+
+ Examples for syntax `rgba(, , , )`:
+
+ - `rgba(128, 128, 128, 0.1)`
+ - `rgba(128, 128, 128, 0.3)`
+ - `rgba(255, 165, 0, 0.1)`
+
+
+- `r.rmarkdown.preview.autoRefresh`: Enable automatic refresh of R Markdown
+ preview on file update.
+
+## Language server settings
+
+The following settings could be set up to deviate from the default behavior:
+
+- `r.lsp.enabled`: Enable the R language server (default).
+- `r.executablePath`: Path to the vanilla R binary used to launch the R Language
+ Server and other background processes. Examples: `/usr/bin/R`
+ (Linux/macOS), `C:\\Program Files\\R\\R-4.1.0\\bin\\x64\\R.exe` (Windows). If
+ the setting is left blank (default), then the R path will be detected from
+ the `PATH` environment variable and Windows registry. It should be _vanilla_ R
+ rather than an alternative console.
+- `r.lsp.args`: The command line arguments to use when launching R Language
+ Server. Example: `--vanilla` to disable loading startup scripts such as
+ `.Rprofile` and `Rprofile.site`.
+- `r.lsp.debug`: Enable debugging traces. Defaults to `false`. Set this to
+ `true` if you are having trouble getting the Language Server working.
+- `r.lsp.diagnostics`: Enable linting of R code, using the
+ [lintr](https://github.com/jimhester/lintr) package. Defaults to `true`. To
+ disable this, you must have at least version 0.2.7 of the R Language Server
+ installed.
diff --git a/website/docs/configuration/keyboard-shortcuts.md b/website/docs/configuration/keyboard-shortcuts.md
new file mode 100644
index 000000000..7147d90c0
--- /dev/null
+++ b/website/docs/configuration/keyboard-shortcuts.md
@@ -0,0 +1,183 @@
+# Keyboard shortcuts
+
+To learn how to edit your keybindings, see [Keyboard shortcuts for Visual Studio Code](https://code.visualstudio.com/docs/configure/keybindings).
+
+The easiest way to edit your keybindings is to open the Keyboard Shortcuts editor with `ctrl+k ctrl+s` (or `⌘K ⌘S` on macOS) and then click the icon in the top right corner to open and edit the `keybindings.json` file directly.
+
+## Suggested keyboard shortcuts
+
+If you have used RStudio, you may want to add some of these keyboard shortcuts to your
+`keybindings.json` file to make your experience more similar.
+
+```json
+[
+ // Restart R terminal
+ {
+ "key": "ctrl+shift+f10",
+ "command": "runCommands",
+ "args": {
+ "commands": [
+ {
+ "command": "workbench.action.terminal.kill",
+ "when": "editorTextFocus && editorLangId == 'r' || editorTextFocus && editorLangId == 'rmd'"
+ },
+ {
+ "command": "r.createRTerm"
+ }
+ ]
+ }
+ },
+ {
+ "key": "alt+-",
+ "command": "type",
+ "when": "editorLangId == r && editorTextFocus || editorLangId == rmd && editorTextFocus",
+ // if you want using quarto, try this
+ // "when": "editorLangId =~ /r|rmd|qmd/ && editorTextFocus",
+ "args": {"text": " <- "}
+ },
+ {
+ "key": "ctrl+shift+m",
+ "command": "type",
+ "when": "editorLangId == r && editorTextFocus || editorLangId == rmd && editorTextFocus",
+ "args": {"text": " %>% "}
+ },
+ {
+ "key": "ctrl+shift+m",
+ "command": "-workbench.actions.view.problems"
+ },
+
+ // input indicative of r markdown code chunk
+ {
+ "key": "ctrl+shift+i",
+ "command": "editor.action.insertSnippet",
+ "when": "editorTextFocus && editorLangId == 'rmd'",
+ "args": {
+ "snippet": "```{r}\n${TM_SELECTED_TEXT}$0\n```"
+ },
+ "label": "input indicative of r markdown code chunk"
+ },
+
+ // you can also input indicative of code chunk in `r` file by inserting "# %% ":
+ // specifics in `https://github.com/REditorSupport/vscode-R/pull/662`
+ {
+ "key": "ctrl+shift+i",
+ "command": "editor.action.insertSnippet",
+ "when": "editorTextFocus && editorLangId == 'r'",
+ "args": {
+ "snippet": "$LINE_COMMENT %% "
+ },
+ "label": "input indicative of code chunk"
+ },
+
+ // open help panel for selection
+ {
+ "key": "f1",
+ "command": "r.helpPanel.openForSelection",
+ "when": "editorTextFocus && editorLangId == 'r' || editorTextFocus && editorLangId == 'rmd'"
+ },
+
+ // RStudio keybinding for R Package development
+ {
+ "key": "ctrl+shift+b",
+ "command": "r.install",
+ "when": "resourceLangId == 'r'"
+ },
+ {
+ "key": "ctrl+shift+e",
+ "command": "r.check",
+ "when": "resourceLangId == 'r'"
+ },
+ {
+ "key": "ctrl+shift+t",
+ "command": "r.test",
+ "when": "resourceLangId == 'r'"
+ },
+ {
+ "key": "ctrl+shift+d",
+ "command": "r.document",
+ "when": "resourceLangId == 'r'"
+ },
+ {
+ "key": "ctrl+shift+l",
+ "command": "r.loadAll",
+ "when": "resourceLangId == 'r'"
+ }
+]
+
+```
+
+## Removed keyboard shortcuts
+
+These keyboard shortcuts used to be set by this extension, but were removed
+because they conflicted with default Visual Studio Code shortcuts. If you would
+like to restore them, add these to `keybindings.json`:
+
+```json
+[
+ {
+ "command": "r.nrow",
+ "key": "Ctrl+1",
+ "when": "editorTextFocus && editorLangId == 'r'"
+ },
+ {
+ "command": "r.length",
+ "key": "Ctrl+2",
+ "when": "editorTextFocus && editorLangId == 'r'"
+ },
+ {
+ "command": "r.head",
+ "key": "Ctrl+3",
+ "when": "editorTextFocus && editorLangId == 'r'"
+ },
+ {
+ "command": "r.thead",
+ "key": "Ctrl+4",
+ "when": "editorTextFocus && editorLangId == 'r'"
+ },
+ {
+ "command": "r.names",
+ "key": "Ctrl+5",
+ "when": "editorTextFocus && editorLangId == 'r'"
+ }
+]
+```
+
+## Creating keybindings for R commands
+
+There are 3 ways you can use extension functions to create keybindings that run
+R commands in the terminal:
+
+1. `r.runCommand` to make a keybinding to run any R expression.
+2. `r.runCommandWithEditorPath` to create a keybinding for an R expression where
+ the placeholder value `$$` is interpolated with the current file path.
+3. `runCommandWithSelectionOrWord` to create a keybinding for an R expression
+ where `$$` is interpolated with the current selection or the current word the
+ cursor is on.
+
+Here are some example entries from `keybindings.json`:
+
+```json
+[
+ {
+ "description": "run drake::r_make()",
+ "key": "ctrl+;",
+ "command": "r.runCommand",
+ "when": "editorTextFocus",
+ "args": "drake::r_make()"
+ },
+ {
+ "description": "load drake target at cursor",
+ "key": "ctrl+shift+;",
+ "command": "r.runCommandWithSelectionOrWord",
+ "when": "editorTextFocus",
+ "args": "drake::loadd($$)"
+ },
+ {
+ "description": "knit to html",
+ "key": "ctrl+i",
+ "command": "r.runCommandWithEditorPath",
+ "when": "editorTextFocus",
+ "args": "rmarkdown::render(\"$$\", output_format = rmarkdown::html_document(), output_dir = \".\", clean = TRUE)"
+ }
+]
+```
diff --git a/website/docs/configuration/r-options.md b/website/docs/configuration/r-options.md
new file mode 100644
index 000000000..dc3108884
--- /dev/null
+++ b/website/docs/configuration/r-options.md
@@ -0,0 +1,8 @@
+# R options (removed)
+
+::: warning Removed in vscode-R 3.0.0
+The R-side `vsc.*` options documented on this page are no longer read by
+vscode-R 3.0.0. Use the corresponding `r.*` VS Code settings described on the
+[Extension settings](./extension-settings.md)
+page instead.
+:::
diff --git a/website/docs/configuration/recommended-extensions.md b/website/docs/configuration/recommended-extensions.md
new file mode 100644
index 000000000..0700ef734
--- /dev/null
+++ b/website/docs/configuration/recommended-extensions.md
@@ -0,0 +1,132 @@
+# Recommended extensions and configuration
+
+In addition to the setup detailed in the
+[Getting Started](../getting-started.md)
+page, or the configuration available in the
+[settings page](./extension-settings.md),
+users may be interested in further configuration to match the experience of
+other editors like RStudio. Many of these are features that vscode-R does not
+directly control, but are possible to handle through VSCode and the libraries
+vscode-R interfaces with. We suggest some of those options here.
+
+## Formatting
+
+User's `settings.json` file in VSCode can be configured to format on save:
+
+```json
+{
+ "[r]": {
+ "editor.defaultFormatter": "REditorSupport.r",
+ "editor.formatOnSave": true
+ },
+ "[rmd]": {
+ "editor.defaultFormatter": "REditorSupport.r",
+ "editor.formatOnSave": true
+ }
+}
+```
+
+## Linting
+
+It's also useful to set some sensible defaults for the R linter. These can be
+configured in a `.lintr` file at your computer's `HOME` directory (or
+`USERPROFILE` if you are on Windows), or in your current project.
+
+The following example allows commented code, which is often a necessity, and
+prevents checking if objects are in global scope, since this can throw
+[extraneous errors](https://github.com/r-lib/lintr/issues/482) if functions from
+libraries are called.
+
+```dcf
+linters: with_defaults(
+ object_usage_linter = NULL,
+ commented_code_linter = NULL)
+```
+
+See the
+[`lintr` docs](https://lintr.r-lib.org/articles/lintr.html)
+for more configuration details and rules.
+
+## Dots in variable/function names
+
+Treat `names.like.this` as one word for selection.
+
+In VSCode's `settings.json`, add the following:
+
+```json
+"[r]": {
+ "editor.wordSeparators": "`~!@#%$^&*()-=+[{]}\\|;:'\",<>/?"
+}
+```
+
+## C/C++
+
+We recommend the
+[C/C++](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools)
+VSCode extension with the following settings to write Rcpp:
+
+In `.vscode/c_cpp_properties.json`:
+
+```json
+{
+ "configurations": [
+ {
+ "name": "Linux",
+ "includePath": [
+ "${workspaceFolder}/**",
+ "${env:HOME}/R/x86_64-pc-linux-gnu-library/3.6/Rcpp/include",
+ "/usr/share/R/include"
+ ],
+ "defines": [],
+ "compilerPath": "/usr/bin/gcc",
+ "cStandard": "c11",
+ "cppStandard": "c++17",
+ "intelliSenseMode": "clang-x64"
+ }
+ ],
+ "version": 4
+}
+```
+
+`.clang-format`:
+
+```yaml
+---
+Language: Cpp
+BasedOnStyle: LLVM
+Standard: Cpp11
+ReflowComments: false
+---
+```
+
+In your `settings.json`:
+
+```json
+"C_Cpp.commentContinuationPatterns": [
+ "/**",
+ "//'"
+]
+```
+
+See demonstration and more tooling at
+[renkun-ken/vscode-rcpp-demo](https://github.com/renkun-ken/vscode-rcpp-demo)
+
+## Path Autocomplete
+
+We recommend the VSCode extension
+[Path Autocomplete](https://marketplace.visualstudio.com/items?itemName=ionutvmi.path-autocomplete)
+with the following configuration in `settings.json` to enable autocompletion for
+file names:
+
+```json
+"path-autocomplete.pathMappings": {
+ "/": "/",
+ "./": "${folder}"
+}
+```
+
+## Error Lens
+
+You can use the
+[Error Lens](https://marketplace.visualstudio.com/items?itemName=usernamehw.errorlens)
+extension for more visible error messages.
diff --git a/website/docs/configuration/renv.md b/website/docs/configuration/renv.md
new file mode 100644
index 000000000..8b9193398
--- /dev/null
+++ b/website/docs/configuration/renv.md
@@ -0,0 +1,81 @@
+# Working with renv-enabled projects
+
+[renv](https://rstudio.github.io/renv/articles/renv.html) is a package that helps manage library paths to help isolate your project’s R dependencies for better reproducibility of the project.
+
+Since `renv` uses a private library per project, vscode-R features will not work
+if their required R packages are unavailable in the active project library.
+There are two general approaches to this problem.
+
+### Option 1: Declare explicit vscode-R dependencies
+
+Within each of your `renv` enabled projects, consider adding a simple `scaffolding.R` (or whatever you want to call it) file that explicitly declares your vscode-R dependencies. In most cases, all you would need is:
+
+```r
+library(languageserver)
+library(jgd) # optional
+library(httpgd) # optional
+library(vscDebugger) # optional
+```
+
+Do not add `library(sess)` to this scaffolding file. vscode-R ships and manages
+the matching `sess` version itself. In a managed terminal it prompts before
+installing or updating `sess` in the active library. When attaching an existing
+external R session, the generated attach script installs or updates the bundled
+version when needed without a separate prompt.
+
+Note that you don't actually have to ever call this `scaffolding.R` file as part of your workflow. But by naming these packages explicitly in a project script, you ensure that `renv` will configure your project dependencies correctly. Moreover, this ensures that they will be added to `renv`'s [global cache](https://rstudio.github.io/renv/articles/package-install.html#cache), which reduces re-installation overhead across your other VS Code + `renv` projects.
+
+
+### Option 2: Link a standalone library
+
+_Note: Some users have reported that this approach no longer works. See discussion in [this thread](https://github.com/rstudio/renv/issues/1129#issuecomment-2248960686)._
+
+Some users might find it useful to maintain a standalone, minimal user library to provide these packages.
+
+Suppose we want to maintain such a library at `~/R/vscode-R` using renv.
+
+```r
+renv::init(project = "~/R/vscode-R")
+```
+
+Start R from the folder (`path.expand("~/R/vscode-R")`) and install required packages:
+
+```r
+renv::install(c("languageserver"))
+```
+
+Print the library path:
+
+```r
+renv::paths$library()
+```
+
+```
+[1] "/Users/user/R/vscode-R/renv/library/R-4.2/x86_64-apple-darwin17.0"
+```
+
+Write the library path in VS Code settings:
+
+```json
+"r.libPaths": [
+ "/Users/user/R/vscode-R/renv/library/R-4.2/x86_64-apple-darwin17.0"
+]
+```
+
+Then the following R processes running in the background will be launched with the configured library paths appended to `.libPaths()` on startup:
+
+* R language server
+* R help server
+* R aliases
+
+And the code editing features and help viewer could continue to work without necessary packages being installed into the project library.
+
+---
+
+When working with `Rcpp`, a good demo is provided at [vscode-rcpp-demo](https://github.com/renkun-ken/vscode-rcpp-demo). If you're working with `renv`, the `includePath` property in `.vscode/c_cpp_properties.json` needs to manually be pointed at your project's `R_LIBS_USER` directory. Exempli gratia:
+
+```
+/Users/user/Library/Caches/org.R-project.R/R/renv/library/vscode-rcpp-demo-e5908179/macos/R-4.4/aarch64-apple-darwin20
+# becomes
+/Users/user/Library/Caches/org.R-project.R/R/renv/library/vscode-rcpp-demo-e5908179/macos/R-4.4/aarch64-apple-darwin20/*/include/
+```
diff --git a/website/docs/contributing.md b/website/docs/contributing.md
new file mode 100644
index 000000000..dd3049aba
--- /dev/null
+++ b/website/docs/contributing.md
@@ -0,0 +1,73 @@
+# Contributing
+
+Contributions are always welcome!
+
+## Developing the extension
+
+The development setup, debugging, formatting, linting, and testing instructions
+live with the source in
+[CONTRIBUTING.md](https://github.com/REditorSupport/vscode-R/blob/main/CONTRIBUTING.md).
+In short:
+
+```sh
+git clone https://github.com/REditorSupport/vscode-R.git
+cd vscode-R
+pnpm install --frozen-lockfile # install required packages for vscode-R
+code . # run VS Code
+```
+
+Then test your changes:
+
+- In VS Code: 'File' -> 'Open Folder...' and select 'vscode-R' (the directory
+ with your edits)
+- Select **Launch Extension** in Run and Debug, then press `F5`
+- A new VS Code window should open, with '[Extension Development Host]' in the
+ title bar. This is running your modified version of vscode-R
+
+## Editing this documentation
+
+This site is built with [VitePress](https://vitepress.dev/) from the Markdown
+files in the
+[`website/docs`](https://github.com/REditorSupport/vscode-R/tree/main/website/docs)
+directory. Every documentation page has an **Edit this page on GitHub** link at
+the bottom.
+
+To preview the site locally:
+
+```sh
+cd website
+pnpm install --frozen-lockfile
+pnpm run docs:dev
+```
+
+`website` is a standalone pnpm project with its own lockfile, so it does not
+affect the dependencies of the extension itself.
+
+## Pull Request
+
+- Fork it (via GitHub) in your account
+- Add your project URL
+
+```sh
+git remote add mine https://github.com/yourname/vscode-R.git
+```
+
+- Create your feature branch
+
+```sh
+git checkout -b my-new-feature
+```
+
+- Commit your changes
+
+```sh
+git commit -am 'Add some feature'
+```
+
+- Push to the branch
+
+```sh
+git push mine my-new-feature
+```
+
+- Create new Pull Request (via GitHub)
diff --git a/website/docs/faq.md b/website/docs/faq.md
new file mode 100644
index 000000000..95a83ba51
--- /dev/null
+++ b/website/docs/faq.md
@@ -0,0 +1,5 @@
+# FAQ
+
+The following are the solutions to the most frequently asked questions in the issues. The solutions are mostly contributed by users.
+
+### How can I work with R provided by Conda environment under remote development?
diff --git a/website/docs/features/interactive-viewers.md b/website/docs/features/interactive-viewers.md
new file mode 100644
index 000000000..80aa579b9
--- /dev/null
+++ b/website/docs/features/interactive-viewers.md
@@ -0,0 +1,82 @@
+# Interactive viewers
+
+With R session watcher enabled, multiple types of viewers are supported to
+display tabular data, graphics, [htmlwidgets](http://www.htmlwidgets.org/) and
+[shiny](https://shiny.rstudio.com/) apps.
+
+## Data viewer
+
+`View()` will open a tab to view the object.
+
+| Object type | Viewer |
+| --- | --- |
+| `data.frame` or `matrix` | paged table viewer |
+| [Apache Arrow](https://arrow.apache.org/docs/r/) table | paged table viewer |
+| Polars DataFrame | paged table viewer |
+| `list` | JSON viewer |
+| others, including environments | R code viewer |
+
+### Table viewer
+
+Rows are loaded on demand as you scroll. The table viewer supports sorting,
+column filters, row counts, full-value tooltips, and a column panel for
+searching, showing, hiding, pinning, and reordering columns. Calling `View()` on
+the same object again refreshes the existing tab and preserves its layout when
+the column names, order, and types are unchanged.
+
+
+
+### List viewer
+
+The list viewer supports collapsing nodes.
+
+
+
+## Plot viewer
+
+The plot viewer supports JGD, httpgd, and a responsive standard SVG/PNG backend.
+For more details, go to
+[Plot viewer](./plot-viewer.md).
+
+
+
+## Webpage viewer
+
+In R, an htmlwidget is written in HTML and can be presented in a web browser.
+For example, the following image demonstrates an interactive graphics created by
+[plotly](https://plotly.com/r/):
+
+
+
+## Browser viewer
+
+Interactive shiny apps can be displayed in VS Code. The following is an example
+created by
+
+```r
+shiny::runExample("01_hello")
+```
+
+
+
+For security reasons, the VS Code WebView has security limitations on its
+capability of accessing external resources over a network. For more details,
+visit
+[WebView API](https://code.visualstudio.com/api/extension-guides/webview#security).
+
+If you encounter a problem loading a webpage in a browser viewer, you may try
+viewing the web page in an external web browser.
+
+## Help viewer
+
+The web pages in R documentation can be viewed in the help viewer. Syntax
+highlighting and link navigation are supported.
+
+Help viewer could be revealed via `?symbol` in R terminal, or from the
+[Help pages viewer](./sidebar.md#help-pages-viewer)
+in the
+[sidebar](./sidebar.md),
+or via command `R: Open help for selection` in either command palette or context
+menu in the editor.
+
+
diff --git a/website/docs/features/language-service.md b/website/docs/features/language-service.md
new file mode 100644
index 000000000..86c6ced38
--- /dev/null
+++ b/website/docs/features/language-service.md
@@ -0,0 +1,214 @@
+# R Language Service
+
+The
+[R language server](https://github.com/REditorSupport/languageserver#servers-implemented)
+implements the
+[Language Server Protocol](https://microsoft.github.io/language-server-protocol/specifications/specification-current/)
+and provides a set of language analysis features such as completion, providing
+function signatures, extended function documentation, locating function
+implementations, occurrences of a symbol or object, and code diagnostics and
+formatting. The R language server statically analyzes R code, and vscode-R
+interfaces with it to provide the core of this extension's functionality.
+
+The R language server is implemented by the
+[languageserver](https://github.com/REditorSupport/languageserver) package which
+performs static code analysis with the latest user documents in `R` and `Rmd`
+languages. Therefore, it does not rely on an active R session and thus does not
+require the code to be executed.
+
+To install the package from CRAN:
+
+```r
+install.packages("languageserver")
+```
+
+To experience the latest features, install the package from GitHub:
+
+```r
+remotes::install_github("REditorSupport/languageserver")
+```
+
+### Settings
+
+See the
+[extension settings page](../configuration/extension-settings.md)
+for information on configuring the language server.
+
+## Features
+
+The R language server contributes the following features.
+
+- [Smart editing](#smart-editing)
+ - [Autocompletion while typing](#autocompletion)
+ - [Function signature preview while typing](#signature-preview)
+ - [Extended documentation on hover](#hover)
+ - [Diagnose potential errors and unreliable code with `lintr`](#diagnostics)
+ - [Format with `styler` for clean and consistent code](#formatting)
+ - [Symbol renaming, powered up](#rename-symbol)
+- [Document organization](#document-organization)
+ - [Symbol highlighting on cursor focus](#symbol-highlight)
+ - [Structure-aware document selection](#document-selection)
+ - [Code sections and folding](#code-sections)
+ - [Call hierarchy analysis](#call-hierarchy)
+- [Document navigation](#document-navigation)
+ - [Navigate through all R objects in workspace](#document-and-workspace-symbols)
+ - [Find all occurrences of an object](#find-all-occurrences)
+ - [Document names are links](#document-links)
+ - [See implementation](#go-to-definition)
+- [Miscellaneous](#miscellaneous)
+ - [Color picker](#color-picker)
+
+---
+
+## Smart editing
+
+---
+
+### Autocompletion
+
+The R language server provides global and scope-based autocompletion. You can
+scroll through the suggested signatures with the arrow keys.
+
+Global autocompletion:
+
+
+
+Scope-based autocompletion:
+
+
+
+The R language server currently does not provide completion for filenames; see
+this
+[comment.](../configuration/recommended-extensions.md#path-autocomplete).
+
+### Signature preview
+
+The R language server provides popups of function signatures and their short
+descriptions as you type, which can save a few calls to `help()`.
+
+
+
+
+
+### Hover
+
+A larger preview of the documentation is shown when users mouse over R symbols:
+
+
+
+### Diagnostics
+
+The language server provides code diagnostics through the
+[lintr](https://lintr.r-lib.org/) package in R. See
+[here](../configuration/code-linting.md)
+for configuration.
+
+
+
+### Formatting
+
+The language server provides code formatting through the
+[`styler`](https://github.com/r-lib/styler) package in R. See
+[here](https://github.com/REditorSupport/languageserver#customizing-formatting-style)
+for configuration.
+
+
+
+
+
+### Rename symbol
+
+Symbol renaming through the language server allows you to group renaming actions
+together, letting you refactor code more easily and discard a change on the fly
+if need be.
+
+
+
+---
+
+## Document organization
+
+---
+
+### Symbol highlight
+
+When the cursor is inside of a symbol, all occurrences of that symbol within the
+document are highlighted.
+
+
+
+### Document selection
+
+You can expand selections through `Shift+Alt+RightArrow`. Selections are
+expanded in steps, following the boundaries of each containing R expression.
+
+
+
+### Code sections
+
+The R language server informs VSCode of code sections, or blocks of code that
+form coherent R expressions, which can be navigated through the outline or the
+panel header.
+
+
+
+Sections can also be folded, allowing users to organize the current editor:
+
+
+
+### Call hierarchy
+
+The R language server's static analysis also allows users to see the call
+sequence and hierarchy within an R expression.
+
+
+
+---
+
+## Document navigation
+
+---
+
+### Document and workspace symbols
+
+Users can navigate through the document outline or search for symbols by
+prepending an `@` symbol in the search bar.
+
+
+
+### Find all occurrences
+
+`Ctrl+Click`ing on a user-created R object, pressing `Shift+F12` while the
+cursor is focused on any object, or right-clicking and then selecting
+`Go To References` will open a popup showing all of the uses of the object
+within the current document.
+
+
+
+### Document links
+
+`Ctrl+Click` on a file path takes the user to the referenced document.
+
+
+
+### Go to definition
+
+`Ctrl+Click`ing on an R symbol, pressing `F12` while the cursor is focused on a
+symbol, or right-clicking and then selecting `Go To Definition` will bring up a
+function's implementation.
+
+
+
+---
+
+## Miscellaneous
+
+---
+
+### Color picker
+
+Strings of text that are recognized as R colors are rendered with a color
+decoration. Hovering over the decoration brings out a color picker popup that
+can be used to adjust the referenced color.
+
+
diff --git a/website/docs/features/live-share.md b/website/docs/features/live-share.md
new file mode 100644
index 000000000..e485bb994
--- /dev/null
+++ b/website/docs/features/live-share.md
@@ -0,0 +1,6 @@
+# Live Share collaboration (removed)
+
+::: warning Removed in vscode-R 3.0.0
+vscode-R's Live Share integration was removed in version 3.0.0. The associated
+commands, sidebar view, and `r.liveShare.*` settings are no longer available.
+:::
diff --git a/website/docs/features/plot-viewer.md b/website/docs/features/plot-viewer.md
new file mode 100644
index 000000000..fefe2aeb1
--- /dev/null
+++ b/website/docs/features/plot-viewer.md
@@ -0,0 +1,59 @@
+# Plot viewer
+
+Plots from an attached R session can be displayed in a VS Code editor tab. Use
+`r.plot.backend` to select one of four modes:
+
+- `auto` (default): use JGD if installed, otherwise httpgd if installed,
+ otherwise the standard viewer
+- `jgd`: use the [JGD](https://github.com/REditorSupport/jgd) graphics device
+- `httpgd`: use the [httpgd](https://github.com/nx10/httpgd) graphics device
+- `standard`: use the built-in responsive plot viewer
+
+Backend changes take effect without reloading VS Code. vscode-R warns and falls
+back when the requested package is unavailable.
+
+JGD is lightweight, has no external R-package dependencies, and is usually
+simpler to install. httpgd has a mature, feature-rich SVG viewer, but a larger
+compiled dependency footprint. If you are unsure which optional backend to
+install, start with JGD.
+
+## Standard viewer
+
+The standard backend records the current R plot and re-renders it to fit the
+viewer whenever the panel is resized. It uses crisp SVG output when the
+`svglite` R package is installed and falls back to PNG otherwise.
+
+Use `r.plot.format` to request `"svglite"` or `"png"`. The
+`r.plot.devArgs` setting supplies additional graphics-device arguments, but the
+responsive viewer manages width and height itself.
+
+To use R's native graphics window instead, disable the session watcher with
+`r.sessionWatcher`. This also disables the other features that require an
+attached R session.
+
+## JGD viewer
+
+Install the `jgd` R package to use the lightweight JGD backend:
+
+```r
+install.packages("jgd")
+```
+
+JGD supports plot history, navigation, zoom, and export. Configure the maximum
+history size with `r.plot.jgd.historyLimit`, and the default export dimensions
+and resolution with `r.plot.jgd.exportWidth`, `r.plot.jgd.exportHeight`, and
+`r.plot.jgd.exportDpi`.
+
+## httpgd viewer
+
+Install `httpgd` to use its SVG-based interactive viewer:
+
+```r
+install.packages("httpgd")
+```
+
+Select it explicitly with `"r.plot.backend": "httpgd"`, or leave the backend
+as `auto`. The viewer supports resizing, themes, plot history, hiding, zooming,
+and export.
+
+
diff --git a/website/docs/features/r-interactive.md b/website/docs/features/r-interactive.md
new file mode 100644
index 000000000..12f2281c1
--- /dev/null
+++ b/website/docs/features/r-interactive.md
@@ -0,0 +1,262 @@
+# R Interactive
+
+R Interactive runs R independently of the VS Code extension host. Each session has its own Interactive window, execution queue, environment, retained transcript, plot service, and private agent. Reloading VS Code, closing a tab, or losing an SSH connection does not terminate R.
+
+::: warning Experimental
+R Interactive was introduced in vscode-R 3.2.0 ([PR #1805](https://github.com/REditorSupport/vscode-R/pull/1805)). The feature and its `r.interactive.*` settings may change in future releases.
+:::
+
+## Requirements and setup
+
+Use **VS Code 1.101.0 or newer**. R Interactive currently supports Linux and macOS; its native console bridge does not support Windows. Existing R terminal workflows remain available.
+
+For Remote SSH, install this extension **on the remote host**. R, its packages, optional executables, and session storage must be available on that host. For local use, the same requirements apply to your computer.
+
+The R host needs:
+
+- R, plus either compatible pre-built sess/dependency packages or a C compiler capable of building R packages (`r-base-dev` and `build-essential` on Debian/Ubuntu).
+- The session agent automatically uses the extension host's bundled runtime: VS Code's Electron runtime in Node mode on desktop, or VS Code Server's Node runtime remotely. A separate Node.js installation is optional.
+- `tmux` is optional. On Linux, the default supervisor uses tmux when available and otherwise starts an independent detached process. `systemd --user` is another configurable option.
+- R packages `processx`, `later`, `jsonlite`, and `rstudioapi`. Install `languageserver` for language features, `jgd` and `systemfonts` for JGD graphics, `svglite` for the static fallback, and `htmlwidgets`/`htmltools` for HTML output.
+- `arf` is optional. Creating a headless arf session requires an executable on the R host; plain R requires no arf installation. Connecting to an already-running arf uses its socket and does not require arf on the extension host's PATH. The provider contract was exercised with arf 0.5.1.
+
+For example, run in the R installation used on the server:
+
+```r
+install.packages(c(
+ "processx", "later", "jsonlite", "rstudioapi", "languageserver",
+ "jgd", "systemfonts", "svglite", "htmlwidgets", "htmltools"
+))
+```
+
+### Agent runtime
+
+The experimental `r.interactive.nodePath` setting provides an optional standalone Node.js override for compatible IDEs where the automatic runtime is unavailable, such as some code-server, OpenVSCode Server, or VSCodium configurations. Its default is empty, which selects the current extension host's runtime. Set it to a Node.js 18+ executable name on the R host's PATH or a path such as `/usr/bin/node`; `~`, `${userHome}`, and `${workspaceFolder}` are supported. An invalid explicit override is reported and must be repaired or cleared. The override is excluded from Settings Sync and restricted to trusted workspaces.
+
+Runtime availability and version (Node.js 18+) are checked before installation or restart, so a failed check leaves the current R process running. If an editor update removes the automatic runtime, reload VS Code to select its current executable. Reconnecting to an existing agent does not launch or replace its runtime; new and restarted sessions reread `r.interactive.nodePath`.
+
+### R packages and project libraries
+
+The extension installs its bundled `sess` into a private, content-addressed library. It does not replace your installed `sess` package. If the source build fails, including when build tools are missing, it tries a compiler-free package from [R-universe](https://reditorsupport.r-universe.dev/sess). Installation diagnostics appear in the **R Interactive** output channel.
+
+On macOS, the fallback uses R's matching binary repository. On Ubuntu, it uses a repository matching the host's codename, architecture, and R version. It never assumes that an Ubuntu binary is compatible with another Linux distribution. Dependencies for a binary fallback come from the matching R-universe repositories. No global repository settings are changed.
+
+The compiler-free fallback requires a published `sess` build compatible with the native Interactive bridge. A matching package version alone is insufficient; the extension checks the compatibility marker, required functions, and registered native console routines. Until a compatible build is published for your host, building the bundled package requires a C compiler. Missing or incompatible binaries produce an installation error with diagnostics in **R Interactive**.
+
+That private library is used only to load the bridge; it is not added to your session's `.libPaths()` or `R_LIBS`. Package installation follows ordinary R behavior: `install.packages()` defaults to the first library in `.libPaths()`, usually your user library. Startup files can customize that order, and an explicit `lib=` still takes precedence. The extension does not force a user-library destination over a project library.
+
+Start the session in the renv project directory to load its `.Rprofile` normally. An activated renv project keeps its project library, installation destination, and package isolation; the private `sess` is not added to `renv::snapshot()` lockfiles. IDE support namespaces and the plot device load explicitly, preferring available project versions of their dependencies and using normal host libraries as a fallback. This does not make unrelated packages from those host libraries visible to the project. Install analysis packages in the project as usual, and record them with renv. As in any R process, an already-loaded dependency keeps its loaded version until restart.
+
+Sessions created by older extension builds retain their original library order. Start a new session after updating to use this behavior. Restarting also applies it, but clears in-memory R objects; switching directories in an existing R session does not itself activate a different renv project.
+
+### Process supervision
+
+Typical remote settings:
+
+```json
+{
+ "r.interactive.arfPath": "/home/me/.cargo/bin/arf",
+ "r.interactive.supervision": "auto",
+ "r.interactive.restore": true,
+ "r.interactive.executionTarget": "auto"
+}
+```
+
+Executable paths, storage location, supervision, graphics backend, and output/journal/asset size limits are excluded from VS Code Settings Sync by default because they depend on the R host. Execution target, table presentation, automatic reconnection, and history-length preferences can still sync.
+
+Use the paths appropriate for your server. Linux `auto` prefers tmux when its executable is on the extension host's PATH. If tmux is missing or not executable, it uses a detached agent and records the fallback in the **R Interactive** output channel and agent log. Session Details shows **Independent process**. macOS `auto` also uses a detached agent. Both plain R and managed arf support this fallback with the same Interactive features.
+
+Selecting `tmux` or `systemd` explicitly requires `tmux` or `systemd-run` on the R host. Missing executables produce an actionable error before installing a runtime or stopping the current R process for restart. Install the selected supervisor or change `r.interactive.supervision` to `auto` or `detached`. New sessions and restarts use the current setting; merely reconnecting leaves the existing supervisor unchanged. If an installed supervisor fails to launch (for example, a systemd user service is unavailable), the error includes its diagnostics. The extension does not retry with another supervisor after a launch attempt, which could create duplicate R processes.
+
+Detached launch goes through a short-lived bootstrap so the agent leaves the editor's process tree before launch completes; VS Code debugger auto-attach settings are removed. It survives VS Code reload/exit and an SSH connection closing, but server policies that terminate a user's processes at logout can still stop it. User systemd services also depend on the server's login/linger policy. No option preserves in-memory R objects across a host reboot or termination of the R process.
+
+## Start a session
+
+Run **R: New Persistent Interactive Session**, choose **R** or **arf**, and name the session. Each session opens its own Interactive window; select it in **R → Interactive Sessions** to return to it. Plain R does not require arf. Multiple sessions execute concurrently; each R process runs submitted cells serially.
+
+### Connect to an existing arf session
+
+Adoption uses arf's session discovery and IPC socket on the R host. It does not depend on a particular terminal multiplexer or session manager.
+
+1. Start arf in your preferred terminal or session manager as usual.
+2. Run **R: Connect Interactive to Session** and select the discovered arf PID and working directory.
+3. Arf controls permission to execute visible IPC requests. Approve its prompt, or explicitly choose `:ipc send-policy allow` in that arf process if you want unattended editor submissions. The extension does not bypass this policy using silent evaluation.
+4. Name the session. Its independent agent adopts the existing R process and preserves `.GlobalEnv`. An incompatible loaded `sess` is disconnected and unloaded before loading the private bridge; if another package prevents unloading, resolve that dependency in the terminal and reconnect.
+5. Repeat for other arf sessions. Select an entry in **R → Interactive Sessions** to switch the active Interactive window and workspace viewer.
+
+The agent itself runs under the separately selected supervisor (`tmux`, `systemd`, or a detached process). Stopping your original arf process ends its R session. Stopping the agent interrupts editor integration; it is not a checkpoint of the R heap. If an adopted arf outlives a failed agent, `sess::interactive_stop()` restores its terminal callbacks so that it can be adopted again.
+
+### Configure managed arf sessions
+
+The provider picker shows **R** and **arf**, each with its resolved executable path on a second line. **arf** appears only when `r.interactive.arfPath` resolves to an executable file on this host (the remote server with Remote SSH). Otherwise, **Configure arf…** opens its setting without creating a session. Install arf separately and configure its path, or choose **R** with the same persistence and multi-session controls. The setting accepts names on PATH, absolute or workspace-relative paths, `~/`, `${userHome}`, and `${workspaceFolder}`. Configured paths containing spaces do not need quotes. Changing the setting takes effect the next time the picker opens; shell aliases are not executables.
+
+New arf sessions save their resolved absolute executable path, so a later PATH change does not break restart. Restart checks that saved path, then the current setting if the executable moved, before stopping R. If neither is usable, it explains how to configure arf and leaves the current session running.
+
+## Execution and editor behavior
+
+### Session controls
+
+- **R: Open Interactive Session** opens the session picker when run from the Command Palette. The picker checks saved agents without taking control and shows live status, provider, PID, working directory, and a short session ID. Unavailable agents are omitted, while their saved history remains on disk. The picker also offers **New persistent R session**. Selecting a session in the tree opens that session directly. Cancelling the picker leaves existing sessions unchanged.
+- The R session button in the Interactive toolbar shows the session name and live state. The kernel chooser uses a compact version/provider/PID description and a second line for the working directory, host, and supervision. VS Code also uses that short description as the button tooltip; it does not expose a separate tooltip or arbitrary multiline descriptions. The full R version, PID, directory, host, supervision, executable, session ID, and controlling/observing status remain available in the status-bar tooltip and **Session… → Session Details**. The presentation refreshes during startup, execution, disconnect, stop, and restart without changing the selected kernel.
+- The status bar shows the selected session, activity, queued cell count, connection state, and observer status. Select it to switch sessions or answer a waiting R input prompt. Right-click a session in **Interactive Sessions** for actions on that specific session, including rename, interrupt, queued-work cancellation, detach, and restart.
+- The **Interactive Sessions** tooltip separates **Connection: Connected · controlling/observing** from process supervision. **Independent process** means R survives VS Code reload/exit; it does not mean the editor is disconnected. Unopened sessions show **Not open in this VS Code window**. Connection/control changes refresh the tooltip, including after reconnecting.
+- Session age appears in the session list, connection/stop pickers, and kernel description as **<1m**, **30m**, **1h**, or **1d**. It refreshes once a minute; the tooltip includes the start time. Age uses the persisted start of the current process generation, so reloading preserves it and restarting resets it. The recorded process exit time keeps a stopped session's lifetime fixed.
+- **R: Stop Selected Interactive Sessions…** in the Command Palette opens a checkbox picker with session names, PIDs, and directories. Use Ctrl/Cmd-click or Shift-click to select entries in **Interactive Sessions**, then click the header's stop icon or right-click **Stop Selected Interactive Sessions…** to stop that selection. With no tree selection, the header icon opens the picker. **R: Stop All Interactive Sessions…**, also in the view's **…** menu, targets running Interactive sessions in the configured registry on this host, including those without open tabs. Both ask once with the target list, retain history, and leave the current editor layout intact. Sessions controlled by another VS Code window are skipped; the result offers **Show Details** for failures. Use **Take Control** explicitly before retrying those sessions. Sessions created or restarted after confirmation opens are not added to its targets.
+- The Interactive toolbar includes **Restart**, **Session…**, **History**, and **Clear Completed**, alongside VS Code's **Interrupt** control. **Session…** opens a searchable action picker for switching/creating sessions, rename/details, queued-work cancellation, input/control, plots/export/asset cleanup, disconnect, and stop. These actions target that window's notebook, even when another session or editor has focus. On narrow windows, VS Code moves excess actions into its toolbar overflow. The controls also work in the fallback R notebook and stay out of other kernels' notebooks.
+- Restart and Stop confirmations name the affected session and explain that in-memory objects will be lost. Restart is available for managed plain R and arf sessions; restart an adopted arf session in its original terminal or session manager, then reconnect. **Disconnect** leaves R running. **Clear Completed** retains active/queued cells, drafts, and saved history.
+- When R stops, the Interactive window shows a **R session stopped** notice, including when R exits itself. Reopening the stopped session restores one notice along with its history. Restart keeps the same Interactive window, its input draft, edited cells, code, and output. A **R session restarted** boundary marks where the fresh process begins; subsequent execution uses that process. Source-document bindings and the existing kernel controls follow the replacement. A failed restart leaves an explanation and the transcript in place so it can be retried.
+- **Search Interactive History** (`Ctrl+Alt+H`, or `Cmd+Alt+H` on macOS) searches admitted code in the session's durable history, including commands older than the restored window. Enter inserts a command into the input for editing and preserves any existing draft. Item buttons copy, run again, or navigate to the original source; the history button loads older matches. Disconnected and older agents use the locally restored history.
+- **New Persistent Interactive Session** focuses the new session's input, preserving drafts in other sessions. Creating a target through **Run Selection** preserves source-editor focus.
+- The cell toolbar provides icons for **Insert Cell Code into Interactive Input**, **Copy Cell Code**, and **Go to Interactive Cell Source**, with tooltips identifying each action. Insert preserves an existing draft; lifecycle notices cannot be inserted as executable R code. **Browse Interactive Plots** searches the plots in the restored transcript by their generating code and opens an enlarged view.
+- **Cancel Queued Interactive Cells** leaves the running cell alone. **Clear Completed Interactive Cells** hides finished cells while preserving drafts, running/queued/uncertain work, and durable history. Hidden cells stay hidden during reconnect to the same view; reopening a detached view restores the history. R process exit automatically cancels undispatched cells.
+- The native VS Code Interactive window provides an R input editor and execution history, without requiring Jupyter. If that window cannot be opened, a native `r-interactive` notebook is used.
+
+### Route code to a session
+
+- Selecting an Interactive session makes existing Run Selection/Line, source, and other R execution commands target it when `executionTarget` is `auto`. **Use Terminal for R Execution** restores terminal routing. Set `executionTarget` to `terminal` to keep terminal routing by default.
+- With the default `executionTarget: auto`, running source code when no execution target is available opens **Run R code**. Choose **New R Interactive window**, **Create R terminal**, or a live persistent session (including discovered arf sessions). The captured code runs after the target is ready. Cancelling leaves the code and cursor unchanged. Rapid submissions share the chooser and terminal startup; multiline terminal submissions remain ordered. A stopped or disconnected Interactive target also opens this chooser. Explicit `terminal` mode retains terminal behavior; explicit `interactive` mode offers Interactive targets only.
+- **Bind Document to Interactive Session** pins a source document to the selected session. Notebook cells and Interactive input are bound automatically. Switching tabs does not redirect an already-bound document's requests.
+- The **Workspace** viewer follows the focused Interactive window or bound source document. Its header identifies the session and PID. Unbound source files keep the last selected session. Background results refresh their own session without changing the selected workspace.
+- Workspace **View**, **Remove**, **Clear**, **Save**, and **Load** target the session displayed when the action starts, including across focus changes during a dialog. Object names containing spaces or quotes are supported. A stopped, restarting, or disconnected session displays its state in the viewer; detaching clears it. Expanded data viewers retain their original session.
+
+### R execution and input
+
+- Code runs in `.GlobalEnv`; visible results update `.Last.value`. Output is streamed during execution. Messages, warnings, errors, and traces are represented separately from ordinary console output. Errors show their message followed by the user calls, omitting the worker, arf transport, and condition-handler scaffolding. Saved R and Jupyter notebooks retain both the message and trace.
+- `readline()`, `scan()`, and `browser()` prompts appear as input requests. Canceling the input box leaves R waiting; **Reply to Interactive Input** opens it again. **Interrupt Interactive Session** signals the R process while preserving the environment when R handles the interrupt.
+- R remains single-threaded. A native call that does not check interrupts may delay cancellation. Arbitrary environment inspection and table queries are not executed concurrently with user code; cached workspace information remains visible while R is busy.
+- A rerun creates a new execution identity and history entry. Submissions with an existing identity are deduplicated. Reconnect never resubmits code automatically. Ambiguous dispatch failures block the queue until completion or process exit establishes what happened.
+- A client control lease prevents two windows from submitting simultaneously. Other clients can observe retained output; **Take Control of Interactive Session** explicitly transfers control.
+
+External terminal output observed through the arf console bridge is retained in terminal-origin history entries. When arf invokes R task callbacks, the completed command can also be recorded. Some arf evaluation paths omit those callbacks; their output is labeled as having unavailable source and is grouped into short output batches. This does not reconstruct exact terminal execution boundaries or provide a second live editor input surface. Arf may reject editor submissions while a terminal user is typing or R is otherwise occupied.
+
+### Language features
+
+- Separate language-server processes serve virtual documents with the session's R executable, library paths, and working directory. Cell and input diagnostics lint the live text with lintr's disk cache disabled, because virtual documents have no corresponding R source file. Blank or whitespace-only Interactive prompts clear diagnostics and ignore late lint replies; nonempty code and source files still receive normal diagnostics. Unsaved notebook cells also use a pathless language-server URI so namespace linters do not try to read a nonexistent file; diagnostics still map to the original cell. Source-file language servers retain the user's cache setting. Live completion and hover use the owning session with short timeouts. The existing source-file language-server configuration remains available.
+- Custom `.lintr` linter lists in cells and inputs require the [pathless-document settings fix in `languageserver`](https://github.com/REditorSupport/languageserver/pull/782). `languageserver` 0.3.20 selects default linters for these documents, even when source files use your configured rules. Updating the extension alone does not fix that package behavior.
+- Function hovers and parameter hints can use the owning session's cached function metadata, including while R is busy. After executing `fun1 <- function(x, y) x + y`, hovering over `fun1` shows its formals, and typing `fun1(` or `fun1(1, ` shows and highlights the corresponding parameter. Hints handle defaults, named arguments, `...`, nested expressions, and quoted names. Source-local definitions and package signatures from languageserver take priority. Session hints are a fallback for simple function names in source documents, notebook cells, and Interactive inputs; they do not evaluate code. Different sessions can define the same name with different signatures.
+
+## Rich outputs
+
+| Output | Behavior |
+| --- | --- |
+| Console, warnings, errors | Incremental output with per-execution limits and explicit truncation notices |
+| Base/grid/ggplot graphics | JGD frames retained by the agent and rendered as scalable SVG; independent font metrics work without a connected editor |
+| Incremental graphics | Recorded execution markers associate updates with their producing cell, including extensions of an existing plot |
+| Plot controls | Compact icons with labels for opening and resizing; **Save…** opens a native VS Code format picker for SVG and PNG |
+| Static fallback | Captured plots when JGD/systemfonts are unavailable or `plotBackend` is `standard` |
+| Data frames and matrices | On-demand inline pages (20/50/100 rows), first/last and page jumps, sorting, column filters/reordering and Reset; an expanded data viewer remains available. Requests stay bound to their originating session |
+| HTML widgets and HTML tags | Sandboxed browser output with copied local dependencies; dependencies remain after the R temporary source is gone |
+| Explicit MIME | `sess::display(x, mime = "text/markdown")`, HTML, and text formats |
+| Live applications | Forwarded loopback URLs opened in a viewer; applications such as Shiny still need their own running server and may occupy the R process |
+
+### Plots
+
+When one cell produces multiple plots, the output uses one paged plot viewer with **Previous plot**, **Plot n of m**, and **Next plot** controls. New plots appear on the latest page until you choose a page. Your choice is retained across output updates and reconnection. **Open**, **Save…**, and **Fit R device** act on the selected page; standard graphics images support Open and Save but have no live resize control. Pagination remains available in saved notebooks and after R stops or restarts. R notebook exports retain the gallery; Jupyter and HTML exports include every plot page.
+
+### Tables
+
+Table headings and values use the same alignment: numbers (including integer64 IDs) are right aligned and text is left aligned. **Text** switches a table to its ordinary R printout; **Table** switches back. The printout uses the object's class printer and the R print options at execution time, so data.table retains its type labels and tibble retains its usual compact printing. Switching does not execute R, and remains available while R is busy or stopped and in saved notebooks. Set `r.interactive.tableView` to `"text"` to use printed output by default, or `"table"` for the paged preview. Per-output choices override that default and survive reconnection. Explicit `print(x)` still produces normal console output.
+
+Printed snapshots require a session started with this extension build; older output explains why Text is unavailable. Snapshots retain at most 256 KiB of printed text, with a truncation notice. If a custom printer fails, the rich table remains available and the Text tooltip explains the failure. Live table paging and the full data viewer still require the original R process.
+
+Data inspection does not initialize or advance R's random-number stream, so opening a table between `set.seed()` and a simulation or train/test split leaves the draws unchanged. Inline tables retain a snapshot of up to **1,000 rows**, reduced to fit **100,000 cells** for wide tables (at least one row). Row subsetting gives data.table snapshots independent columns without a full deep copy. Later `:=`, `setnames()`, and `setorder()` calls do not change those saved rows. Reference assignments remain quiet like the R console; evaluate `DT` or use `DT[, x := value][]` to display the result, or call `View()` / `sess::display()` explicitly.
+
+The saved snapshot is **not a browsing limit**. The inline status initially shows **Saved preview** and the full row count; its tooltip and Text output identify the saved scope, for example **Snapshot: first 1,000 of 832,976,871 rows**. Moving beyond those rows automatically fetches a page from the uncopied original object and changes the status to **Live data**. Once browsing live data, navigation stays live until Reset. Later edits by reference can appear in these pages. The handle retains the original object; assigning a different object to the same variable does not retarget an old viewer.
+
+- Use **First**, **Previous**, **Next**, **Last**, or enter a page number and press **Go** / Enter. Choose **20**, **50**, or **100 rows** per page. Only the current fetched page is kept in the renderer; paging does not accumulate the dataset in browser memory.
+- Click a column heading to cycle ascending, descending, and original order. **Filters** offers operators appropriate to the R column type, including missing values, dates, booleans and exact integer64 values. Press **Apply** to run a filter; typing does not query R. Filters on different columns combine with AND, and each active filter has a remove button. Text comparisons are case-insensitive and use literal text.
+- Drag column headings to reorder them. Reordering changes presentation locally and leaves R data unchanged.
+- **Reset** restores the saved first page, 20 rows, original column order, and clears sorting, filters and unfinished filter text. It works locally after R stops and ignores outstanding replies. It does not interrupt an R operation already running; use the session's Interrupt control for that.
+
+Sorting and filtering a large table use the **full dataset**, even from the saved preview. They can scan all rows and allocate query indices; plain paging does neither. Cached queries are reused while paging and invalidated after R execution. When starting a new live query, a changed column schema clears incompatible sorting/filtering. If columns change during ordinary live navigation, use Reset and browse beyond the preview again to refresh, or reopen **Data viewer**. The expanded viewer opens the same full object without copying it and is labelled **Full data**.
+
+Inline page/query/order choices survive output updates in the current window, within a bounded cache of recently used tables. They are temporary: reloads and exports use the original saved output. The Text/Table preference is persisted separately. Live requests require the original R process; stopped or archived cells retain their available page and local Reset/Text/column controls. Sessions with the bounded-snapshot/full-data handles already support these editor-side controls after reloading VS Code. Older output without a full-data handle cannot dynamically expand a truncated snapshot.
+
+Column-header tooltips show R classes and storage types. Actual `NA` and `NaN` values have muted italic labels and explanatory tooltips, distinct from the literal string `"NA"`. Small nested values use readable JSON instead of `[object Object]`; large or deeply nested list cells show their class and size. Text previews shorten strings beyond 1,000 characters with a truncation marker. This prevents a single nested dataset or long string from creating an enormous cell. Inspect the original object in R for its complete contents. Full-view filters use the original string, including text beyond the displayed prefix. Numeric labels continue to use R's formatting without changing the values used in calculations.
+
+Full-table handles retain their original objects in R memory without an additional deep copy. Closing an expanded viewer or clearing completed cells does not release a handle that remains in the transcript. Distinct historical objects can therefore still retain substantial memory; use summaries or explicit `print(DT)` if you do not need a full-data handle. R's usual copy-on-modify rules still apply to later edits of shared ordinary data frames. The default Text view changes presentation only. The asset quota limits disk storage, not R heap usage.
+
+### Widgets and output controls
+
+JGD graphics and browser widgets have different interaction models: a static R plot can resize and export, while plotly/leaflet-style interaction comes from the widget's JavaScript. Arbitrary widget behavior that requires browser permissions or unavailable external network resources remains subject to the sandbox and server configuration.
+
+Table paging uses arrow icons with tooltips and accessible names. **Data viewer**, **Open plot**, and **Fit R device** retain short labels alongside their icons. **Save…** opens VS Code's native format picker without changing the cell height or scroll position, followed by the file save dialog. PNG is offered after the image loads. The picker supports typing, arrow-key navigation, Enter to select, and Escape to cancel. Each output allows one pending picker, and replies to replaced or disposed outputs are ignored.
+
+### Numeric formatting
+
+Inline numeric columns use R's `format()` with the session's `digits`, `scipen`, and `OutDec` options. For example, at the default `digits = 7`, `1417.39130434783` displays as `1417.391`. Formatting applies to each requested page, including column-wide decimal places and scientific notation, and HTML reports retain the preview's labels. Hover over a rounded value to inspect the full received number. Raw numeric values remain unchanged for calculations and the expanded data viewer's sorting/filtering; integer64 IDs and numeric-looking text remain exact. This uses base R numeric formatting, rather than class-specific printers such as tibble's pillar display.
+
+Already-running sessions and older saved outputs also get compact numeric display after updating the extension and reloading VS Code, using an approximation of R's default seven significant digits. Exact session-option formatting is available in new sessions using the updated bundled `sess`; existing R sessions can keep running. Previously recorded previews keep their original labels, while new page requests use the current session options.
+
+## Persistence, storage, and export
+
+The default registry is `$XDG_STATE_HOME/vscode-r/interactive` when `XDG_STATE_HOME` is a nonempty absolute path. Otherwise, new macOS installations use `~/Library/Application Support/vscode-r/interactive`, and Linux uses `~/.local/state/vscode-r/interactive`. An existing macOS registry at `~/.local/state/vscode-r/interactive` is reused so live sessions remain discoverable; it is never moved automatically.
+
+`r.interactive.storagePath` overrides the default. Use an absolute, writable path, and reload VS Code after changing it. Keep this directory on private, reliable storage on the R host. With Remote SSH, the path and environment belong to the remote host.
+
+If session creation reports `EACCES`, the storage directory or an ancestor is not writable by the R host's user. For example, a root-owned `~/.local` can prevent creating the Linux-style path on macOS. New macOS installations use Application Support to avoid this problem. For a custom path, choose a writable directory using `r.interactive.storagePath` and reload. Changing this setting selects a different registry; it does not migrate existing sessions. Reuse the original setting to reconnect to sessions stored there.
+
+Each session stores a manifest, immutable assets, and one journal directory per process generation. Private Unix sockets and credentials live in a mode-0700 runtime directory. The extension discovers existing agents after a reload and reconstructs the recent transcript. Asset URLs are regenerated through VS Code's remote forwarding support.
+
+With `r.interactive.restore` enabled (the default), reopening the same workspace reconnects its saved sessions, even when no R source file is open. Native Interactive tabs are matched by their saved URI, since VS Code does not retain their notebook metadata across reload. This restores the existing views without opening duplicate empty tabs. A failed reconnect preserves the saved association for a later retry. Sessions remain discoverable through **R: Open Interactive Session** from another workspace or when automatic restoration is disabled. Closing a view or choosing **Disconnect** removes its automatic-restoration entry while leaving R alive.
+
+Admission and completion records are flushed to disk. Ordinary output is buffered by the OS, so a machine crash can lose recent output. The execution ledger prevents automatic duplicate evaluation; it does not make arbitrary R code transactional. If the agent dies during a request, the outcome can remain unknown. R process death loses in-memory objects even when its transcript survives.
+
+**Detach** and closing a notebook leave R running. **Stop** terminates R and its graphics worker; the agent serves the open retained transcript until its final client disconnects. **Restart** creates a new process generation and environment in the same window. Restart boundaries and prior generations are restored from their journals when reconnecting, with the existing replay limits applied to each generation. History search includes all admitted commands across these generations, and exports include their retained output and restart boundaries. Old plot previews, saved widgets, and plot exports remain available; old table paging and R-device resizing are disabled because their live handles belonged to the previous process. Run the code again to create live output in the new process. Session restoration remembers open connections, not deliberately detached tabs.
+
+### Export history
+
+**Export Interactive History** supports:
+
+- `.R`: execution history as a script;
+- `.rnb`: code, execution metadata, retained output, and static plot fallbacks;
+- `.ipynb`: standard Jupyter cells with portable MIME output and an R kernelspec;
+- `.html`: an HTML report with a neighboring `.assets` directory containing plots and widget dependencies. Keep the two together.
+
+Choose the format first, then choose the destination in the save dialog. This also avoids macOS appending the wrong extension when several save filters are supplied. History and plot exports suggest names based on the session and default to its working directory. Expanded output tabs are named **Plot: session** or **Viewer: session** to distinguish them from the Interactive window.
+
+A saved `.rnb` contains no agent authentication token or forwarded asset URL. Table previews and static plot fallbacks can be read offline. Full interactive widgets and live table handles require reconnection to the originating session; use HTML export when sharing self-contained widget dependencies. IPYNB export retains standard MIME fallbacks; live session handles remain specific to R Interactive.
+
+Saved output disables controls that need an agent and explains how to reconnect. PNG export waits for the plot image to finish loading. Late plot updates preserve the cell's identity and any unsubmitted code edits. Fit R device works while plain R is idle and keeps historical plots associated with their original cells.
+
+### Updating the extension
+
+Existing agents keep running with the code and R bridge loaded when they started. Reloading VS Code updates editor behavior but does not update those agents. Features that require newer agent capabilities need a new or restarted session. Start a new session to use those features while preserving old work, or explicitly restart a managed session when its in-memory objects are no longer needed. Restart prepares and loads the current private R runtime. History search falls back to the restored transcript on older agents. Renaming updates the session list, status bar, and kernel label; an already-open native tab may retain its original title until reopened.
+
+### Retention limits
+
+Retention limits are configured in MiB (1 MiB = 1,048,576 bytes):
+
+```json
+{
+ "r.interactive.maxAssetSizeMiB": 1024,
+ "r.interactive.maxJournalSizeMiB": 128,
+ "r.interactive.maxOutputSizeMiB": 4
+}
+```
+
+These defaults allow **1 GiB of assets per session**, approximately 128 MiB of output journal per R generation, and 4 MiB of console text per execution. Fractional MiB values are supported and converted to whole bytes. Asset usage counts stored bytes after compression where supported. Output and journal setting changes apply to new or restarted sessions. The asset limit also updates connected sessions controlled by this window without restarting R.
+
+These limits do not cap total session storage: earlier R generations and execution records (including submitted code) remain separately retained. Journal rotation removes old output in roughly 4 MiB segments. Reopening a window restores about 3 MiB of recent execution data per R generation, independently of these retention limits, so a retained execution's full output may not fit in the restored window. Truncation is explicit; admission records remain for deduplication.
+
+Plot storage follows this lifecycle:
+
+- Incremental JGD drawing updates are combined over 200 ms, and pending updates for an execution are flushed when it finishes. The agent saves SVG snapshots; it keeps JGD's drawing operations in memory for live plot handling instead of also saving redundant JSON frame files.
+- Generated SVG/JSON assets of at least 4 KiB use gzip when it reduces their size. Identical content is deduplicated. Display and export decode transparently; exported SVG/JSON files remain ordinary files. Existing uncompressed assets remain readable. HTML dependencies retain their original encoding and directory structure.
+- Automatic cleanup starts when a write would exceed 80% of the quota. It removes superseded snapshots and unreferenced generated assets. The latest display version in every retained journal generation is protected, including all dependencies of retained HTML widgets. When journal rotation removes an output's last reference, its assets become eligible for cleanup. A corrupt or unreadable journal prevents cleanup.
+- **R: Clean Up Interactive Assets**, also in the session context menu, runs cleanup immediately and reports reclaimed space and current usage. Clearing cells only hides them; it does not erase durable history or make their final plots eligible for cleanup.
+- The hard limit still applies when all remaining assets are referenced. A failed plot retention is reported once per execution, and R keeps running. Increasing `r.interactive.maxAssetSizeMiB` updates connected sessions that support asset management and that this window controls, without restarting R. Lowering it below protected output size is rejected.
+
+Cleanup preserves distinct historical plots. Compression savings depend on the output, so plot count alone cannot predict storage use. To release all storage for unused work, export it and remove that **stopped** session's storage directory. Do not delete live session storage.
+
+## Known limitations
+
+- Persistence does not checkpoint R memory. An R crash, process termination, host reboot, or server logout policy can still end a session.
+- Native Interactive input drafts are not guaranteed to survive a full application exit. Save unfinished code in a source file before quitting.
+- VS Code's accessibility announcements can expose the selected custom MIME payload as JSON. The public renderer/controller API does not provide separate announcement text.
+- Widget frames use a fixed height, and an already-open native Interactive tab can retain its original title after renaming the session.
+- Local lifecycle tests and Linux tmux CI do not establish behavior for every Remote SSH connection or server-specific systemd/logout policy. Validate those on the intended host.
+
+## Contributing
+
+The [architecture and backend contract](https://github.com/REditorSupport/vscode-R/blob/main/src/interactive/README.md), [test instructions](https://github.com/REditorSupport/vscode-R/blob/main/CONTRIBUTING.md#testing-r-interactive), and [analysis fixtures](https://github.com/REditorSupport/vscode-R/blob/main/src/test/examples/README.md) live with the source.
diff --git a/website/docs/features/r-terminals.md b/website/docs/features/r-terminals.md
new file mode 100644
index 000000000..e7742c1bc
--- /dev/null
+++ b/website/docs/features/r-terminals.md
@@ -0,0 +1,90 @@
+# Interacting with R terminals
+
+## Creating R terminal
+
+In VS Code window, press F1 (or Ctrl + Shift + P) and
+choose "R: Create R terminal" command, then the VS Code terminal will be
+revealed and an R terminal will be launched.
+
+By default, the official `R` terminal is launched.
+
+Set `r.consolePath` to use an alternative console. For new configurations, when
+it is unset, vscode-R uses `r.executablePath`, then the system R installation.
+
+
+
+For an alternative R console, see [arf](https://github.com/eitsupi/arf).
+
+If the R session watcher is enabled, then it will attach to the R session
+whenever a new R terminal is created. The status of the session watcher is shown
+in the status bar like below. Managed terminals reconnect automatically after a
+VS Code window reload.
+
+
+
+## Sending code to R terminals
+
+By default, if there is no active R terminal, then a new R terminal will be
+created before sending code to it. To always send code to the active terminal
+without creating a new one, turn on `r.alwaysUseActiveTerminal` in VS Code
+settings.
+
+The behavior of sending code to the terminal is following:
+
+- If a range of code is selected, then the selected code will be sent to the
+ terminal.
+- If no code is selected, then an executable range of code will be sent to the
+ terminal and the cursor will move to the next line.
+
+## Using multiple R terminals
+
+Each time "R: Create R terminal" is executed, a new R terminal is created. The
+user could switch between these R terminals, and customize the icon color and
+the label of each terminal.
+
+
+
+To activate the session belonging to the current R terminal, click the status
+bar item or run **R: Activate R Session**.
+
+## Using self-managed R terminals
+
+Self-managed R terminals could be useful if one needs one or more R sessions to
+be preserved so that closing the VS Code window does not terminate the R
+sessions. On Linux and macOS, both
+[`screen`](https://www.gnu.org/software/screen/) and
+[`tmux`](https://github.com/tmux/tmux/wiki) could be used to preserve any number
+of R sessions or any other terminal programs in a customizable layout.
+
+To connect one, run **R: Attach External R Session (Copy command)** in VS Code,
+then paste and run the copied `source(...)` command in the target R session.
+The generated script installs or updates vscode-R's bundled `sess` package if
+needed and attaches the session to the current window.
+
+The old `~/.vscode-R/init.R` startup snippet was removed in v3.0.0. Remove any
+remaining block that sources it from `.Rprofile`.
+
+## Control console print width and text wrapping
+
+On some systems, users may notice that the full width of the R console is not being used. In the example below, we see that both the `LETTERS` vector and the columns of our dummy data frame are being hard wrapped at 80 characters, resulting in unnecessary overflow of rows instead of utilizing the available horizontal space.
+
+
+
+The culprit in such cases is most likely a hard-coded `width` option in your system-wide `.Rprofile`. You can check by running
+
+```r
+getOption("width")
+```
+
+Changing this width/wrapping constraint is a simple matter of overriding the default `width` option. You can provide a hard-coded value like, say, `120` or `160`. Or, you can try invoking the `"COLUMNS"` system environment variable (caveat: this may not be available on your system). Either way, you will probably want to set the sister `setWidthOnResize` option to `TRUE` at the same time, so that the prompt width dynamically adjusts along with your VS Code terminal (e.g., if you resize the window).
+
+```r
+options(width=120) # set hard-coded value
+# options(width=Sys.getenv("COLUMNS")) # set on available columns (may not work on every system)
+options(setWidthOnResize=TRUE) # automatically reset the width if the terminal window is changed
+```
+
+
+
+
+Here we have (temporarily) set the width options directly in our live R session. But you may wish to add them to your `.Rprofile` for a persistent change across sessions.
diff --git a/website/docs/features/rstudio-addins.md b/website/docs/features/rstudio-addins.md
new file mode 100644
index 000000000..3b1fc04c2
--- /dev/null
+++ b/website/docs/features/rstudio-addins.md
@@ -0,0 +1,129 @@
+# RStudio addin support
+
+The VSCode-R extension is compatible with a subset of RStudio Addins via an
+`{rstudioapi}` emulation layer. Nearly all of the document inspection and
+manipulation API is supported, although with some notable concessions:
+
+- VSCode always directs addin text output destined for the "active document" to
+ the active or last active text editor, and never the active terminal/console.
+
+There are two main ways to launch an addin:
+
+1. via the addin picker, launched from the command palette as "R: Launch RStudio
+ Addin", or via a keybinding to `r.launchAddinPicker`.
+2. via a direct keybinding to the addin R functions. These can be found by
+ looking in the `inst/rstudion/addins.dcf` file of the
+ addin-providing-package's source. For example to bind a key to Reprex the
+ current selection, you would configure a keybinding like:
+
+```json
+{
+ "description": "reprex selection",
+ "key": "ctrl+;",
+ "command": "r.runCommand",
+ "when": "editorTextFocus",
+ "args": "reprex::reprex_selection()"
+}
+```
+
+## Enabling RStudio Addin Support
+
+RStudio API emulation is enabled by default when the session watcher is active.
+It can be controlled with the `r.session.emulateRStudioAPI` VS Code setting. No
+`.Rprofile` entry is needed.
+
+## Installing addins
+
+Unlike RStudio the VSCode addin registry is regenerated every time a new R
+session is attached, not when a new package is installed. You can use the
+`rstudioapi::restartSession()` to restart the R session and repopulate installed
+addins. For a self-managed session, you can also reconnect using the command
+copied by **R: Attach External R Session (Copy command)**.
+
+## Shiny Gadgets
+
+Addins that launch Shiny gadgets and call supported functions can work, although
+for best results, consider setting the `viewer` property of
+`r.session.viewers.viewColumn` to `"Beside"` to have the gadget open alongside
+the active text editor:
+
+```json
+{
+ "r.session.viewers.viewColumn": {
+ "viewer": "Beside"
+ }
+}
+```
+
+## Known compatible packages
+
+Packages listed here have been verified working in VSCode.
+
+- `{AlignAssign}`
+- `{blogdown}`
+ - Live preview in VSCode works but viewer colour theme interacts with site
+ colour theme. Choose a light theme for light site preview or explicitly set
+ the website background color, e.g., `body {background-color: white;}`, in CSS files.
+- `{citr}`
+- `{codegrip}`
+ - currently only `addin_reshape()`
+- `{datapasta}` dev version
+- `{docthis}`
+- `{equisse}`
+- `{fnmate}`
+- `{gistfo}`
+- `{prefixer}`
+- `{remedy}`
+- `{reprex}`
+- `{sinew}`
+ - The interactive oxygen generator polls the active document_context, which is
+ glitchy but can work.
+- `{styler}`
+
+## Implemented functions
+
+`{rstudioapi}` Functions in this section have been reimplemented to work with
+VSCode:
+
+- `getActiveDocumentContext`
+- `getSourceEditorContext`
+- `isAvailable`
+- `verifyAvailable`
+- `insertText`
+- `modifyRange`
+- `readPreference`
+- `readRStudioPreference`
+- `hasFun`
+- `findFun`
+- `showDialog`
+- `navigateToFile`
+- `setSelectionRanges`
+- `setCursorPosition`
+- `setDocumentContents`
+- `documentSave`
+- `documentId`
+- `documentPath`
+- `documentSaveAll`
+- `documentNew`
+- `getActiveProject`
+- `restartSession`
+- `viewer`
+- `showPrompt`
+- `askForPassword`
+
+## Unimplemented functions
+
+Functions not above that need to interact with the IDE to work have been
+reassigned to stop with an error:
+
+`This {rstudioapi} function is not currently implemented for VSCode.`
+
+## Developer notes
+
+The best way to check if an IDE API function is supported in a way that is
+supported by both RStudio and VSCode is to call `hasFun` or `findFun`. This will
+work as expected for all implemented functions above.
+
+`rstudioapi` offers the ability to assert certain version numbers of the IDE
+whilst using these functions with a `version_needed` argument. This is not
+supported by VSCode at present.
diff --git a/website/docs/features/session-watcher.md b/website/docs/features/session-watcher.md
new file mode 100644
index 000000000..fd7edc100
--- /dev/null
+++ b/website/docs/features/session-watcher.md
@@ -0,0 +1,68 @@
+# R Session watcher
+
+R session watcher connects vscode-R to a live R session and powers the
+workspace and data viewers, session-aware hover and completion, plots, help,
+web viewers, and RStudio API emulation.
+
+## Basic usage
+
+The watcher is enabled by default through `r.sessionWatcher`. Run
+**R: Create R terminal** to start a managed terminal. vscode-R connects the
+session automatically and shows the attached R process in the status bar.
+
+vscode-R 3.0.0 uses the bundled `sess` R package for this connection. If the
+package is missing or older than the extension, vscode-R asks whether it may
+install or update the bundled version. Managed terminals can reconnect after a
+VS Code window reload.
+
+## External and self-managed R sessions
+
+To attach an R process started outside **R: Create R terminal**, run
+**R: Attach External R Session (Copy command)** from the Command Palette. This
+copies a short `source(...)` command to the clipboard. Run that command in the
+target R session.
+
+The generated attach script installs or updates the bundled `sess` package if
+needed, then connects that R process to the current VS Code window. This makes
+it suitable for R sessions running in `tmux`, `screen`, or another
+self-managed terminal. Generate a new command when attaching to a different VS
+Code window.
+
+To switch between connected sessions, focus the desired terminal and use the
+status bar item or **R: Activate R Session**.
+
+The old `~/.vscode-R/init.R` startup snippet and **R: Attach Active Terminal**
+command were removed in v3.0.0. If your `.Rprofile` still sources that file from
+a 2.x installation, remove the obsolete `source(...)` block.
+
+## Configuration
+
+Configure session behavior with VS Code settings rather than R
+`options(vsc.*)`. In particular:
+
+- `r.session.watchGlobalEnvironment` controls workspace watching and
+ session-aware hover and completion.
+- `r.session.emulateRStudioAPI` controls RStudio API emulation.
+- `r.session.viewers.viewColumn` controls where R webviews open.
+- `r.plot.backend` selects the plot backend.
+
+The R-side `vsc.*` options used by vscode-R 2.x are no longer read. See
+[Extension settings](../configuration/extension-settings.md)
+for the current settings.
+
+## Disabling the watcher
+
+Set `r.sessionWatcher` to `false` and restart or reload VS Code. Features that
+require communication with a live R session will then be unavailable.
+
+## How it works
+
+The `sess` package and vscode-R exchange JSON-RPC messages over a local Unix
+domain socket on Linux and macOS, or a named pipe on Windows. This replaces the
+2.x file-watching protocol based on `request.log`, `globalenv.json`, and
+`plot.png`.
+
+Each connected R process has a stable session identity. The extension can work
+with multiple sessions, switch the active session, and reconnect managed
+terminals after the VS Code window reloads. Session files and local endpoints
+are created with owner-only permissions.
diff --git a/website/docs/features/sidebar.md b/website/docs/features/sidebar.md
new file mode 100644
index 000000000..e89bb3b09
--- /dev/null
+++ b/website/docs/features/sidebar.md
@@ -0,0 +1,34 @@
+# Sidebar user interface
+
+The sidebar contains a workspace viewer and help pages viewer.
+
+
+
+## Workspace viewer
+
+The workspace viewer displays the information of the objects in the global
+environment of the attached R session.
+
+Objects could be viewed (sending `View(obj)` to the terminal) or removed
+(sending `rm(...)` to the terminal).
+
+Lists, environments, pairlists, S4 and R6 objects, and data frames can be
+expanded recursively. Large objects load 500 items at a time; select the `...`
+row to load the next group.
+
+
+
+## Help pages viewer
+
+The help pages viewer lists several options to work with help pages, topics, and
+packages.
+
+
+
+## Package management
+
+In the help pages viewer, one can also install and remove packages. In the
+viewer, pressing any key will trigger the search mode so that one can easily
+find a package by name.
+
+
diff --git a/website/docs/getting-started.md b/website/docs/getting-started.md
new file mode 100644
index 000000000..5c72a2318
--- /dev/null
+++ b/website/docs/getting-started.md
@@ -0,0 +1,70 @@
+# Getting Started
+
+For many R users, [RStudio](https://github.com/rstudio/rstudio) has long been a
+great integrated development environment for data analysis and visualization. It
+provides a rich set of features that make it unprecedentedly easy to perform a
+wide range of tasks interactively.
+
+[VS Code](https://code.visualstudio.com/), in contrast, is not specifically
+designed for a certain programming language. It is highly customizable through
+[settings](https://code.visualstudio.com/docs/getstarted/settings), and highly
+extensible through [extensions](https://marketplace.visualstudio.com/). It
+supports many programming languages at different levels through language
+extensions that implement some common protocols such as the
+[Language Server Protocol](https://microsoft.github.io/language-server-protocol)
+to enable language features based on code analysis such as _Go To Definition_
+and _Rename symbol_, and the
+[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) to
+enable interactive debugging of any target.
+
+This vscode-R extension is an extension that attempts to make it easier to write
+R code and work with R sessions interactively in VS Code. Though vscode-R
+[provides support](./features/rstudio-addins.md)
+emulating RStudio's features, it is not intended to be a full drop-in
+replacement for RStudio. In contrast, vscode-R is useful for those who want a
+unified development environment to work with multiple programming languages such
+as R, Python, C++, etc., as well as those who need to work with remote servers,
+containers, self-managed R sessions or multiple R sessions at the same time.
+
+vscode-R requires VS Code 1.101 or later. To enjoy the full R development
+experience, install the extension and language server, then choose any optional
+tools you need:
+
+- [vscode-R](https://marketplace.visualstudio.com/items?itemName=REditorSupport.r):
+ Provides R language service, R Markdown, and interactivity between VS Code and
+ R terminals. When first creating a managed R terminal, accept the prompt to
+ install the bundled `sess` R package; it does not need to be installed
+ manually.
+
+- [languageserver](https://github.com/REditorSupport/languageserver): An R
+ package that implements the Language Server Protocol for R to provide a wide
+ range of language analysis features such as auto-completion, function
+ signature, documentation, symbol highlight, document outline, code formatting,
+ symbol hover, diagnostics, go to definition, find references, etc.
+
+- [arf](https://github.com/eitsupi/arf) (optional): An alternative R console.
+ See its repository for installation and configuration.
+
+- [VSCode-R-Debugger](https://github.com/ManuelHentschel/VSCode-R-Debugger): A
+ VS Code extension to support R debugging capabilities.
+
+- [`jgd`](https://github.com/REditorSupport/jgd) or
+ [`httpgd`](https://github.com/nx10/httpgd) (optional): Interactive graphics
+ devices used by the
+ [plot viewer](./features/plot-viewer.md).
+ The default `r.plot.backend` value, `auto`, tries JGD first, then httpgd, then
+ the standard viewer.
+
+- [rmarkdown](https://rmarkdown.rstudio.com): An R package and format for
+ creating reproducible and narrative-driven data analyses. vscode-R provides
+ tooling to edit, run, and knit Rmarkdown files.
+
+- [Pandoc](https://pandoc.org) (optional): A powerful document conversion tool.
+ vscode-R uses this to render help previews when users hover over R code.
+
+However, the astounding flexibility of VS Code comes at a cost that some users
+might not find enjoyable in the beginning: Some setup and configuration are
+needed to make each part work well together. To minimize that cost, please refer
+to the detailed installation instructions we provide for
+[Windows](./installation/windows.md), [macOS](./installation/macos.md) and
+[Linux](./installation/linux.md).
diff --git a/website/docs/guide/package-development.md b/website/docs/guide/package-development.md
new file mode 100644
index 000000000..ac5e24dd8
--- /dev/null
+++ b/website/docs/guide/package-development.md
@@ -0,0 +1,37 @@
+# Package development
+
+Package development is supported by vscode-R,
+[R language server](https://github.com/REditorSupport/languageserver), and
+[R debugger](https://github.com/ManuelHentschel/VSCode-R-Debugger).
+
+## Commands
+
+vscode-R mainly provides the mostly used package development commands:
+
+| Title | Command | R code |
+| --------------- | ------------ | ---------------------- |
+| Build package | `r.build` | `devtools::build()` |
+| Test package | `r.test` | `devtools::test()` |
+| Check package | `r.check` | `devtools::check()` |
+| Install package | `r.install` | `devtools::install()` |
+| Document | `r.document` | `devtools::document()` |
+| Load all | `r.loadAll` | `devtools::load_all()` |
+
+
+Keyboard shortcuts could be bound to these commands. See
+[Creating keybindings for R commands](../configuration/keyboard-shortcuts.md#creating-keybindings-for-r-commands).
+
+## Development
+
+The [R language server](https://github.com/REditorSupport/languageserver) loads
+all R documents in `./R` if it detects a `NAMESPACE` file in the workspace root
+folder, which indicates that the workspace contains an R package. Therefore, all
+these R files are considered in the same workspace, sharing completions,
+definitions, references, and other workspace-level language features.
+
+## Debugging
+
+The [R debugger](https://github.com/ManuelHentschel/VSCode-R-Debugger) supports
+debugging the package code in the current workspace. See
+[Debugging R packages](https://github.com/ManuelHentschel/VSCode-R-Debugger#debugging-r-packages)
+for more details.
diff --git a/website/docs/guide/r-markdown.md b/website/docs/guide/r-markdown.md
new file mode 100644
index 000000000..9d3eef0d1
--- /dev/null
+++ b/website/docs/guide/r-markdown.md
@@ -0,0 +1,110 @@
+# R Markdown
+
+R Markdown document creation is supported with the following features:
+
+- Chunk highlighting
+- Chunk navigation commands (Select current chunk, go to previous/next chunks,
+ etc.)
+- Chunk execution commands (Run current chunk, run above/below chunks, etc.)
+- Automatic evaluation of YAML `params` before running code
+- Rmd render commands (Knit, Knit to PDF/HTML/All)
+- Live preview rmd (as html)
+- Create new draft from a template
+
+## File association
+
+By default, `Rmd` files are open as Markdown documents. To enable R Markdown features, you need to associate `*.Rmd` files with `rmd` language. Add an entry Item `*.Rmd` and Value `rmd` in the VS Code settings editor:
+
+
+
+or directly update `settings.json` with the following:
+
+```json
+{
+ "files.associations": {
+ "*.Rmd": "rmd"
+ }
+}
+```
+
+## Installing pandoc
+
+[pandoc](https://pandoc.org) is required to render R Markdown documents. Visit [Installing pandoc](https://pandoc.org/installing.html) for instructions.
+
+You may need to restart VS Code for `rmarkdown` to be able to detect `pandoc`.
+
+## Editing R Markdown documents
+
+
+
+When an R Markdown document declares `params` in its YAML header, vscode-R
+evaluates them into the R session before running code from the document. A
+custom shortcut to load the parameters is not required.
+
+## Knitting R Markdown documents
+
+R Markdown documents can be knit in a VSCode-R managed background process when
+using the knit command. Beyond the use of a background process, this has the
+following features:
+
+- Set knitr document directory
+- Knit progress tracking
+- Smart knitting
+
+### Set knitr document directory
+
+By default, knitr evaluates documents as though they are the root folder. For
+instance, calling `source` in a document will use the document's folder as the
+working directory, not the document's workspace. This can be modified in
+VSCode-R, so as to tell knitr if we want to evaluate from the workspace root or
+the document directory.
+
+
+
+### Progress tracking
+
+Knit progress is tracked via a progress bar, and can be viewed in the R Markdown
+output stream. Progress is determined by the percentages reported in the R
+Markdown output stream and may not be 100% accurate.
+
+
+
+### Smart knitting
+
+The knit button is "smart" in that it checks the document and its workspace for
+context when knitting. For instance, if a document has a knit function defined
+in the YAML header, the knit button will call the custom function when knitting.
+This also works for R Markdown sites, where the knit button will call
+`rmarkdown::render_site` instead of `rmarkdown::render`.
+
+## Live rendering R Markdown documents
+
+You can live preview R Markdown documents by pressing the "Open Preview to Side"
+button when focused on an R Markdown document.
+
+
+
+You can also preview a document by right-clicking it in the explorer and
+selecting preview.
+
+You can also run the following code and a browser viewer will open with live
+rendering of the R Markdown document.
+
+```r
+rmarkdown::run("your-rmd-document.Rmd")
+```
+
+## Live previewing rendered R Markdown documents
+
+When an R Markdown document is knit and rendered to an HTML file, [Live Preview](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) can be used to live preview the HTML document. It supports auto-refresh when the HTML file is updated.
+
+## Templates
+
+You can run "R Markdown: New Draft" from the command palettes to create a new draft from an R Markdown template.
+
+The following is a (incomplete) list of packages that provide R Markdown templates:
+
+* [rmarkdown](https://rmarkdown.rstudio.com/gallery.html)
+* [rticles](https://pkgs.rstudio.com/rticles/index.html)
+* [tufte](https://rstudio.github.io/tufte/)
+* [prettydoc](https://prettydoc.statr.me/)
diff --git a/website/docs/index.md b/website/docs/index.md
new file mode 100644
index 000000000..37040a7c2
--- /dev/null
+++ b/website/docs/index.md
@@ -0,0 +1,114 @@
+---
+layout: home
+title: R Extension for Visual Studio Code
+titleTemplate: false
+
+hero:
+ name: vscode-R
+ text: R Extension for Visual Studio Code
+ tagline: Language service based on static code analysis, and interactivity between VS Code and R sessions.
+ image:
+ src: /logo.svg
+ alt: R logo
+ actions:
+ - theme: brand
+ text: Getting Started
+ link: /getting-started
+ - theme: alt
+ text: Windows
+ link: /installation/windows
+ - theme: alt
+ text: macOS
+ link: /installation/macos
+ - theme: alt
+ text: Linux
+ link: /installation/linux
+---
+
+
+
+[vscode-R](https://github.com/REditorSupport/vscode-R) is the R Extension for
+[Visual Studio Code](https://code.visualstudio.com/). The extension is mainly
+focused on providing language service based on static code analysis and user
+interactivity between VS Code and R sessions.
+
+We recommend the [Getting Started](./getting-started.md) page first. Or, dive in
+straight away by choosing the installation instructions for your operating
+system: [Windows](./installation/windows.md), [macOS](./installation/macos.md),
+or [Linux](./installation/linux.md).
+
+## Features
+
+- Snippets for R and R Markdown.
+
+- [R Language Service](./features/language-service.md):
+ Code completion, function signature, symbol highlight, document outline,
+ formatting, definition, diagnostics, references, and more.
+
+- [Interacting with R terminals](./features/r-terminals.md):
+ Sending code to terminals, running multiple terminals, working with remote
+ servers.
+
+- [R Interactive](./features/r-interactive.md) (experimental):
+ Persistent R sessions with native Interactive windows and rich output.
+
+- [Package development](./guide/package-development.md):
+ Build, test, install, load all and other commands from devtools.
+
+- [Keyboard shortcuts](./configuration/keyboard-shortcuts.md):
+ Built-in and customizable keyboard shortcuts.
+
+- [Workspace viewer](./features/sidebar.md#workspace-viewer):
+ Environment pane to show global variables in the attached R session.
+
+- [Help pages viewer](./features/sidebar.md#help-pages-viewer):
+ Viewing R help pages and searching help topics.
+
+- [Package management](./features/sidebar.md#package-management):
+ Installing and removing R packages.
+
+- Session symbol hover and completion.
+
+- [Data viewer](./features/interactive-viewers.md#data-viewer):
+ Viewing data frames, matrices, Arrow tables, and Polars DataFrames in a
+ sortable, filterable grid that loads rows on demand, or lists as JSON.
+
+- [Plot viewer](./features/plot-viewer.md):
+ Interactive JGD and httpgd backends, plus a responsive standard SVG/PNG
+ viewer.
+
+- [Webpage viewer](./features/interactive-viewers.md#webpage-viewer):
+ Viewing [htmlwidgets](https://www.htmlwidgets.org) such as interactive
+ graphics and [visual profiling results](https://rstudio.github.io/profvis/).
+
+- [Browser viewer](./features/interactive-viewers.md#browser-viewer):
+ Viewing interactive [shiny](https://shiny.rstudio.com) apps.
+
+- [R Markdown support](./guide/r-markdown.md):
+ R Markdown chunk highlighting, chunk navigation, execute commands, and
+ preview.
+
+- [RStudio add-in support](./features/rstudio-addins.md):
+ Run supported RStudio add-ins in VS Code with a live R session.
+
+- Full support of
+ [Remote Development](https://code.visualstudio.com/docs/remote/remote-overview)
+ via [SSH](https://code.visualstudio.com/docs/remote/ssh),
+ [Containers](https://code.visualstudio.com/docs/remote/containers) and
+ [WSL](https://code.visualstudio.com/docs/remote/wsl).
+
+
+
+### List viewer
+
+The list viewer supports collapsing nodes.
+
+
+
+## Plot viewer
+
+The plot viewer supports JGD, httpgd, and a responsive standard SVG/PNG backend.
+For more details, go to
+[Plot viewer](./plot-viewer.md).
+
+
+
+## Webpage viewer
+
+In R, an htmlwidget is written in HTML and can be presented in a web browser.
+For example, the following image demonstrates an interactive graphics created by
+[plotly](https://plotly.com/r/):
+
+
+
+## Browser viewer
+
+Interactive shiny apps can be displayed in VS Code. The following is an example
+created by
+
+```r
+shiny::runExample("01_hello")
+```
+
+
+
+For security reasons, the VS Code WebView has security limitations on its
+capability of accessing external resources over a network. For more details,
+visit
+[WebView API](https://code.visualstudio.com/api/extension-guides/webview#security).
+
+If you encounter a problem loading a webpage in a browser viewer, you may try
+viewing the web page in an external web browser.
+
+## Help viewer
+
+The web pages in R documentation can be viewed in the help viewer. Syntax
+highlighting and link navigation are supported.
+
+Help viewer could be revealed via `?symbol` in R terminal, or from the
+[Help pages viewer](./sidebar.md#help-pages-viewer)
+in the
+[sidebar](./sidebar.md),
+or via command `R: Open help for selection` in either command palette or context
+menu in the editor.
+
+
diff --git a/website/docs/features/language-service.md b/website/docs/features/language-service.md
new file mode 100644
index 000000000..86c6ced38
--- /dev/null
+++ b/website/docs/features/language-service.md
@@ -0,0 +1,214 @@
+# R Language Service
+
+The
+[R language server](https://github.com/REditorSupport/languageserver#servers-implemented)
+implements the
+[Language Server Protocol](https://microsoft.github.io/language-server-protocol/specifications/specification-current/)
+and provides a set of language analysis features such as completion, providing
+function signatures, extended function documentation, locating function
+implementations, occurrences of a symbol or object, and code diagnostics and
+formatting. The R language server statically analyzes R code, and vscode-R
+interfaces with it to provide the core of this extension's functionality.
+
+The R language server is implemented by the
+[languageserver](https://github.com/REditorSupport/languageserver) package which
+performs static code analysis with the latest user documents in `R` and `Rmd`
+languages. Therefore, it does not rely on an active R session and thus does not
+require the code to be executed.
+
+To install the package from CRAN:
+
+```r
+install.packages("languageserver")
+```
+
+To experience the latest features, install the package from GitHub:
+
+```r
+remotes::install_github("REditorSupport/languageserver")
+```
+
+### Settings
+
+See the
+[extension settings page](../configuration/extension-settings.md)
+for information on configuring the language server.
+
+## Features
+
+The R language server contributes the following features.
+
+- [Smart editing](#smart-editing)
+ - [Autocompletion while typing](#autocompletion)
+ - [Function signature preview while typing](#signature-preview)
+ - [Extended documentation on hover](#hover)
+ - [Diagnose potential errors and unreliable code with `lintr`](#diagnostics)
+ - [Format with `styler` for clean and consistent code](#formatting)
+ - [Symbol renaming, powered up](#rename-symbol)
+- [Document organization](#document-organization)
+ - [Symbol highlighting on cursor focus](#symbol-highlight)
+ - [Structure-aware document selection](#document-selection)
+ - [Code sections and folding](#code-sections)
+ - [Call hierarchy analysis](#call-hierarchy)
+- [Document navigation](#document-navigation)
+ - [Navigate through all R objects in workspace](#document-and-workspace-symbols)
+ - [Find all occurrences of an object](#find-all-occurrences)
+ - [Document names are links](#document-links)
+ - [See implementation](#go-to-definition)
+- [Miscellaneous](#miscellaneous)
+ - [Color picker](#color-picker)
+
+---
+
+## Smart editing
+
+---
+
+### Autocompletion
+
+The R language server provides global and scope-based autocompletion. You can
+scroll through the suggested signatures with the arrow keys.
+
+Global autocompletion:
+
+
+
+Scope-based autocompletion:
+
+
+
+The R language server currently does not provide completion for filenames; see
+this
+[comment.](../configuration/recommended-extensions.md#path-autocomplete).
+
+### Signature preview
+
+The R language server provides popups of function signatures and their short
+descriptions as you type, which can save a few calls to `help()`.
+
+
+
+
+
+### Hover
+
+A larger preview of the documentation is shown when users mouse over R symbols:
+
+
+
+### Diagnostics
+
+The language server provides code diagnostics through the
+[lintr](https://lintr.r-lib.org/) package in R. See
+[here](../configuration/code-linting.md)
+for configuration.
+
+
+
+### Formatting
+
+The language server provides code formatting through the
+[`styler`](https://github.com/r-lib/styler) package in R. See
+[here](https://github.com/REditorSupport/languageserver#customizing-formatting-style)
+for configuration.
+
+
+
+
+
+### Rename symbol
+
+Symbol renaming through the language server allows you to group renaming actions
+together, letting you refactor code more easily and discard a change on the fly
+if need be.
+
+
+
+---
+
+## Document organization
+
+---
+
+### Symbol highlight
+
+When the cursor is inside of a symbol, all occurrences of that symbol within the
+document are highlighted.
+
+
+
+### Document selection
+
+You can expand selections through `Shift+Alt+RightArrow`. Selections are
+expanded in steps, following the boundaries of each containing R expression.
+
+
+
+### Code sections
+
+The R language server informs VSCode of code sections, or blocks of code that
+form coherent R expressions, which can be navigated through the outline or the
+panel header.
+
+
+
+Sections can also be folded, allowing users to organize the current editor:
+
+
+
+### Call hierarchy
+
+The R language server's static analysis also allows users to see the call
+sequence and hierarchy within an R expression.
+
+
+
+---
+
+## Document navigation
+
+---
+
+### Document and workspace symbols
+
+Users can navigate through the document outline or search for symbols by
+prepending an `@` symbol in the search bar.
+
+
+
+### Find all occurrences
+
+`Ctrl+Click`ing on a user-created R object, pressing `Shift+F12` while the
+cursor is focused on any object, or right-clicking and then selecting
+`Go To References` will open a popup showing all of the uses of the object
+within the current document.
+
+
+
+### Document links
+
+`Ctrl+Click` on a file path takes the user to the referenced document.
+
+
+
+### Go to definition
+
+`Ctrl+Click`ing on an R symbol, pressing `F12` while the cursor is focused on a
+symbol, or right-clicking and then selecting `Go To Definition` will bring up a
+function's implementation.
+
+
+
+---
+
+## Miscellaneous
+
+---
+
+### Color picker
+
+Strings of text that are recognized as R colors are rendered with a color
+decoration. Hovering over the decoration brings out a color picker popup that
+can be used to adjust the referenced color.
+
+
diff --git a/website/docs/features/live-share.md b/website/docs/features/live-share.md
new file mode 100644
index 000000000..e485bb994
--- /dev/null
+++ b/website/docs/features/live-share.md
@@ -0,0 +1,6 @@
+# Live Share collaboration (removed)
+
+::: warning Removed in vscode-R 3.0.0
+vscode-R's Live Share integration was removed in version 3.0.0. The associated
+commands, sidebar view, and `r.liveShare.*` settings are no longer available.
+:::
diff --git a/website/docs/features/plot-viewer.md b/website/docs/features/plot-viewer.md
new file mode 100644
index 000000000..fefe2aeb1
--- /dev/null
+++ b/website/docs/features/plot-viewer.md
@@ -0,0 +1,59 @@
+# Plot viewer
+
+Plots from an attached R session can be displayed in a VS Code editor tab. Use
+`r.plot.backend` to select one of four modes:
+
+- `auto` (default): use JGD if installed, otherwise httpgd if installed,
+ otherwise the standard viewer
+- `jgd`: use the [JGD](https://github.com/REditorSupport/jgd) graphics device
+- `httpgd`: use the [httpgd](https://github.com/nx10/httpgd) graphics device
+- `standard`: use the built-in responsive plot viewer
+
+Backend changes take effect without reloading VS Code. vscode-R warns and falls
+back when the requested package is unavailable.
+
+JGD is lightweight, has no external R-package dependencies, and is usually
+simpler to install. httpgd has a mature, feature-rich SVG viewer, but a larger
+compiled dependency footprint. If you are unsure which optional backend to
+install, start with JGD.
+
+## Standard viewer
+
+The standard backend records the current R plot and re-renders it to fit the
+viewer whenever the panel is resized. It uses crisp SVG output when the
+`svglite` R package is installed and falls back to PNG otherwise.
+
+Use `r.plot.format` to request `"svglite"` or `"png"`. The
+`r.plot.devArgs` setting supplies additional graphics-device arguments, but the
+responsive viewer manages width and height itself.
+
+To use R's native graphics window instead, disable the session watcher with
+`r.sessionWatcher`. This also disables the other features that require an
+attached R session.
+
+## JGD viewer
+
+Install the `jgd` R package to use the lightweight JGD backend:
+
+```r
+install.packages("jgd")
+```
+
+JGD supports plot history, navigation, zoom, and export. Configure the maximum
+history size with `r.plot.jgd.historyLimit`, and the default export dimensions
+and resolution with `r.plot.jgd.exportWidth`, `r.plot.jgd.exportHeight`, and
+`r.plot.jgd.exportDpi`.
+
+## httpgd viewer
+
+Install `httpgd` to use its SVG-based interactive viewer:
+
+```r
+install.packages("httpgd")
+```
+
+Select it explicitly with `"r.plot.backend": "httpgd"`, or leave the backend
+as `auto`. The viewer supports resizing, themes, plot history, hiding, zooming,
+and export.
+
+
diff --git a/website/docs/features/r-interactive.md b/website/docs/features/r-interactive.md
new file mode 100644
index 000000000..12f2281c1
--- /dev/null
+++ b/website/docs/features/r-interactive.md
@@ -0,0 +1,262 @@
+# R Interactive
+
+R Interactive runs R independently of the VS Code extension host. Each session has its own Interactive window, execution queue, environment, retained transcript, plot service, and private agent. Reloading VS Code, closing a tab, or losing an SSH connection does not terminate R.
+
+::: warning Experimental
+R Interactive was introduced in vscode-R 3.2.0 ([PR #1805](https://github.com/REditorSupport/vscode-R/pull/1805)). The feature and its `r.interactive.*` settings may change in future releases.
+:::
+
+## Requirements and setup
+
+Use **VS Code 1.101.0 or newer**. R Interactive currently supports Linux and macOS; its native console bridge does not support Windows. Existing R terminal workflows remain available.
+
+For Remote SSH, install this extension **on the remote host**. R, its packages, optional executables, and session storage must be available on that host. For local use, the same requirements apply to your computer.
+
+The R host needs:
+
+- R, plus either compatible pre-built sess/dependency packages or a C compiler capable of building R packages (`r-base-dev` and `build-essential` on Debian/Ubuntu).
+- The session agent automatically uses the extension host's bundled runtime: VS Code's Electron runtime in Node mode on desktop, or VS Code Server's Node runtime remotely. A separate Node.js installation is optional.
+- `tmux` is optional. On Linux, the default supervisor uses tmux when available and otherwise starts an independent detached process. `systemd --user` is another configurable option.
+- R packages `processx`, `later`, `jsonlite`, and `rstudioapi`. Install `languageserver` for language features, `jgd` and `systemfonts` for JGD graphics, `svglite` for the static fallback, and `htmlwidgets`/`htmltools` for HTML output.
+- `arf` is optional. Creating a headless arf session requires an executable on the R host; plain R requires no arf installation. Connecting to an already-running arf uses its socket and does not require arf on the extension host's PATH. The provider contract was exercised with arf 0.5.1.
+
+For example, run in the R installation used on the server:
+
+```r
+install.packages(c(
+ "processx", "later", "jsonlite", "rstudioapi", "languageserver",
+ "jgd", "systemfonts", "svglite", "htmlwidgets", "htmltools"
+))
+```
+
+### Agent runtime
+
+The experimental `r.interactive.nodePath` setting provides an optional standalone Node.js override for compatible IDEs where the automatic runtime is unavailable, such as some code-server, OpenVSCode Server, or VSCodium configurations. Its default is empty, which selects the current extension host's runtime. Set it to a Node.js 18+ executable name on the R host's PATH or a path such as `/usr/bin/node`; `~`, `${userHome}`, and `${workspaceFolder}` are supported. An invalid explicit override is reported and must be repaired or cleared. The override is excluded from Settings Sync and restricted to trusted workspaces.
+
+Runtime availability and version (Node.js 18+) are checked before installation or restart, so a failed check leaves the current R process running. If an editor update removes the automatic runtime, reload VS Code to select its current executable. Reconnecting to an existing agent does not launch or replace its runtime; new and restarted sessions reread `r.interactive.nodePath`.
+
+### R packages and project libraries
+
+The extension installs its bundled `sess` into a private, content-addressed library. It does not replace your installed `sess` package. If the source build fails, including when build tools are missing, it tries a compiler-free package from [R-universe](https://reditorsupport.r-universe.dev/sess). Installation diagnostics appear in the **R Interactive** output channel.
+
+On macOS, the fallback uses R's matching binary repository. On Ubuntu, it uses a repository matching the host's codename, architecture, and R version. It never assumes that an Ubuntu binary is compatible with another Linux distribution. Dependencies for a binary fallback come from the matching R-universe repositories. No global repository settings are changed.
+
+The compiler-free fallback requires a published `sess` build compatible with the native Interactive bridge. A matching package version alone is insufficient; the extension checks the compatibility marker, required functions, and registered native console routines. Until a compatible build is published for your host, building the bundled package requires a C compiler. Missing or incompatible binaries produce an installation error with diagnostics in **R Interactive**.
+
+That private library is used only to load the bridge; it is not added to your session's `.libPaths()` or `R_LIBS`. Package installation follows ordinary R behavior: `install.packages()` defaults to the first library in `.libPaths()`, usually your user library. Startup files can customize that order, and an explicit `lib=` still takes precedence. The extension does not force a user-library destination over a project library.
+
+Start the session in the renv project directory to load its `.Rprofile` normally. An activated renv project keeps its project library, installation destination, and package isolation; the private `sess` is not added to `renv::snapshot()` lockfiles. IDE support namespaces and the plot device load explicitly, preferring available project versions of their dependencies and using normal host libraries as a fallback. This does not make unrelated packages from those host libraries visible to the project. Install analysis packages in the project as usual, and record them with renv. As in any R process, an already-loaded dependency keeps its loaded version until restart.
+
+Sessions created by older extension builds retain their original library order. Start a new session after updating to use this behavior. Restarting also applies it, but clears in-memory R objects; switching directories in an existing R session does not itself activate a different renv project.
+
+### Process supervision
+
+Typical remote settings:
+
+```json
+{
+ "r.interactive.arfPath": "/home/me/.cargo/bin/arf",
+ "r.interactive.supervision": "auto",
+ "r.interactive.restore": true,
+ "r.interactive.executionTarget": "auto"
+}
+```
+
+Executable paths, storage location, supervision, graphics backend, and output/journal/asset size limits are excluded from VS Code Settings Sync by default because they depend on the R host. Execution target, table presentation, automatic reconnection, and history-length preferences can still sync.
+
+Use the paths appropriate for your server. Linux `auto` prefers tmux when its executable is on the extension host's PATH. If tmux is missing or not executable, it uses a detached agent and records the fallback in the **R Interactive** output channel and agent log. Session Details shows **Independent process**. macOS `auto` also uses a detached agent. Both plain R and managed arf support this fallback with the same Interactive features.
+
+Selecting `tmux` or `systemd` explicitly requires `tmux` or `systemd-run` on the R host. Missing executables produce an actionable error before installing a runtime or stopping the current R process for restart. Install the selected supervisor or change `r.interactive.supervision` to `auto` or `detached`. New sessions and restarts use the current setting; merely reconnecting leaves the existing supervisor unchanged. If an installed supervisor fails to launch (for example, a systemd user service is unavailable), the error includes its diagnostics. The extension does not retry with another supervisor after a launch attempt, which could create duplicate R processes.
+
+Detached launch goes through a short-lived bootstrap so the agent leaves the editor's process tree before launch completes; VS Code debugger auto-attach settings are removed. It survives VS Code reload/exit and an SSH connection closing, but server policies that terminate a user's processes at logout can still stop it. User systemd services also depend on the server's login/linger policy. No option preserves in-memory R objects across a host reboot or termination of the R process.
+
+## Start a session
+
+Run **R: New Persistent Interactive Session**, choose **R** or **arf**, and name the session. Each session opens its own Interactive window; select it in **R → Interactive Sessions** to return to it. Plain R does not require arf. Multiple sessions execute concurrently; each R process runs submitted cells serially.
+
+### Connect to an existing arf session
+
+Adoption uses arf's session discovery and IPC socket on the R host. It does not depend on a particular terminal multiplexer or session manager.
+
+1. Start arf in your preferred terminal or session manager as usual.
+2. Run **R: Connect Interactive to Session** and select the discovered arf PID and working directory.
+3. Arf controls permission to execute visible IPC requests. Approve its prompt, or explicitly choose `:ipc send-policy allow` in that arf process if you want unattended editor submissions. The extension does not bypass this policy using silent evaluation.
+4. Name the session. Its independent agent adopts the existing R process and preserves `.GlobalEnv`. An incompatible loaded `sess` is disconnected and unloaded before loading the private bridge; if another package prevents unloading, resolve that dependency in the terminal and reconnect.
+5. Repeat for other arf sessions. Select an entry in **R → Interactive Sessions** to switch the active Interactive window and workspace viewer.
+
+The agent itself runs under the separately selected supervisor (`tmux`, `systemd`, or a detached process). Stopping your original arf process ends its R session. Stopping the agent interrupts editor integration; it is not a checkpoint of the R heap. If an adopted arf outlives a failed agent, `sess::interactive_stop()` restores its terminal callbacks so that it can be adopted again.
+
+### Configure managed arf sessions
+
+The provider picker shows **R** and **arf**, each with its resolved executable path on a second line. **arf** appears only when `r.interactive.arfPath` resolves to an executable file on this host (the remote server with Remote SSH). Otherwise, **Configure arf…** opens its setting without creating a session. Install arf separately and configure its path, or choose **R** with the same persistence and multi-session controls. The setting accepts names on PATH, absolute or workspace-relative paths, `~/`, `${userHome}`, and `${workspaceFolder}`. Configured paths containing spaces do not need quotes. Changing the setting takes effect the next time the picker opens; shell aliases are not executables.
+
+New arf sessions save their resolved absolute executable path, so a later PATH change does not break restart. Restart checks that saved path, then the current setting if the executable moved, before stopping R. If neither is usable, it explains how to configure arf and leaves the current session running.
+
+## Execution and editor behavior
+
+### Session controls
+
+- **R: Open Interactive Session** opens the session picker when run from the Command Palette. The picker checks saved agents without taking control and shows live status, provider, PID, working directory, and a short session ID. Unavailable agents are omitted, while their saved history remains on disk. The picker also offers **New persistent R session**. Selecting a session in the tree opens that session directly. Cancelling the picker leaves existing sessions unchanged.
+- The R session button in the Interactive toolbar shows the session name and live state. The kernel chooser uses a compact version/provider/PID description and a second line for the working directory, host, and supervision. VS Code also uses that short description as the button tooltip; it does not expose a separate tooltip or arbitrary multiline descriptions. The full R version, PID, directory, host, supervision, executable, session ID, and controlling/observing status remain available in the status-bar tooltip and **Session… → Session Details**. The presentation refreshes during startup, execution, disconnect, stop, and restart without changing the selected kernel.
+- The status bar shows the selected session, activity, queued cell count, connection state, and observer status. Select it to switch sessions or answer a waiting R input prompt. Right-click a session in **Interactive Sessions** for actions on that specific session, including rename, interrupt, queued-work cancellation, detach, and restart.
+- The **Interactive Sessions** tooltip separates **Connection: Connected · controlling/observing** from process supervision. **Independent process** means R survives VS Code reload/exit; it does not mean the editor is disconnected. Unopened sessions show **Not open in this VS Code window**. Connection/control changes refresh the tooltip, including after reconnecting.
+- Session age appears in the session list, connection/stop pickers, and kernel description as **<1m**, **30m**, **1h**, or **1d**. It refreshes once a minute; the tooltip includes the start time. Age uses the persisted start of the current process generation, so reloading preserves it and restarting resets it. The recorded process exit time keeps a stopped session's lifetime fixed.
+- **R: Stop Selected Interactive Sessions…** in the Command Palette opens a checkbox picker with session names, PIDs, and directories. Use Ctrl/Cmd-click or Shift-click to select entries in **Interactive Sessions**, then click the header's stop icon or right-click **Stop Selected Interactive Sessions…** to stop that selection. With no tree selection, the header icon opens the picker. **R: Stop All Interactive Sessions…**, also in the view's **…** menu, targets running Interactive sessions in the configured registry on this host, including those without open tabs. Both ask once with the target list, retain history, and leave the current editor layout intact. Sessions controlled by another VS Code window are skipped; the result offers **Show Details** for failures. Use **Take Control** explicitly before retrying those sessions. Sessions created or restarted after confirmation opens are not added to its targets.
+- The Interactive toolbar includes **Restart**, **Session…**, **History**, and **Clear Completed**, alongside VS Code's **Interrupt** control. **Session…** opens a searchable action picker for switching/creating sessions, rename/details, queued-work cancellation, input/control, plots/export/asset cleanup, disconnect, and stop. These actions target that window's notebook, even when another session or editor has focus. On narrow windows, VS Code moves excess actions into its toolbar overflow. The controls also work in the fallback R notebook and stay out of other kernels' notebooks.
+- Restart and Stop confirmations name the affected session and explain that in-memory objects will be lost. Restart is available for managed plain R and arf sessions; restart an adopted arf session in its original terminal or session manager, then reconnect. **Disconnect** leaves R running. **Clear Completed** retains active/queued cells, drafts, and saved history.
+- When R stops, the Interactive window shows a **R session stopped** notice, including when R exits itself. Reopening the stopped session restores one notice along with its history. Restart keeps the same Interactive window, its input draft, edited cells, code, and output. A **R session restarted** boundary marks where the fresh process begins; subsequent execution uses that process. Source-document bindings and the existing kernel controls follow the replacement. A failed restart leaves an explanation and the transcript in place so it can be retried.
+- **Search Interactive History** (`Ctrl+Alt+H`, or `Cmd+Alt+H` on macOS) searches admitted code in the session's durable history, including commands older than the restored window. Enter inserts a command into the input for editing and preserves any existing draft. Item buttons copy, run again, or navigate to the original source; the history button loads older matches. Disconnected and older agents use the locally restored history.
+- **New Persistent Interactive Session** focuses the new session's input, preserving drafts in other sessions. Creating a target through **Run Selection** preserves source-editor focus.
+- The cell toolbar provides icons for **Insert Cell Code into Interactive Input**, **Copy Cell Code**, and **Go to Interactive Cell Source**, with tooltips identifying each action. Insert preserves an existing draft; lifecycle notices cannot be inserted as executable R code. **Browse Interactive Plots** searches the plots in the restored transcript by their generating code and opens an enlarged view.
+- **Cancel Queued Interactive Cells** leaves the running cell alone. **Clear Completed Interactive Cells** hides finished cells while preserving drafts, running/queued/uncertain work, and durable history. Hidden cells stay hidden during reconnect to the same view; reopening a detached view restores the history. R process exit automatically cancels undispatched cells.
+- The native VS Code Interactive window provides an R input editor and execution history, without requiring Jupyter. If that window cannot be opened, a native `r-interactive` notebook is used.
+
+### Route code to a session
+
+- Selecting an Interactive session makes existing Run Selection/Line, source, and other R execution commands target it when `executionTarget` is `auto`. **Use Terminal for R Execution** restores terminal routing. Set `executionTarget` to `terminal` to keep terminal routing by default.
+- With the default `executionTarget: auto`, running source code when no execution target is available opens **Run R code**. Choose **New R Interactive window**, **Create R terminal**, or a live persistent session (including discovered arf sessions). The captured code runs after the target is ready. Cancelling leaves the code and cursor unchanged. Rapid submissions share the chooser and terminal startup; multiline terminal submissions remain ordered. A stopped or disconnected Interactive target also opens this chooser. Explicit `terminal` mode retains terminal behavior; explicit `interactive` mode offers Interactive targets only.
+- **Bind Document to Interactive Session** pins a source document to the selected session. Notebook cells and Interactive input are bound automatically. Switching tabs does not redirect an already-bound document's requests.
+- The **Workspace** viewer follows the focused Interactive window or bound source document. Its header identifies the session and PID. Unbound source files keep the last selected session. Background results refresh their own session without changing the selected workspace.
+- Workspace **View**, **Remove**, **Clear**, **Save**, and **Load** target the session displayed when the action starts, including across focus changes during a dialog. Object names containing spaces or quotes are supported. A stopped, restarting, or disconnected session displays its state in the viewer; detaching clears it. Expanded data viewers retain their original session.
+
+### R execution and input
+
+- Code runs in `.GlobalEnv`; visible results update `.Last.value`. Output is streamed during execution. Messages, warnings, errors, and traces are represented separately from ordinary console output. Errors show their message followed by the user calls, omitting the worker, arf transport, and condition-handler scaffolding. Saved R and Jupyter notebooks retain both the message and trace.
+- `readline()`, `scan()`, and `browser()` prompts appear as input requests. Canceling the input box leaves R waiting; **Reply to Interactive Input** opens it again. **Interrupt Interactive Session** signals the R process while preserving the environment when R handles the interrupt.
+- R remains single-threaded. A native call that does not check interrupts may delay cancellation. Arbitrary environment inspection and table queries are not executed concurrently with user code; cached workspace information remains visible while R is busy.
+- A rerun creates a new execution identity and history entry. Submissions with an existing identity are deduplicated. Reconnect never resubmits code automatically. Ambiguous dispatch failures block the queue until completion or process exit establishes what happened.
+- A client control lease prevents two windows from submitting simultaneously. Other clients can observe retained output; **Take Control of Interactive Session** explicitly transfers control.
+
+External terminal output observed through the arf console bridge is retained in terminal-origin history entries. When arf invokes R task callbacks, the completed command can also be recorded. Some arf evaluation paths omit those callbacks; their output is labeled as having unavailable source and is grouped into short output batches. This does not reconstruct exact terminal execution boundaries or provide a second live editor input surface. Arf may reject editor submissions while a terminal user is typing or R is otherwise occupied.
+
+### Language features
+
+- Separate language-server processes serve virtual documents with the session's R executable, library paths, and working directory. Cell and input diagnostics lint the live text with lintr's disk cache disabled, because virtual documents have no corresponding R source file. Blank or whitespace-only Interactive prompts clear diagnostics and ignore late lint replies; nonempty code and source files still receive normal diagnostics. Unsaved notebook cells also use a pathless language-server URI so namespace linters do not try to read a nonexistent file; diagnostics still map to the original cell. Source-file language servers retain the user's cache setting. Live completion and hover use the owning session with short timeouts. The existing source-file language-server configuration remains available.
+- Custom `.lintr` linter lists in cells and inputs require the [pathless-document settings fix in `languageserver`](https://github.com/REditorSupport/languageserver/pull/782). `languageserver` 0.3.20 selects default linters for these documents, even when source files use your configured rules. Updating the extension alone does not fix that package behavior.
+- Function hovers and parameter hints can use the owning session's cached function metadata, including while R is busy. After executing `fun1 <- function(x, y) x + y`, hovering over `fun1` shows its formals, and typing `fun1(` or `fun1(1, ` shows and highlights the corresponding parameter. Hints handle defaults, named arguments, `...`, nested expressions, and quoted names. Source-local definitions and package signatures from languageserver take priority. Session hints are a fallback for simple function names in source documents, notebook cells, and Interactive inputs; they do not evaluate code. Different sessions can define the same name with different signatures.
+
+## Rich outputs
+
+| Output | Behavior |
+| --- | --- |
+| Console, warnings, errors | Incremental output with per-execution limits and explicit truncation notices |
+| Base/grid/ggplot graphics | JGD frames retained by the agent and rendered as scalable SVG; independent font metrics work without a connected editor |
+| Incremental graphics | Recorded execution markers associate updates with their producing cell, including extensions of an existing plot |
+| Plot controls | Compact icons with labels for opening and resizing; **Save…** opens a native VS Code format picker for SVG and PNG |
+| Static fallback | Captured plots when JGD/systemfonts are unavailable or `plotBackend` is `standard` |
+| Data frames and matrices | On-demand inline pages (20/50/100 rows), first/last and page jumps, sorting, column filters/reordering and Reset; an expanded data viewer remains available. Requests stay bound to their originating session |
+| HTML widgets and HTML tags | Sandboxed browser output with copied local dependencies; dependencies remain after the R temporary source is gone |
+| Explicit MIME | `sess::display(x, mime = "text/markdown")`, HTML, and text formats |
+| Live applications | Forwarded loopback URLs opened in a viewer; applications such as Shiny still need their own running server and may occupy the R process |
+
+### Plots
+
+When one cell produces multiple plots, the output uses one paged plot viewer with **Previous plot**, **Plot n of m**, and **Next plot** controls. New plots appear on the latest page until you choose a page. Your choice is retained across output updates and reconnection. **Open**, **Save…**, and **Fit R device** act on the selected page; standard graphics images support Open and Save but have no live resize control. Pagination remains available in saved notebooks and after R stops or restarts. R notebook exports retain the gallery; Jupyter and HTML exports include every plot page.
+
+### Tables
+
+Table headings and values use the same alignment: numbers (including integer64 IDs) are right aligned and text is left aligned. **Text** switches a table to its ordinary R printout; **Table** switches back. The printout uses the object's class printer and the R print options at execution time, so data.table retains its type labels and tibble retains its usual compact printing. Switching does not execute R, and remains available while R is busy or stopped and in saved notebooks. Set `r.interactive.tableView` to `"text"` to use printed output by default, or `"table"` for the paged preview. Per-output choices override that default and survive reconnection. Explicit `print(x)` still produces normal console output.
+
+Printed snapshots require a session started with this extension build; older output explains why Text is unavailable. Snapshots retain at most 256 KiB of printed text, with a truncation notice. If a custom printer fails, the rich table remains available and the Text tooltip explains the failure. Live table paging and the full data viewer still require the original R process.
+
+Data inspection does not initialize or advance R's random-number stream, so opening a table between `set.seed()` and a simulation or train/test split leaves the draws unchanged. Inline tables retain a snapshot of up to **1,000 rows**, reduced to fit **100,000 cells** for wide tables (at least one row). Row subsetting gives data.table snapshots independent columns without a full deep copy. Later `:=`, `setnames()`, and `setorder()` calls do not change those saved rows. Reference assignments remain quiet like the R console; evaluate `DT` or use `DT[, x := value][]` to display the result, or call `View()` / `sess::display()` explicitly.
+
+The saved snapshot is **not a browsing limit**. The inline status initially shows **Saved preview** and the full row count; its tooltip and Text output identify the saved scope, for example **Snapshot: first 1,000 of 832,976,871 rows**. Moving beyond those rows automatically fetches a page from the uncopied original object and changes the status to **Live data**. Once browsing live data, navigation stays live until Reset. Later edits by reference can appear in these pages. The handle retains the original object; assigning a different object to the same variable does not retarget an old viewer.
+
+- Use **First**, **Previous**, **Next**, **Last**, or enter a page number and press **Go** / Enter. Choose **20**, **50**, or **100 rows** per page. Only the current fetched page is kept in the renderer; paging does not accumulate the dataset in browser memory.
+- Click a column heading to cycle ascending, descending, and original order. **Filters** offers operators appropriate to the R column type, including missing values, dates, booleans and exact integer64 values. Press **Apply** to run a filter; typing does not query R. Filters on different columns combine with AND, and each active filter has a remove button. Text comparisons are case-insensitive and use literal text.
+- Drag column headings to reorder them. Reordering changes presentation locally and leaves R data unchanged.
+- **Reset** restores the saved first page, 20 rows, original column order, and clears sorting, filters and unfinished filter text. It works locally after R stops and ignores outstanding replies. It does not interrupt an R operation already running; use the session's Interrupt control for that.
+
+Sorting and filtering a large table use the **full dataset**, even from the saved preview. They can scan all rows and allocate query indices; plain paging does neither. Cached queries are reused while paging and invalidated after R execution. When starting a new live query, a changed column schema clears incompatible sorting/filtering. If columns change during ordinary live navigation, use Reset and browse beyond the preview again to refresh, or reopen **Data viewer**. The expanded viewer opens the same full object without copying it and is labelled **Full data**.
+
+Inline page/query/order choices survive output updates in the current window, within a bounded cache of recently used tables. They are temporary: reloads and exports use the original saved output. The Text/Table preference is persisted separately. Live requests require the original R process; stopped or archived cells retain their available page and local Reset/Text/column controls. Sessions with the bounded-snapshot/full-data handles already support these editor-side controls after reloading VS Code. Older output without a full-data handle cannot dynamically expand a truncated snapshot.
+
+Column-header tooltips show R classes and storage types. Actual `NA` and `NaN` values have muted italic labels and explanatory tooltips, distinct from the literal string `"NA"`. Small nested values use readable JSON instead of `[object Object]`; large or deeply nested list cells show their class and size. Text previews shorten strings beyond 1,000 characters with a truncation marker. This prevents a single nested dataset or long string from creating an enormous cell. Inspect the original object in R for its complete contents. Full-view filters use the original string, including text beyond the displayed prefix. Numeric labels continue to use R's formatting without changing the values used in calculations.
+
+Full-table handles retain their original objects in R memory without an additional deep copy. Closing an expanded viewer or clearing completed cells does not release a handle that remains in the transcript. Distinct historical objects can therefore still retain substantial memory; use summaries or explicit `print(DT)` if you do not need a full-data handle. R's usual copy-on-modify rules still apply to later edits of shared ordinary data frames. The default Text view changes presentation only. The asset quota limits disk storage, not R heap usage.
+
+### Widgets and output controls
+
+JGD graphics and browser widgets have different interaction models: a static R plot can resize and export, while plotly/leaflet-style interaction comes from the widget's JavaScript. Arbitrary widget behavior that requires browser permissions or unavailable external network resources remains subject to the sandbox and server configuration.
+
+Table paging uses arrow icons with tooltips and accessible names. **Data viewer**, **Open plot**, and **Fit R device** retain short labels alongside their icons. **Save…** opens VS Code's native format picker without changing the cell height or scroll position, followed by the file save dialog. PNG is offered after the image loads. The picker supports typing, arrow-key navigation, Enter to select, and Escape to cancel. Each output allows one pending picker, and replies to replaced or disposed outputs are ignored.
+
+### Numeric formatting
+
+Inline numeric columns use R's `format()` with the session's `digits`, `scipen`, and `OutDec` options. For example, at the default `digits = 7`, `1417.39130434783` displays as `1417.391`. Formatting applies to each requested page, including column-wide decimal places and scientific notation, and HTML reports retain the preview's labels. Hover over a rounded value to inspect the full received number. Raw numeric values remain unchanged for calculations and the expanded data viewer's sorting/filtering; integer64 IDs and numeric-looking text remain exact. This uses base R numeric formatting, rather than class-specific printers such as tibble's pillar display.
+
+Already-running sessions and older saved outputs also get compact numeric display after updating the extension and reloading VS Code, using an approximation of R's default seven significant digits. Exact session-option formatting is available in new sessions using the updated bundled `sess`; existing R sessions can keep running. Previously recorded previews keep their original labels, while new page requests use the current session options.
+
+## Persistence, storage, and export
+
+The default registry is `$XDG_STATE_HOME/vscode-r/interactive` when `XDG_STATE_HOME` is a nonempty absolute path. Otherwise, new macOS installations use `~/Library/Application Support/vscode-r/interactive`, and Linux uses `~/.local/state/vscode-r/interactive`. An existing macOS registry at `~/.local/state/vscode-r/interactive` is reused so live sessions remain discoverable; it is never moved automatically.
+
+`r.interactive.storagePath` overrides the default. Use an absolute, writable path, and reload VS Code after changing it. Keep this directory on private, reliable storage on the R host. With Remote SSH, the path and environment belong to the remote host.
+
+If session creation reports `EACCES`, the storage directory or an ancestor is not writable by the R host's user. For example, a root-owned `~/.local` can prevent creating the Linux-style path on macOS. New macOS installations use Application Support to avoid this problem. For a custom path, choose a writable directory using `r.interactive.storagePath` and reload. Changing this setting selects a different registry; it does not migrate existing sessions. Reuse the original setting to reconnect to sessions stored there.
+
+Each session stores a manifest, immutable assets, and one journal directory per process generation. Private Unix sockets and credentials live in a mode-0700 runtime directory. The extension discovers existing agents after a reload and reconstructs the recent transcript. Asset URLs are regenerated through VS Code's remote forwarding support.
+
+With `r.interactive.restore` enabled (the default), reopening the same workspace reconnects its saved sessions, even when no R source file is open. Native Interactive tabs are matched by their saved URI, since VS Code does not retain their notebook metadata across reload. This restores the existing views without opening duplicate empty tabs. A failed reconnect preserves the saved association for a later retry. Sessions remain discoverable through **R: Open Interactive Session** from another workspace or when automatic restoration is disabled. Closing a view or choosing **Disconnect** removes its automatic-restoration entry while leaving R alive.
+
+Admission and completion records are flushed to disk. Ordinary output is buffered by the OS, so a machine crash can lose recent output. The execution ledger prevents automatic duplicate evaluation; it does not make arbitrary R code transactional. If the agent dies during a request, the outcome can remain unknown. R process death loses in-memory objects even when its transcript survives.
+
+**Detach** and closing a notebook leave R running. **Stop** terminates R and its graphics worker; the agent serves the open retained transcript until its final client disconnects. **Restart** creates a new process generation and environment in the same window. Restart boundaries and prior generations are restored from their journals when reconnecting, with the existing replay limits applied to each generation. History search includes all admitted commands across these generations, and exports include their retained output and restart boundaries. Old plot previews, saved widgets, and plot exports remain available; old table paging and R-device resizing are disabled because their live handles belonged to the previous process. Run the code again to create live output in the new process. Session restoration remembers open connections, not deliberately detached tabs.
+
+### Export history
+
+**Export Interactive History** supports:
+
+- `.R`: execution history as a script;
+- `.rnb`: code, execution metadata, retained output, and static plot fallbacks;
+- `.ipynb`: standard Jupyter cells with portable MIME output and an R kernelspec;
+- `.html`: an HTML report with a neighboring `.assets` directory containing plots and widget dependencies. Keep the two together.
+
+Choose the format first, then choose the destination in the save dialog. This also avoids macOS appending the wrong extension when several save filters are supplied. History and plot exports suggest names based on the session and default to its working directory. Expanded output tabs are named **Plot: session** or **Viewer: session** to distinguish them from the Interactive window.
+
+A saved `.rnb` contains no agent authentication token or forwarded asset URL. Table previews and static plot fallbacks can be read offline. Full interactive widgets and live table handles require reconnection to the originating session; use HTML export when sharing self-contained widget dependencies. IPYNB export retains standard MIME fallbacks; live session handles remain specific to R Interactive.
+
+Saved output disables controls that need an agent and explains how to reconnect. PNG export waits for the plot image to finish loading. Late plot updates preserve the cell's identity and any unsubmitted code edits. Fit R device works while plain R is idle and keeps historical plots associated with their original cells.
+
+### Updating the extension
+
+Existing agents keep running with the code and R bridge loaded when they started. Reloading VS Code updates editor behavior but does not update those agents. Features that require newer agent capabilities need a new or restarted session. Start a new session to use those features while preserving old work, or explicitly restart a managed session when its in-memory objects are no longer needed. Restart prepares and loads the current private R runtime. History search falls back to the restored transcript on older agents. Renaming updates the session list, status bar, and kernel label; an already-open native tab may retain its original title until reopened.
+
+### Retention limits
+
+Retention limits are configured in MiB (1 MiB = 1,048,576 bytes):
+
+```json
+{
+ "r.interactive.maxAssetSizeMiB": 1024,
+ "r.interactive.maxJournalSizeMiB": 128,
+ "r.interactive.maxOutputSizeMiB": 4
+}
+```
+
+These defaults allow **1 GiB of assets per session**, approximately 128 MiB of output journal per R generation, and 4 MiB of console text per execution. Fractional MiB values are supported and converted to whole bytes. Asset usage counts stored bytes after compression where supported. Output and journal setting changes apply to new or restarted sessions. The asset limit also updates connected sessions controlled by this window without restarting R.
+
+These limits do not cap total session storage: earlier R generations and execution records (including submitted code) remain separately retained. Journal rotation removes old output in roughly 4 MiB segments. Reopening a window restores about 3 MiB of recent execution data per R generation, independently of these retention limits, so a retained execution's full output may not fit in the restored window. Truncation is explicit; admission records remain for deduplication.
+
+Plot storage follows this lifecycle:
+
+- Incremental JGD drawing updates are combined over 200 ms, and pending updates for an execution are flushed when it finishes. The agent saves SVG snapshots; it keeps JGD's drawing operations in memory for live plot handling instead of also saving redundant JSON frame files.
+- Generated SVG/JSON assets of at least 4 KiB use gzip when it reduces their size. Identical content is deduplicated. Display and export decode transparently; exported SVG/JSON files remain ordinary files. Existing uncompressed assets remain readable. HTML dependencies retain their original encoding and directory structure.
+- Automatic cleanup starts when a write would exceed 80% of the quota. It removes superseded snapshots and unreferenced generated assets. The latest display version in every retained journal generation is protected, including all dependencies of retained HTML widgets. When journal rotation removes an output's last reference, its assets become eligible for cleanup. A corrupt or unreadable journal prevents cleanup.
+- **R: Clean Up Interactive Assets**, also in the session context menu, runs cleanup immediately and reports reclaimed space and current usage. Clearing cells only hides them; it does not erase durable history or make their final plots eligible for cleanup.
+- The hard limit still applies when all remaining assets are referenced. A failed plot retention is reported once per execution, and R keeps running. Increasing `r.interactive.maxAssetSizeMiB` updates connected sessions that support asset management and that this window controls, without restarting R. Lowering it below protected output size is rejected.
+
+Cleanup preserves distinct historical plots. Compression savings depend on the output, so plot count alone cannot predict storage use. To release all storage for unused work, export it and remove that **stopped** session's storage directory. Do not delete live session storage.
+
+## Known limitations
+
+- Persistence does not checkpoint R memory. An R crash, process termination, host reboot, or server logout policy can still end a session.
+- Native Interactive input drafts are not guaranteed to survive a full application exit. Save unfinished code in a source file before quitting.
+- VS Code's accessibility announcements can expose the selected custom MIME payload as JSON. The public renderer/controller API does not provide separate announcement text.
+- Widget frames use a fixed height, and an already-open native Interactive tab can retain its original title after renaming the session.
+- Local lifecycle tests and Linux tmux CI do not establish behavior for every Remote SSH connection or server-specific systemd/logout policy. Validate those on the intended host.
+
+## Contributing
+
+The [architecture and backend contract](https://github.com/REditorSupport/vscode-R/blob/main/src/interactive/README.md), [test instructions](https://github.com/REditorSupport/vscode-R/blob/main/CONTRIBUTING.md#testing-r-interactive), and [analysis fixtures](https://github.com/REditorSupport/vscode-R/blob/main/src/test/examples/README.md) live with the source.
diff --git a/website/docs/features/r-terminals.md b/website/docs/features/r-terminals.md
new file mode 100644
index 000000000..e7742c1bc
--- /dev/null
+++ b/website/docs/features/r-terminals.md
@@ -0,0 +1,90 @@
+# Interacting with R terminals
+
+## Creating R terminal
+
+In VS Code window, press F1 (or Ctrl + Shift + P) and
+choose "R: Create R terminal" command, then the VS Code terminal will be
+revealed and an R terminal will be launched.
+
+By default, the official `R` terminal is launched.
+
+Set `r.consolePath` to use an alternative console. For new configurations, when
+it is unset, vscode-R uses `r.executablePath`, then the system R installation.
+
+
+
+For an alternative R console, see [arf](https://github.com/eitsupi/arf).
+
+If the R session watcher is enabled, then it will attach to the R session
+whenever a new R terminal is created. The status of the session watcher is shown
+in the status bar like below. Managed terminals reconnect automatically after a
+VS Code window reload.
+
+
+
+## Sending code to R terminals
+
+By default, if there is no active R terminal, then a new R terminal will be
+created before sending code to it. To always send code to the active terminal
+without creating a new one, turn on `r.alwaysUseActiveTerminal` in VS Code
+settings.
+
+The behavior of sending code to the terminal is following:
+
+- If a range of code is selected, then the selected code will be sent to the
+ terminal.
+- If no code is selected, then an executable range of code will be sent to the
+ terminal and the cursor will move to the next line.
+
+## Using multiple R terminals
+
+Each time "R: Create R terminal" is executed, a new R terminal is created. The
+user could switch between these R terminals, and customize the icon color and
+the label of each terminal.
+
+
+
+To activate the session belonging to the current R terminal, click the status
+bar item or run **R: Activate R Session**.
+
+## Using self-managed R terminals
+
+Self-managed R terminals could be useful if one needs one or more R sessions to
+be preserved so that closing the VS Code window does not terminate the R
+sessions. On Linux and macOS, both
+[`screen`](https://www.gnu.org/software/screen/) and
+[`tmux`](https://github.com/tmux/tmux/wiki) could be used to preserve any number
+of R sessions or any other terminal programs in a customizable layout.
+
+To connect one, run **R: Attach External R Session (Copy command)** in VS Code,
+then paste and run the copied `source(...)` command in the target R session.
+The generated script installs or updates vscode-R's bundled `sess` package if
+needed and attaches the session to the current window.
+
+The old `~/.vscode-R/init.R` startup snippet was removed in v3.0.0. Remove any
+remaining block that sources it from `.Rprofile`.
+
+## Control console print width and text wrapping
+
+On some systems, users may notice that the full width of the R console is not being used. In the example below, we see that both the `LETTERS` vector and the columns of our dummy data frame are being hard wrapped at 80 characters, resulting in unnecessary overflow of rows instead of utilizing the available horizontal space.
+
+
+
+## Workspace viewer
+
+The workspace viewer displays the information of the objects in the global
+environment of the attached R session.
+
+Objects could be viewed (sending `View(obj)` to the terminal) or removed
+(sending `rm(...)` to the terminal).
+
+Lists, environments, pairlists, S4 and R6 objects, and data frames can be
+expanded recursively. Large objects load 500 items at a time; select the `...`
+row to load the next group.
+
+
+
+## Help pages viewer
+
+The help pages viewer lists several options to work with help pages, topics, and
+packages.
+
+
+
+## Package management
+
+In the help pages viewer, one can also install and remove packages. In the
+viewer, pressing any key will trigger the search mode so that one can easily
+find a package by name.
+
+
diff --git a/website/docs/getting-started.md b/website/docs/getting-started.md
new file mode 100644
index 000000000..5c72a2318
--- /dev/null
+++ b/website/docs/getting-started.md
@@ -0,0 +1,70 @@
+# Getting Started
+
+For many R users, [RStudio](https://github.com/rstudio/rstudio) has long been a
+great integrated development environment for data analysis and visualization. It
+provides a rich set of features that make it unprecedentedly easy to perform a
+wide range of tasks interactively.
+
+[VS Code](https://code.visualstudio.com/), in contrast, is not specifically
+designed for a certain programming language. It is highly customizable through
+[settings](https://code.visualstudio.com/docs/getstarted/settings), and highly
+extensible through [extensions](https://marketplace.visualstudio.com/). It
+supports many programming languages at different levels through language
+extensions that implement some common protocols such as the
+[Language Server Protocol](https://microsoft.github.io/language-server-protocol)
+to enable language features based on code analysis such as _Go To Definition_
+and _Rename symbol_, and the
+[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/) to
+enable interactive debugging of any target.
+
+This vscode-R extension is an extension that attempts to make it easier to write
+R code and work with R sessions interactively in VS Code. Though vscode-R
+[provides support](./features/rstudio-addins.md)
+emulating RStudio's features, it is not intended to be a full drop-in
+replacement for RStudio. In contrast, vscode-R is useful for those who want a
+unified development environment to work with multiple programming languages such
+as R, Python, C++, etc., as well as those who need to work with remote servers,
+containers, self-managed R sessions or multiple R sessions at the same time.
+
+vscode-R requires VS Code 1.101 or later. To enjoy the full R development
+experience, install the extension and language server, then choose any optional
+tools you need:
+
+- [vscode-R](https://marketplace.visualstudio.com/items?itemName=REditorSupport.r):
+ Provides R language service, R Markdown, and interactivity between VS Code and
+ R terminals. When first creating a managed R terminal, accept the prompt to
+ install the bundled `sess` R package; it does not need to be installed
+ manually.
+
+- [languageserver](https://github.com/REditorSupport/languageserver): An R
+ package that implements the Language Server Protocol for R to provide a wide
+ range of language analysis features such as auto-completion, function
+ signature, documentation, symbol highlight, document outline, code formatting,
+ symbol hover, diagnostics, go to definition, find references, etc.
+
+- [arf](https://github.com/eitsupi/arf) (optional): An alternative R console.
+ See its repository for installation and configuration.
+
+- [VSCode-R-Debugger](https://github.com/ManuelHentschel/VSCode-R-Debugger): A
+ VS Code extension to support R debugging capabilities.
+
+- [`jgd`](https://github.com/REditorSupport/jgd) or
+ [`httpgd`](https://github.com/nx10/httpgd) (optional): Interactive graphics
+ devices used by the
+ [plot viewer](./features/plot-viewer.md).
+ The default `r.plot.backend` value, `auto`, tries JGD first, then httpgd, then
+ the standard viewer.
+
+- [rmarkdown](https://rmarkdown.rstudio.com): An R package and format for
+ creating reproducible and narrative-driven data analyses. vscode-R provides
+ tooling to edit, run, and knit Rmarkdown files.
+
+- [Pandoc](https://pandoc.org) (optional): A powerful document conversion tool.
+ vscode-R uses this to render help previews when users hover over R code.
+
+However, the astounding flexibility of VS Code comes at a cost that some users
+might not find enjoyable in the beginning: Some setup and configuration are
+needed to make each part work well together. To minimize that cost, please refer
+to the detailed installation instructions we provide for
+[Windows](./installation/windows.md), [macOS](./installation/macos.md) and
+[Linux](./installation/linux.md).
diff --git a/website/docs/guide/package-development.md b/website/docs/guide/package-development.md
new file mode 100644
index 000000000..ac5e24dd8
--- /dev/null
+++ b/website/docs/guide/package-development.md
@@ -0,0 +1,37 @@
+# Package development
+
+Package development is supported by vscode-R,
+[R language server](https://github.com/REditorSupport/languageserver), and
+[R debugger](https://github.com/ManuelHentschel/VSCode-R-Debugger).
+
+## Commands
+
+vscode-R mainly provides the mostly used package development commands:
+
+| Title | Command | R code |
+| --------------- | ------------ | ---------------------- |
+| Build package | `r.build` | `devtools::build()` |
+| Test package | `r.test` | `devtools::test()` |
+| Check package | `r.check` | `devtools::check()` |
+| Install package | `r.install` | `devtools::install()` |
+| Document | `r.document` | `devtools::document()` |
+| Load all | `r.loadAll` | `devtools::load_all()` |
+
+
+Keyboard shortcuts could be bound to these commands. See
+[Creating keybindings for R commands](../configuration/keyboard-shortcuts.md#creating-keybindings-for-r-commands).
+
+## Development
+
+The [R language server](https://github.com/REditorSupport/languageserver) loads
+all R documents in `./R` if it detects a `NAMESPACE` file in the workspace root
+folder, which indicates that the workspace contains an R package. Therefore, all
+these R files are considered in the same workspace, sharing completions,
+definitions, references, and other workspace-level language features.
+
+## Debugging
+
+The [R debugger](https://github.com/ManuelHentschel/VSCode-R-Debugger) supports
+debugging the package code in the current workspace. See
+[Debugging R packages](https://github.com/ManuelHentschel/VSCode-R-Debugger#debugging-r-packages)
+for more details.
diff --git a/website/docs/guide/r-markdown.md b/website/docs/guide/r-markdown.md
new file mode 100644
index 000000000..9d3eef0d1
--- /dev/null
+++ b/website/docs/guide/r-markdown.md
@@ -0,0 +1,110 @@
+# R Markdown
+
+R Markdown document creation is supported with the following features:
+
+- Chunk highlighting
+- Chunk navigation commands (Select current chunk, go to previous/next chunks,
+ etc.)
+- Chunk execution commands (Run current chunk, run above/below chunks, etc.)
+- Automatic evaluation of YAML `params` before running code
+- Rmd render commands (Knit, Knit to PDF/HTML/All)
+- Live preview rmd (as html)
+- Create new draft from a template
+
+## File association
+
+By default, `Rmd` files are open as Markdown documents. To enable R Markdown features, you need to associate `*.Rmd` files with `rmd` language. Add an entry Item `*.Rmd` and Value `rmd` in the VS Code settings editor:
+
+
+
+or directly update `settings.json` with the following:
+
+```json
+{
+ "files.associations": {
+ "*.Rmd": "rmd"
+ }
+}
+```
+
+## Installing pandoc
+
+[pandoc](https://pandoc.org) is required to render R Markdown documents. Visit [Installing pandoc](https://pandoc.org/installing.html) for instructions.
+
+You may need to restart VS Code for `rmarkdown` to be able to detect `pandoc`.
+
+## Editing R Markdown documents
+
+
+
+When an R Markdown document declares `params` in its YAML header, vscode-R
+evaluates them into the R session before running code from the document. A
+custom shortcut to load the parameters is not required.
+
+## Knitting R Markdown documents
+
+R Markdown documents can be knit in a VSCode-R managed background process when
+using the knit command. Beyond the use of a background process, this has the
+following features:
+
+- Set knitr document directory
+- Knit progress tracking
+- Smart knitting
+
+### Set knitr document directory
+
+By default, knitr evaluates documents as though they are the root folder. For
+instance, calling `source` in a document will use the document's folder as the
+working directory, not the document's workspace. This can be modified in
+VSCode-R, so as to tell knitr if we want to evaluate from the workspace root or
+the document directory.
+
+
+
+### Progress tracking
+
+Knit progress is tracked via a progress bar, and can be viewed in the R Markdown
+output stream. Progress is determined by the percentages reported in the R
+Markdown output stream and may not be 100% accurate.
+
+
+
+### Smart knitting
+
+The knit button is "smart" in that it checks the document and its workspace for
+context when knitting. For instance, if a document has a knit function defined
+in the YAML header, the knit button will call the custom function when knitting.
+This also works for R Markdown sites, where the knit button will call
+`rmarkdown::render_site` instead of `rmarkdown::render`.
+
+## Live rendering R Markdown documents
+
+You can live preview R Markdown documents by pressing the "Open Preview to Side"
+button when focused on an R Markdown document.
+
+
+
+You can also preview a document by right-clicking it in the explorer and
+selecting preview.
+
+You can also run the following code and a browser viewer will open with live
+rendering of the R Markdown document.
+
+```r
+rmarkdown::run("your-rmd-document.Rmd")
+```
+
+## Live previewing rendered R Markdown documents
+
+When an R Markdown document is knit and rendered to an HTML file, [Live Preview](https://marketplace.visualstudio.com/items?itemName=ms-vscode.live-server) can be used to live preview the HTML document. It supports auto-refresh when the HTML file is updated.
+
+## Templates
+
+You can run "R Markdown: New Draft" from the command palettes to create a new draft from an R Markdown template.
+
+The following is a (incomplete) list of packages that provide R Markdown templates:
+
+* [rmarkdown](https://rmarkdown.rstudio.com/gallery.html)
+* [rticles](https://pkgs.rstudio.com/rticles/index.html)
+* [tufte](https://rstudio.github.io/tufte/)
+* [prettydoc](https://prettydoc.statr.me/)
diff --git a/website/docs/index.md b/website/docs/index.md
new file mode 100644
index 000000000..37040a7c2
--- /dev/null
+++ b/website/docs/index.md
@@ -0,0 +1,114 @@
+---
+layout: home
+title: R Extension for Visual Studio Code
+titleTemplate: false
+
+hero:
+ name: vscode-R
+ text: R Extension for Visual Studio Code
+ tagline: Language service based on static code analysis, and interactivity between VS Code and R sessions.
+ image:
+ src: /logo.svg
+ alt: R logo
+ actions:
+ - theme: brand
+ text: Getting Started
+ link: /getting-started
+ - theme: alt
+ text: Windows
+ link: /installation/windows
+ - theme: alt
+ text: macOS
+ link: /installation/macos
+ - theme: alt
+ text: Linux
+ link: /installation/linux
+---
+
+
+
+Then the default settings should work out of the box. Otherwise, set
+`r.consolePath` to the R console executable used by **R: Create R terminal**.
+Use `r.executablePath` separately if background processes require a different,
+vanilla R executable.
+
+## languageserver
+
+[languageserver](https://github.com/REditorSupport/languageserver) is an
+implementation of the
+[Language Server Protocol](https://microsoft.github.io/language-server-protocol/)
+for R.
+
+Run the following commands in R.
+
+You may install the latest stable release from CRAN:
+
+```r
+install.packages("languageserver")
+```
+
+or install the development version with the newest features:
+
+```r
+remotes::install_github("REditorSupport/languageserver")
+```
+
+which requires [Rtools](https://cran.r-project.org/bin/windows/Rtools/) to
+build.
+
+You can also install the `rmarkdown` package and Pandoc rendering library to see
+formatted R help pages upon [hover](../features/language-service.md#hover). Previews of function documentation
+without these dependencies will show a plain page.
+
+`rmarkdown` can be installed with:
+
+```r
+install.packages("rmarkdown")
+```
+
+Pandoc is
+[automatically installed](https://alexd106.github.io/intro2R/install_rmarkdown.html)
+if you have RStudio on your machine. See the official installation guide
+[here](https://pandoc.org/installing.html) if you do not have RStudio.
+
+## VSCode-R-Debugger
+
+[VSCode-R-Debugger](https://marketplace.visualstudio.com/items?itemName=RDebugger.r-debugger)
+is a VS Code extension that implements R debugging capabilities. It depends on
+[vscDebugger](https://github.com/ManuelHentschel/vscDebugger).
+
+1. Install VSCode-R-Debugger extension in VS Code.
+2. Install vscDebugger package via
+
+```r
+remotes::install_github("ManuelHentschel/vscDebugger")
+```
+
+## Plot backends
+
+vscode-R supports two optional interactive plot backends:
+
+- [JGD](https://github.com/REditorSupport/jgd) is lightweight, has no external
+ R-package dependencies, and is usually simpler to install.
+- [httpgd](https://github.com/nx10/httpgd) provides a mature, feature-rich SVG
+ viewer over HTTP and WebSockets, but has a larger compiled dependency
+ footprint.
+
+Install either or both:
+
+```r
+install.packages("jgd")
+install.packages("httpgd", repos = c("https://nx10.r-universe.dev", "https://cran.r-project.org"))
+```
+
+Leave `r.plot.backend` at its default value, `"auto"`, to try JGD first, then
+httpgd, then the standard viewer. You can instead set it explicitly to `"jgd"`
+or `"httpgd"`. See [Plot viewer](../features/plot-viewer.md) for details.
+
+## Troubleshooting WSL
+
+The connection between VSCode and R may fail if an R session is started on
+Windows Subsystem for Linux (WSL/WSL2), but VSCode is started outside of the WSL
+environment (e.g. on plain Windows). For R to work, you must open VSCode _on
+WSL_ with the `code