From 023716e9184821372e200848b4afae0a92b87651 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A1bor=20Cs=C3=A1rdi?= <csardi.gabor@gmail.com>
Date: Thu, 1 Oct 2026 12:44:32 +0200
Subject: [PATCH 1/3] Inline scripts

See docs.
---
 NEWS.md                      |   5 +
 src/args.rs                  |   1 +
 src/cache_cmd.rs             |  18 +-
 src/data/rvenv/R.sh          |   4 +-
 src/help-generated.in        |   6 +-
 src/help/cache-clean.md      |   3 +-
 src/help/cache-info.md       |   5 +-
 src/help/run.md              |  39 ++-
 src/main.rs                  |   2 +
 src/proj.rs                  | 215 ++++++++++++--
 src/rvenv.rs                 |  41 ++-
 src/script_meta.rs           | 561 +++++++++++++++++++++++++++++++++++
 src/scrun.rs                 | 105 ++++++-
 src/stdout_redirect.rs       | 109 +++++++
 tests/test-linux.sh          |  44 +++
 tests/test-macos.sh          |  44 +++
 website/_partials/faq.md     |  23 ++
 website/assets/logo-mono.svg |  26 ++
 website/assets/logo.svg      |  45 +++
 19 files changed, 1256 insertions(+), 40 deletions(-)
 create mode 100644 src/script_meta.rs
 create mode 100644 src/stdout_redirect.rs
 create mode 100644 website/assets/logo-mono.svg
 create mode 100644 website/assets/logo.svg

diff --git a/NEWS.md b/NEWS.md
index 2fa57bcf4..122be64e7 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,5 +1,10 @@
 # Development version
 
+* `rig run` now support self-contained scripts, that declare the packages
+  and the R version they need in a `# /// script` comment block. rig then
+  runs the script in its own environment, in the cache directory, and
+  installs R and the packages as needed.
+
 * `rig add` now has a `--json` option. It prints information about the
   installed R version (or the already installed version that was kept),
   including whether it is a new installation and whether it is the default.
diff --git a/src/args.rs b/src/args.rs
index ca0c41674..79647ca44 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -1261,6 +1261,7 @@ pub fn rig_app() -> Command {
                             "p3m",
                             "git-mirrors",
                             "url-pkgs",
+                            "scripts",
                         ]),
                 ),
         );
diff --git a/src/cache_cmd.rs b/src/cache_cmd.rs
index e99bb5888..645b4a55a 100644
--- a/src/cache_cmd.rs
+++ b/src/cache_cmd.rs
@@ -5,7 +5,7 @@
 //! their own corner of `real_cache_dir()`, see [`crate::cache`]. Rather than
 //! teach this module every producer's file-naming scheme, categories are
 //! derived from the *name of the top-level entry* in the cache directory:
-//! `built`, `packages`, `p3m`, `git-mirrors` and `url-pkgs` are their own
+//! `built`, `packages`, `p3m`, `git-mirrors`, `url-pkgs` and `scripts` are their own
 //! category, `metadata` collects every other kind of package metadata
 //! (binary indexes, CRAN-like databases, package manifests, repo data), and
 //! anything unrecognized left over at the cache root (e.g. stray files from
@@ -30,16 +30,18 @@ enum CacheCategory {
     P3m,
     GitMirrors,
     UrlPkgs,
+    Scripts,
 }
 
 impl CacheCategory {
-    const ALL: [CacheCategory; 6] = [
+    const ALL: [CacheCategory; 7] = [
         CacheCategory::Built,
         CacheCategory::Packages,
         CacheCategory::Metadata,
         CacheCategory::P3m,
         CacheCategory::GitMirrors,
         CacheCategory::UrlPkgs,
+        CacheCategory::Scripts,
     ];
 
     fn label(self) -> &'static str {
@@ -50,6 +52,7 @@ impl CacheCategory {
             CacheCategory::P3m => "P3M status",
             CacheCategory::GitMirrors => "Git mirrors",
             CacheCategory::UrlPkgs => "URL packages",
+            CacheCategory::Scripts => "Script environments",
         }
     }
 
@@ -63,6 +66,7 @@ impl CacheCategory {
             CacheCategory::P3m => "p3m",
             CacheCategory::GitMirrors => "git-mirrors",
             CacheCategory::UrlPkgs => "url-pkgs",
+            CacheCategory::Scripts => "scripts",
         }
     }
 }
@@ -76,6 +80,7 @@ fn classify_entry(name: &str) -> CacheCategory {
         "p3m" => CacheCategory::P3m,
         "git-mirrors" => CacheCategory::GitMirrors,
         "url-pkgs" => CacheCategory::UrlPkgs,
+        "scripts" => CacheCategory::Scripts,
         _ => CacheCategory::Metadata,
     }
 }
@@ -120,8 +125,8 @@ fn dir_usage(path: &Path) -> Usage {
     usage
 }
 
-fn cache_breakdown(cache_dir: &Path) -> [Usage; 6] {
-    let mut totals = [Usage::default(); 6];
+fn cache_breakdown(cache_dir: &Path) -> [Usage; CacheCategory::ALL.len()] {
+    let mut totals = [Usage::default(); CacheCategory::ALL.len()];
     let entries = match fs::read_dir(cache_dir) {
         Ok(entries) => entries,
         Err(_) => return totals,
@@ -180,6 +185,8 @@ struct CacheInfo {
     git_mirrors_count: u64,
     url_pkgs_size: u64,
     url_pkgs_count: u64,
+    scripts_size: u64,
+    scripts_count: u64,
     total_size: u64,
     total_count: u64,
 }
@@ -208,6 +215,8 @@ pub fn sc_cache_info(args: &ArgMatches) -> Result<(), Box<dyn Error>> {
             git_mirrors_count: totals[4].count,
             url_pkgs_size: totals[5].size,
             url_pkgs_count: totals[5].count,
+            scripts_size: totals[6].size,
+            scripts_count: totals[6].count,
             total_size: total.size,
             total_count: total.count,
         };
@@ -316,6 +325,7 @@ mod tests {
         assert_eq!(classify_entry("leftover-file"), CacheCategory::Metadata);
         assert_eq!(classify_entry("git-mirrors"), CacheCategory::GitMirrors);
         assert_eq!(classify_entry("url-pkgs"), CacheCategory::UrlPkgs);
+        assert_eq!(classify_entry("scripts"), CacheCategory::Scripts);
     }
 
     #[test]
diff --git a/src/data/rvenv/R.sh b/src/data/rvenv/R.sh
index fa95cfc95..ecbf1f5ce 100644
--- a/src/data/rvenv/R.sh
+++ b/src/data/rvenv/R.sh
@@ -8,7 +8,9 @@
 #
 # RVENV is derived from this script's own location, so the project directory
 # can be moved or checked out anywhere.
-RVENV=$(cd "$(dirname "$0")/.." && pwd)
+# `${0%/*}` instead of `dirname`, which would be one more process to start.
+case $0 in */*) RVENV=${0%/*} ;; *) RVENV=. ;; esac
+RVENV=$(cd "$RVENV/.." && pwd)
 export RVENV
 # R_LIBS is empty, so that .libPaths()[1] stays the project library, and
 # R_LIBS_SITE points at a path that cannot exist, because an empty one does
diff --git a/src/help-generated.in b/src/help-generated.in
index a8617d613..7817c60f7 100644
--- a/src/help-generated.in
+++ b/src/help-generated.in
@@ -10,9 +10,9 @@ const HELP_ADD: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  D
 const ABOUT_AVAILABLE: &str = "List R versions available to install.";
 const HELP_AVAILABLE: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  List R versions available to install.\n\n  By default some releases are omitted from the output:\n\n  - Versions older than R 3.0.0 are omitted. The installation of these might\n    not work at all.\n  - Only the latest release is shown for each minor version. E.g. R 4.2.3 is\n    listed, but other R 4.2.x versions are not. Use \u{1b}[32m--all\u{1b}[39m to list all\n    versions.\n\n  Use \u{1b}[32m--json\u{1b}[39m to return the output in JSON. JSON output includes the full time\n  stamp (if available) and the download URL as well.\n\n  With the \u{1b}[32m--list-distros\u{1b}[39m flag it lists supported Linux distributions.\n\n  With the \u{1b}[32m--list-rtools-versions\u{1b}[39m flag it lists supported Rtools versions.\n  Rtools contains tools to build R and R packages on Windows. Use \u{1b}[32m--all\u{1b}[39m to\n  list all Rtools versions, even very old ones.";
 const ABOUT_CACHE_CLEAN: &str = "Delete cached files";
-const HELP_CACHE_CLEAN: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Deletes files from rig's cache directory. With no options, deletes the\n  whole cache. Use \u{1b}[32m--category\u{1b}[39m to delete only one category of cached files\n  (\u{1b}[32mbuilt\u{1b}[39m, \u{1b}[32mpackages\u{1b}[39m, \u{1b}[32mmetadata\u{1b}[39m, \u{1b}[32mp3m\u{1b}[39m, \u{1b}[32mgit-mirrors\u{1b}[39m or \u{1b}[32murl-pkgs\u{1b}[39m),\n  leaving the rest in place. See \u{1b}[32mrig cache info\u{1b}[39m\n  for what each category contains.";
+const HELP_CACHE_CLEAN: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Deletes files from rig's cache directory. With no options, deletes the\n  whole cache. Use \u{1b}[32m--category\u{1b}[39m to delete only one category of cached files\n  (\u{1b}[32mbuilt\u{1b}[39m, \u{1b}[32mpackages\u{1b}[39m, \u{1b}[32mmetadata\u{1b}[39m, \u{1b}[32mp3m\u{1b}[39m, \u{1b}[32mgit-mirrors\u{1b}[39m, \u{1b}[32murl-pkgs\u{1b}[39m or\n  \u{1b}[32mscripts\u{1b}[39m),\n  leaving the rest in place. See \u{1b}[32mrig cache info\u{1b}[39m\n  for what each category contains.";
 const ABOUT_CACHE_INFO: &str = "Show cache size and contents";
-const HELP_CACHE_INFO: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Prints the total size of rig's cache directory, broken down into\n  categories: packages rig built from source, downloaded package files,\n  package metadata (binary package indexes, CRAN-like package databases,\n  package manifests, and repository data), the cached PPM status document,\n  the persistent git mirrors kept for git/GitHub dependency resolution\n  (\u{1b}[32mrig proj lock\u{1b}[39m), and the downloaded archives kept for \u{1b}[32murl\u{1b}[39m dependency\n  resolution.\n\n  Use \u{1b}[32m--json\u{1b}[39m for machine-readable output.";
+const HELP_CACHE_INFO: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Prints the total size of rig's cache directory, broken down into\n  categories: packages rig built from source, downloaded package files,\n  package metadata (binary package indexes, CRAN-like package databases,\n  package manifests, and repository data), the cached PPM status document,\n  the persistent git mirrors kept for git/GitHub dependency resolution\n  (\u{1b}[32mrig proj lock\u{1b}[39m), the downloaded archives kept for \u{1b}[32murl\u{1b}[39m dependency\n  resolution, and the environments of scripts with inline dependencies\n  (\u{1b}[32mrig run script.R\u{1b}[39m).\n\n  Use \u{1b}[32m--json\u{1b}[39m for machine-readable output.";
 const ABOUT_CACHE: &str = "Manage rig's download cache";
 const HELP_CACHE: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  rig caches files it downloads (R binary indexes, CRAN-like package\n  databases, package DESCRIPTION manifests, downloaded package files, and\n  packages rig built from source) in an OS-specific cache directory, so it\n  does not have to re-download them on every run. See \u{1b}[32mrig system dirs --cache\u{1b}[39m\n  for the cache directory path.\n\n  The global \u{1b}[32m--no-cache\u{1b}[39m flag makes rig skip this cache entirely for the\n  current run; it does not affect what \u{1b}[32mrig cache\u{1b}[39m reports or deletes. You can\n  also set the \u{1b}[32mRIG_NO_CACHE\u{1b}[39m environment variable to \u{1b}[32mtrue\u{1b}[39m or the \u{1b}[32mno-cache\u{1b}[39m\n  config option to \u{1b}[32mtrue\u{1b}[39m.";
 const ABOUT_CONFIG_CONFIG_FILE_PATH: &str = "Print the path to the rig config file";
@@ -126,7 +126,7 @@ const HELP_RTOOLS_RM: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22
 const ABOUT_RTOOLS: &str = "Manage Rtools installations";
 const HELP_RTOOLS: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Manage Rtools installations (Windows only).\n\n  Rtools is the collection of build tools (compilers, \u{1b}[32mmake\u{1b}[39m, etc.) needed to\n  build R packages from source on Windows. Each R version needs a matching\n  Rtools version.\n\n  \u{1b}[32mrig rtools list\u{1b}[39m lists the installed Rtools versions. \u{1b}[32mrig rtools add\u{1b}[39m\n  installs Rtools, by default every version needed by the currently installed\n  R versions. \u{1b}[32mrig rtools rm\u{1b}[39m removes Rtools versions.\n\n  On non-Windows platforms this command does nothing and is hidden.";
 const ABOUT_RUN: &str = "Run R, an R script or an R project";
-const HELP_RUN: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Run R, an R script or an R project, using the selected R version.\n\n  All of these examples allow an \u{1b}[32m--r-version\u{1b}[39m argument, to use a specific R\n  version.\n\n  rig run                    # start R\n  rig run -f <script-file>   # run an R script\n  rig run -e <expression>    # evaluate an R expression\n  rig run <pkg>::<script>    # run a script from a package's exec directory\n  rig run <name>             # run a script the project declares\n  rig run --list             # list the scripts the project declares\n  rig run <path-to-app>      # run an R app\n  rig run --cmd <command>    # run `R CMD <command>`\n  rig run --activate         # start R with the selected version on PATH\n  rig run --shell            # start a shell with the selected version on PATH\n  rig run --rscript ...      # run `Rscript` instead of `R`\n  rig run -- --vanilla       # pass flags to R/Rscript\n\n\u{1b}[1m\u{1b}[34mSupported apps:\u{1b}[39m\u{1b}[22m\n  Currently supported apps are:\n\n  - Plumber APIs,\n  - Shiny apps,\n  - Quarto documents embedding Shiny apps,\n  - Quarto documents,\n  - Rmd documents,\n  - Rmd documents embedding Shiny apps,\n  - Static web sites.\n\n\u{1b}[1m\u{1b}[34mR arguments:\u{1b}[39m\u{1b}[22m\n  Anything after a literal \u{1b}[32m--\u{1b}[39m is passed straight to the R (or \u{1b}[32mRscript\u{1b}[39m)\n  process as its own command-line flags, e.g. \u{1b}[32mrig run -- --vanilla\u{1b}[39m.\n\n  Plain \u{1b}[32mrig run\u{1b}[39m (no \u{1b}[32m-e\u{1b}[39m/\u{1b}[32m-f\u{1b}[39m/app/\u{1b}[32m--cmd\u{1b}[39m) defaults to\n  \u{1b}[32m--no-save --no-restore\u{1b}[39m, so it never shows the \"Save workspace image?\"\n  prompt on exit. Override with \u{1b}[32mrig run -- --save --restore\u{1b}[39m.\n\n\u{1b}[1m\u{1b}[34mProjects:\u{1b}[39m\u{1b}[22m\n  If the current directory is inside a project, then \u{1b}[32mrig run\u{1b}[39m uses\n  the project's own environment instead of the default R version: it runs\n  \u{1b}[32m.rvenv/bin/R\u{1b}[39m. It also runs \u{1b}[32mrig proj lock\u{1b}[39m and \u{1b}[32mrig proj sync\u{1b}[39m as needed.\n\n  Use \u{1b}[32m--no-project\u{1b}[39m to ignore a project, or \u{1b}[32m--r-version\u{1b}[39m to select an R\n  version directly.\n\n\u{1b}[1m\u{1b}[34mProject scripts:\u{1b}[39m\u{1b}[22m\n  A project can give its own scripts a name, in the \u{1b}[32m[[bin]]\u{1b}[39m tables of its\n  \u{1b}[32mrproj.toml\u{1b}[39m:\n\n  [[bin]]\n  name = \"report\"\n  path = \"scripts/report.R\"\n  description = \"Build the report\"\n\n  \u{1b}[32mrig run report --format pdf\u{1b}[39m then runs \u{1b}[32mscripts/report.R\u{1b}[39m in the project's\n  environment, and passes \u{1b}[32m--format pdf\u{1b}[39m on to the script, where\n  \u{1b}[32mcommandArgs(TRUE)\u{1b}[39m picks it up. \u{1b}[32mpath\u{1b}[39m is relative to the project directory,\n  so a declared script works the same from anywhere within the project.\n  \u{1b}[32mrig run --list\u{1b}[39m lists the declared scripts, and \u{1b}[32m--json\u{1b}[39m prints them as JSON.\n\n  A declared name wins over a directory of the same name. Arguments that look\n  like a path rather than a name are never script names: anything containing\n  a slash or \u{1b}[32m::\u{1b}[39m, anything ending in \u{1b}[32m.R\u{1b}[39m, \u{1b}[32m.r\u{1b}[39m, \u{1b}[32m.Rmd\u{1b}[39m or \u{1b}[32m.qmd\u{1b}[39m, and \u{1b}[32m.\u{1b}[39m and \u{1b}[32m..\u{1b}[39m. Use\n  \u{1b}[32m./name\u{1b}[39m to run an app in a directory whose name a script has taken.\n\n\u{1b}[1m\u{1b}[34mActivation:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run --activate\u{1b}[39m puts the selected R version's \u{1b}[32mbin\u{1b}[39m directory on\n  \u{1b}[32mPATH\u{1b}[39m for the R process it starts. \u{1b}[32m--shell\u{1b}[39m starts a shell instead of R,\n  with the same \u{1b}[32mPATH\u{1b}[39m change, so \u{1b}[32mR\u{1b}[39m and its subprocesses start the\n  activated R version.\n\n  Inside a project, both flags put the project's \u{1b}[32m.rvenv/bin\u{1b}[39m on\n  \u{1b}[32mPATH\u{1b}[39m rather than the raw R installation, so a nested \u{1b}[32mR\u{1b}[39m (started from\n  the shell \u{1b}[32m--shell\u{1b}[39m opens, or from R itself) picks up the project's package\n  library and repositories too, not just its version.\n\n\u{1b}[1m\u{1b}[34mRscript:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run --rscript\u{1b}[39m runs the selected R version's \u{1b}[32mRscript\u{1b}[39m instead of \u{1b}[32mR\u{1b}[39m.\n  Unlike \u{1b}[32mR -e\u{1b}[39m/\u{1b}[32mR -f\u{1b}[39m, \u{1b}[32mRscript\u{1b}[39m never echoes back the code it runs, which\n  fits scripts and pipelines better than \u{1b}[32mR\u{1b}[39m's interactive-style echo.\n\n  \u{1b}[32m--rscript\u{1b}[39m works with \u{1b}[32m-e\u{1b}[39m/\u{1b}[32m-f\u{1b}[39m, project scripts, apps and \u{1b}[32m--activate\u{1b}[39m,\n  but not with \u{1b}[32m--cmd\u{1b}[39m (\u{1b}[32mR CMD\u{1b}[39m only exists as part of the \u{1b}[32mR\u{1b}[39m front-end) or\n  \u{1b}[32m--shell\u{1b}[39m (which never runs the R binary at all).";
+const HELP_RUN: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Run R, an R script or an R project, using the selected R version.\n\n  All of these examples allow an \u{1b}[32m--r-version\u{1b}[39m argument, to use a specific R\n  version.\n\n  rig run                    # start R\n  rig run <script.R>         # run an R script\n  rig run -f <script-file>   # run an R script\n  rig run -e <expression>    # evaluate an R expression\n  rig run <pkg>::<script>    # run a script from a package's exec directory\n  rig run <name>             # run a script the project declares\n  rig run --list             # list the scripts the project declares\n  rig run <path-to-app>      # run an R app\n  rig run --cmd <command>    # run `R CMD <command>`\n  rig run --activate         # start R with the selected version on PATH\n  rig run --shell            # start a shell with the selected version on PATH\n  rig run --rscript ...      # run `Rscript` instead of `R`\n  rig run -- --vanilla       # pass flags to R/Rscript\n\n\u{1b}[1m\u{1b}[34mSupported apps:\u{1b}[39m\u{1b}[22m\n  Currently supported apps are:\n\n  - Plumber APIs,\n  - Shiny apps,\n  - Quarto documents embedding Shiny apps,\n  - Quarto documents,\n  - Rmd documents,\n  - Rmd documents embedding Shiny apps,\n  - Static web sites.\n\n\u{1b}[1m\u{1b}[34mR arguments:\u{1b}[39m\u{1b}[22m\n  Anything after a literal \u{1b}[32m--\u{1b}[39m is passed straight to the R (or \u{1b}[32mRscript\u{1b}[39m)\n  process as its own command-line flags, e.g. \u{1b}[32mrig run -- --vanilla\u{1b}[39m.\n\n  Plain \u{1b}[32mrig run\u{1b}[39m (no \u{1b}[32m-e\u{1b}[39m/\u{1b}[32m-f\u{1b}[39m/app/\u{1b}[32m--cmd\u{1b}[39m) defaults to\n  \u{1b}[32m--no-save --no-restore\u{1b}[39m, so it never shows the \"Save workspace image?\"\n  prompt on exit. Override with \u{1b}[32mrig run -- --save --restore\u{1b}[39m.\n\n\u{1b}[1m\u{1b}[34mProjects:\u{1b}[39m\u{1b}[22m\n  If the current directory is inside a project, then \u{1b}[32mrig run\u{1b}[39m uses\n  the project's own environment instead of the default R version: it runs\n  \u{1b}[32m.rvenv/bin/R\u{1b}[39m. It also runs \u{1b}[32mrig proj lock\u{1b}[39m and \u{1b}[32mrig proj sync\u{1b}[39m as needed.\n\n  Use \u{1b}[32m--no-project\u{1b}[39m to ignore a project, or \u{1b}[32m--r-version\u{1b}[39m to select an R\n  version directly.\n\n\u{1b}[1m\u{1b}[34mScripts with inline dependencies:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run -f script.R\u{1b}[39m runs an R script (the \u{1b}[32m-f\u{1b}[39m can be omitted). A\n  script can declare the packages and the R version it needs in a comment\n  block at its top, so it runs anywhere without a project:\n\n  # /// script\n  # [dependencies]\n  # R = \">= 4.4\"\n  # cli = \"*\"\n  # dplyr = \">= 1.1\"\n  #\n  # [tool.rig]\n  # exclude-newer = \"2026-06-01\"\n  # ///\n  library(dplyr)\n\n  The block starts with a \u{1b}[32m# /// script\u{1b}[39m line and ends with a \u{1b}[32m# ///\u{1b}[39m line.\n  In between, every line is a comment, and without the leading \u{1b}[32m#\u{1b}[39m they form\n  a TOML document. The block takes the \u{1b}[32m[dependencies]\u{1b}[39m, \u{1b}[32m[[repository]]\u{1b}[39m and\n  \u{1b}[32m[tool.rig]\u{1b}[39m tables of \u{1b}[32mrproj.toml\u{1b}[39m, with the same meaning.\n\n  rig creates an environment for the script in its cache directory, and runs\n  the script there, isolated from your own package library. It picks an\n  installed R version that fits the \u{1b}[32mR\u{1b}[39m requirement, or installs one, then\n  locks and installs the packages, the same way \u{1b}[32mrig proj sync\u{1b}[39m does for a\n  project. Later runs reuse the environment. Scripts with the same block\n  share one environment, and changing the block creates a new one. A script\n  with a block always uses its own environment, even inside a project.\n  \u{1b}[32m--r-version\u{1b}[39m selects the R version, which must fit the \u{1b}[32mR\u{1b}[39m requirement.\n\n  \u{1b}[32mrig cache clean --category scripts\u{1b}[39m deletes all script environments. A\n  script can start with \u{1b}[32m#!/usr/bin/env -S rig run\u{1b}[39m, to run it directly.\n\n\u{1b}[1m\u{1b}[34mProject scripts:\u{1b}[39m\u{1b}[22m\n  A project can give its own scripts a name, in the \u{1b}[32m[[bin]]\u{1b}[39m tables of its\n  \u{1b}[32mrproj.toml\u{1b}[39m:\n\n  [[bin]]\n  name = \"report\"\n  path = \"scripts/report.R\"\n  description = \"Build the report\"\n\n  \u{1b}[32mrig run report --format pdf\u{1b}[39m then runs \u{1b}[32mscripts/report.R\u{1b}[39m in the project's\n  environment, and passes \u{1b}[32m--format pdf\u{1b}[39m on to the script, where\n  \u{1b}[32mcommandArgs(TRUE)\u{1b}[39m picks it up. \u{1b}[32mpath\u{1b}[39m is relative to the project directory,\n  so a declared script works the same from anywhere within the project.\n  \u{1b}[32mrig run --list\u{1b}[39m lists the declared scripts, and \u{1b}[32m--json\u{1b}[39m prints them as JSON.\n\n  A declared name wins over a directory of the same name. Arguments that look\n  like a path rather than a name are never script names: anything containing\n  a slash or \u{1b}[32m::\u{1b}[39m, anything ending in \u{1b}[32m.R\u{1b}[39m, \u{1b}[32m.r\u{1b}[39m, \u{1b}[32m.Rmd\u{1b}[39m or \u{1b}[32m.qmd\u{1b}[39m, and \u{1b}[32m.\u{1b}[39m and \u{1b}[32m..\u{1b}[39m. Use\n  \u{1b}[32m./name\u{1b}[39m to run an app in a directory whose name a script has taken.\n\n\u{1b}[1m\u{1b}[34mActivation:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run --activate\u{1b}[39m puts the selected R version's \u{1b}[32mbin\u{1b}[39m directory on\n  \u{1b}[32mPATH\u{1b}[39m for the R process it starts. \u{1b}[32m--shell\u{1b}[39m starts a shell instead of R,\n  with the same \u{1b}[32mPATH\u{1b}[39m change, so \u{1b}[32mR\u{1b}[39m and its subprocesses start the\n  activated R version.\n\n  Inside a project, both flags put the project's \u{1b}[32m.rvenv/bin\u{1b}[39m on\n  \u{1b}[32mPATH\u{1b}[39m rather than the raw R installation, so a nested \u{1b}[32mR\u{1b}[39m (started from\n  the shell \u{1b}[32m--shell\u{1b}[39m opens, or from R itself) picks up the project's package\n  library and repositories too, not just its version.\n\n\u{1b}[1m\u{1b}[34mRscript:\u{1b}[39m\u{1b}[22m\n  \u{1b}[32mrig run --rscript\u{1b}[39m runs the selected R version's \u{1b}[32mRscript\u{1b}[39m instead of \u{1b}[32mR\u{1b}[39m.\n  Unlike \u{1b}[32mR -e\u{1b}[39m/\u{1b}[32mR -f\u{1b}[39m, \u{1b}[32mRscript\u{1b}[39m never echoes back the code it runs, which\n  fits scripts and pipelines better than \u{1b}[32mR\u{1b}[39m's interactive-style echo.\n\n  \u{1b}[32m--rscript\u{1b}[39m works with \u{1b}[32m-e\u{1b}[39m/\u{1b}[32m-f\u{1b}[39m, scripts, project scripts, apps and \u{1b}[32m--activate\u{1b}[39m,\n  but not with \u{1b}[32m--cmd\u{1b}[39m (\u{1b}[32mR CMD\u{1b}[39m only exists as part of the \u{1b}[32mR\u{1b}[39m front-end) or\n  \u{1b}[32m--shell\u{1b}[39m (which never runs the R binary at all).";
 const ABOUT_SELF_UNINSTALL: &str = "Remove the rig installation";
 const HELP_SELF_UNINSTALL: &str = "\u{1b}[1m\u{1b}[34mDescription:\u{1b}[39m\u{1b}[22m\n  Removes the \u{1b}[32mrig\u{1b}[39m binary, its shell completions, and the PATH entry the\n  install script added, then deletes itself.\n\n  This only works if rig was installed with the install script (\u{1b}[32minstall.sh\u{1b}[39m\n  on macOS/Linux, \u{1b}[32minstall.ps1\u{1b}[39m on Windows).\n\n  \u{1b}[32mrig self uninstall\u{1b}[39m only removes rig itself. It does not remove rig's\n  configuration, its download/build cache, or any R version it installed.\n  Use \u{1b}[32mrig rm\u{1b}[39m to remove R version and \u{1b}[32mrig cache clean\u{1b}[39m to clean the cache.\n\n  Without \u{1b}[32m--force\u{1b}[39m, it only prints what it would remove. Use \u{1b}[32m--dry-run\u{1b}[39m for\n  the same preview, or \u{1b}[32m--force\u{1b}[39m to actually remove rig.";
 const ABOUT_SELF_UPDATE: &str = "Update rig to the latest release";
diff --git a/src/help/cache-clean.md b/src/help/cache-clean.md
index 631137dc5..29aeda7e2 100644
--- a/src/help/cache-clean.md
+++ b/src/help/cache-clean.md
@@ -4,6 +4,7 @@ Delete cached files
 
 Deletes files from rig's cache directory. With no options, deletes the
 whole cache. Use `--category` to delete only one category of cached files
-(`built`, `packages`, `metadata`, `p3m`, `git-mirrors` or `url-pkgs`),
+(`built`, `packages`, `metadata`, `p3m`, `git-mirrors`, `url-pkgs` or
+`scripts`),
 leaving the rest in place. See [`rig cache info`](cache.qmd#rig-cache-info)
 for what each category contains.
diff --git a/src/help/cache-info.md b/src/help/cache-info.md
index 4e79e5324..d2226015a 100644
--- a/src/help/cache-info.md
+++ b/src/help/cache-info.md
@@ -7,7 +7,8 @@ categories: packages rig built from source, downloaded package files,
 package metadata (binary package indexes, CRAN-like package databases,
 package manifests, and repository data), the cached PPM status document,
 the persistent git mirrors kept for git/GitHub dependency resolution
-(`rig proj lock`), and the downloaded archives kept for `url` dependency
-resolution.
+(`rig proj lock`), the downloaded archives kept for `url` dependency
+resolution, and the environments of scripts with inline dependencies
+(`rig run script.R`).
 
 Use `--json` for machine-readable output.
diff --git a/src/help/run.md b/src/help/run.md
index b71628d29..72f26c537 100644
--- a/src/help/run.md
+++ b/src/help/run.md
@@ -9,6 +9,7 @@ version.
 
 ```sh
 rig run                    # start R
+rig run <script.R>         # run an R script
 rig run -f <script-file>   # run an R script
 rig run -e <expression>    # evaluate an R expression
 rig run <pkg>::<script>    # run a script from a package's exec directory
@@ -52,6 +53,42 @@ the project's own environment instead of the default R version: it runs
 Use `--no-project` to ignore a project, or `--r-version` to select an R
 version directly.
 
+## Scripts with inline dependencies
+
+`rig run -f script.R` runs an R script (the `-f` can be omitted). A
+script can declare the packages and the R version it needs in a comment
+block at its top, so it runs anywhere without a project:
+
+```r
+# /// script
+# [dependencies]
+# R = ">= 4.4"
+# cli = "*"
+# dplyr = ">= 1.1"
+#
+# [tool.rig]
+# exclude-newer = "2026-06-01"
+# ///
+library(dplyr)
+```
+
+The block starts with a `# /// script` line and ends with a `# ///` line.
+In between, every line is a comment, and without the leading `#` they form
+a TOML document. The block takes the `[dependencies]`, `[[repository]]` and
+`[tool.rig]` tables of `rproj.toml`, with the same meaning.
+
+rig creates an environment for the script in its cache directory, and runs
+the script there, isolated from your own package library. It picks an
+installed R version that fits the `R` requirement, or installs one, then
+locks and installs the packages, the same way `rig proj sync` does for a
+project. Later runs reuse the environment. Scripts with the same block
+share one environment, and changing the block creates a new one. A script
+with a block always uses its own environment, even inside a project.
+`--r-version` selects the R version, which must fit the `R` requirement.
+
+`rig cache clean --category scripts` deletes all script environments. A
+script can start with `#!/usr/bin/env -S rig run`, to run it directly.
+
 ## Project scripts
 
 A project can give its own scripts a name, in the `[[bin]]` tables of its
@@ -93,6 +130,6 @@ library and repositories too, not just its version.
 Unlike `R -e`/`R -f`, `Rscript` never echoes back the code it runs, which
 fits scripts and pipelines better than `R`'s interactive-style echo.
 
-`--rscript` works with `-e`/`-f`, project scripts, apps and `--activate`,
+`--rscript` works with `-e`/`-f`, scripts, project scripts, apps and `--activate`,
 but not with `--cmd` (`R CMD` only exists as part of the `R` front-end) or
 `--shell` (which never runs the R binary at all).
diff --git a/src/main.rs b/src/main.rs
index 77b6173f5..564d06bf2 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -12,7 +12,9 @@ use tabular::*;
 mod args;
 use args::*;
 
+mod script_meta;
 mod scrun;
+mod stdout_redirect;
 use scrun::*;
 
 #[cfg(target_os = "macos")]
diff --git a/src/proj.rs b/src/proj.rs
index 372aeb48c..ab566e52d 100644
--- a/src/proj.rs
+++ b/src/proj.rs
@@ -2569,6 +2569,10 @@ struct ProjLockOptions {
     /// dependencies instead of keeping a pin that already satisfies
     /// `rproj.toml` (see [`existing_lock_satisfies`]).
     upgrade: bool,
+    /// Solve for this machine only, instead of the default platform set.
+    /// Used for the environments of scripts with inline metadata, which only
+    /// ever run where they are created.
+    host_only: bool,
 }
 
 fn sc_proj_lock(
@@ -2592,10 +2596,38 @@ fn sc_proj_lock(
         prefer_binary: args.get_one::<usize>("prefer-binary").copied(),
         exclude_newer: exclude_newer_arg(args)?,
         upgrade: args.get_flag("upgrade"),
+        host_only: false,
     };
     proj_lock(&proj_lock_root()?, &opts, args)
 }
 
+/// Lock the project in `root` for this machine only, for `r_version` if
+/// given, else for the R version `proj_lock_r_version` picks. This is what
+/// the environment of a script with inline metadata needs: it is created
+/// and used on the same machine, so the other platforms would only make the
+/// first run slower.
+///
+/// `arch` is the architecture of the R to lock for, if it is not the
+/// machine's own. Only macOS has R builds for more than one architecture.
+pub(crate) fn proj_lock_host(
+    root: &Path,
+    r_version: Option<String>,
+    arch: Option<&str>,
+    args: &ArgMatches,
+) -> Result<(), Box<dyn Error>> {
+    let platforms = match arch {
+        Some(arch) if is_foreign_arch(arch) => vec![macos_platform_for_arch(arch)],
+        _ => vec![],
+    };
+    let opts = ProjLockOptions {
+        r_versions: r_version.into_iter().collect(),
+        host_only: platforms.is_empty(),
+        platforms,
+        ..Default::default()
+    };
+    proj_lock(root, &opts, args)
+}
+
 /// The directory `rig proj lock` and `rig proj sync` work on: the workspace a
 /// project belongs to, else the project itself, else the current directory --
 /// which is where `proj_read_solve_roots` reports the missing manifest.
@@ -2987,6 +3019,9 @@ fn r_requirement(req: Option<&DepVersionSpec>) -> String {
 /// solving, by the resolved-target dedup in `proj_lock`, so a redundant
 /// solve is never dispatched in the first place.
 fn lock_platform_specs(opts: &ProjLockOptions) -> Vec<Option<String>> {
+    if opts.host_only {
+        return vec![None];
+    }
     let mut specs: Vec<Option<String>> = if !opts.platforms.is_empty() {
         opts.platforms.iter().cloned().map(Some).collect()
     } else {
@@ -3783,6 +3818,39 @@ fn rvenv_r_installation(
         bail!("{}", msg);
     }
 
+    install_r_with_rig_add(r_version, arch)?;
+
+    match find_r_installation(r_version, arch)? {
+        Some(name) => {
+            let binary = get_r_binary(&name)?;
+            Ok((name, binary))
+        }
+        None => {
+            let msg = format!(
+                "Installed R {} ({}), but cannot find it now",
+                r_version, arch
+            );
+            OUTPUT.error(&msg);
+            error!("{}", msg);
+            bail!("{}", msg)
+        }
+    }
+}
+
+/// Whether `arch` (as rig names it, see [`native_arch_name`]) is not this
+/// machine's own architecture.
+pub(crate) fn is_foreign_arch(arch: &str) -> bool {
+    native_arch_name(arch) != native_arch_name(std::env::consts::ARCH)
+}
+
+/// The platform string of macOS on `arch`, in the form `proj_lock` takes.
+fn macos_platform_for_arch(arch: &str) -> String {
+    let arch = if arch == "arm64" { "aarch64" } else { arch };
+    format!("{}-apple-darwin", arch)
+}
+
+/// Install `r_version` for `arch` with `rig add`.
+fn install_r_with_rig_add(r_version: &str, arch: &str) -> Result<(), Box<dyn Error>> {
     OUTPUT.status(&format!(
         "R {} ({}) is not installed, installing it now",
         r_version, arch
@@ -3793,28 +3861,61 @@ fn rvenv_r_installation(
     );
     // `rig add` is a subcommand, not a function that takes a version, so go
     // through clap. It escalates on its own in admin mode.
-    let matches = rig_app().try_get_matches_from(add_args)?;
+    let matches = rig_app().try_get_matches_from(r_add_args(r_version, arch))?;
     let (_name, addargs) = match matches.subcommand() {
         Some(x) => x,
         None => bail!("Internal error: `rig add` did not parse"),
     };
     sc_add(addargs)?;
+    Ok(())
+}
 
-    match find_r_installation(r_version, arch)? {
-        Some(name) => {
-            let binary = get_r_binary(&name)?;
-            Ok((name, binary))
+/// The installed R that `r_version` (an `--r-version` argument) selects: an
+/// installation of that name or alias (`4.6.1`, `release`), else the newest
+/// installation of that version on this machine's architecture (`4.5` for
+/// `4.5.3`). Installs it with `rig add` if there is none, or, with `dry_run`,
+/// only says so and returns `None`.
+///
+/// Returns the installation's R version and architecture, e.g. `("4.6.1",
+/// "arm64")`. These identify the R build the way an alias or a short version
+/// cannot: `release` and `4.6` mean different builds over time.
+pub(crate) fn requested_r_installation(
+    r_version: &str,
+    dry_run: bool,
+) -> Result<Option<(String, String)>, Box<dyn Error>> {
+    let arch = native_arch_name(std::env::consts::ARCH);
+    let find = || -> Result<Option<String>, Box<dyn Error>> {
+        if let Some(name) = find_installed(r_version)? {
+            return Ok(Some(name));
         }
-        None => {
+        find_r_installation(r_version, &arch)
+    };
+
+    let name = match find()? {
+        Some(name) => name,
+        None if dry_run => {
             let msg = format!(
-                "Installed R {} ({}), but cannot find it now",
-                r_version, arch
+                "R {} is not installed, would install it with `rig {}`",
+                r_version,
+                r_add_args(r_version, &arch)[1..].join(" ")
             );
-            OUTPUT.error(&msg);
-            error!("{}", msg);
-            bail!("{}", msg)
+            OUTPUT.info(&msg);
+            info!("{}", msg);
+            return Ok(None);
         }
-    }
+        None => {
+            install_r_with_rig_add(r_version, &arch)?;
+            match find()? {
+                Some(name) => name,
+                None => bail!("Installed R {}, but cannot find it now", r_version),
+            }
+        }
+    };
+
+    Ok(Some((
+        get_r_version_data_version(&name)?,
+        rvenv_r_arch(&name),
+    )))
 }
 
 /// The `rig add` command line that installs `r_version` for `arch`. Only
@@ -3863,11 +3964,17 @@ fn find_r_installation(r_version: &str, arch: &str) -> Result<Option<String>, Bo
             }
         })
         .collect();
+    // For the same version, prefer an installation named after its version
+    // (`4.6.1-x86_64`) over a symbolic one (`next-x86_64`), which can point
+    // at another version later.
     matching.sort_by_key(|c| {
-        c.version
-            .as_deref()
-            .and_then(r_components)
-            .unwrap_or_default()
+        (
+            c.version
+                .as_deref()
+                .and_then(r_components)
+                .unwrap_or_default(),
+            c.name.starts_with(|ch: char| ch.is_ascii_digit()),
+        )
     });
     Ok(matching.pop().map(|v| v.name.clone()))
 }
@@ -3928,13 +4035,25 @@ fn this_os_family() -> &'static str {
 /// just works without extra flags; only zero matches is a hard error. For the
 /// same R version a target for this OS wins over a source-only one, which
 /// matches every machine.
+#[cfg(test)]
 fn select_sync_target<'a>(
     targets: &'a [RprojLockTarget],
     r_version: Option<&str>,
     platform: Option<&str>,
+) -> Result<&'a RprojLockTarget, Box<dyn Error>> {
+    select_sync_target_for_arch(targets, r_version, platform, None)
+}
+
+/// [`select_sync_target`], for an R of architecture `arch` instead of the
+/// machine's own, if `arch` is given, see [`ProjSyncOptions::arch`].
+fn select_sync_target_for_arch<'a>(
+    targets: &'a [RprojLockTarget],
+    r_version: Option<&str>,
+    platform: Option<&str>,
+    arch: Option<&str>,
 ) -> Result<&'a RprojLockTarget, Box<dyn Error>> {
     let this_os = this_os_family();
-    let this_arch = native_arch_name(std::env::consts::ARCH);
+    let this_arch = native_arch_name(arch.unwrap_or(std::env::consts::ARCH));
     let mut candidates: Vec<&RprojLockTarget> = targets
         .iter()
         .filter(|t| match target_os_family(&t.platform) {
@@ -4085,6 +4204,12 @@ pub(crate) struct ProjSyncOptions {
     /// `--exclude-newer`: (re)lock with this cutoff before syncing, see
     /// `ProjLockOptions::exclude_newer`.
     pub exclude_newer: Option<ExcludeNewerSpec>,
+    /// Sync for an R of this architecture (`arm64`, `x86_64`), instead of the
+    /// machine's own: pick a lock target for it, and run an R build for it.
+    /// Not a `rig proj sync` option, the environments of scripts with inline
+    /// metadata use it, for an `--r-version` like `4.6.1-x86_64` on an arm64
+    /// Mac.
+    pub arch: Option<String>,
 }
 
 impl Default for ProjSyncOptions {
@@ -4104,6 +4229,7 @@ impl Default for ProjSyncOptions {
             frozen: false,
             dry_run: false,
             exclude_newer: None,
+            arch: None,
         }
     }
 }
@@ -4140,6 +4266,7 @@ fn sc_proj_sync(
         frozen: args.get_flag("frozen"),
         dry_run: args.get_flag("dry-run"),
         exclude_newer: exclude_newer_arg(args)?,
+        arch: None,
     };
 
     proj_sync(&root, &opts, args)
@@ -4261,10 +4388,11 @@ pub(crate) fn proj_sync(
     let lock_content = fs::read_to_string(&lock_path)?;
     RprojLock::check_version(&lock_content)?;
     let lock: RprojLock = toml::from_str(&lock_content)?;
-    let target = select_sync_target(
+    let target = select_sync_target_for_arch(
         &lock.targets,
         opts.r_version.as_deref(),
         opts.platform.as_deref(),
+        opts.arch.as_deref(),
     )?;
 
     let wanted: Vec<RprojLockPackage> = sync_wanted_packages(&target.packages, opts);
@@ -4318,7 +4446,11 @@ pub(crate) fn proj_sync(
     // The architecture comes from the lock file's platform, not from the
     // machine: a lock file solved for macos-x86_64 needs an x86_64 R even on
     // an arm64 Mac.
-    let r_arch = target_r_arch(&target.platform);
+    // A source-only target names no arch, then `opts.arch` decides, if given.
+    let r_arch = match (platform_arch(&target.platform), &opts.arch) {
+        (None, Some(arch)) => native_arch_name(arch),
+        _ => target_r_arch(&target.platform),
+    };
     let (r_name, r_binary) = rvenv_r_installation(
         &target.r_version,
         &r_arch,
@@ -5418,6 +5550,16 @@ mod tests {
         );
     }
 
+    #[test]
+    fn host_only_locks_for_this_machine_only() {
+        let opts = ProjLockOptions {
+            host_only: true,
+            add_platforms: vec!["windows".to_string()],
+            ..Default::default()
+        };
+        assert_eq!(lock_platform_specs(&opts), vec![None]);
+    }
+
     #[test]
     fn add_platform_extends_an_explicit_platform_list() {
         let opts = ProjLockOptions {
@@ -5670,6 +5812,41 @@ mod tests {
         assert_eq!(picked.r_version, "4.6.1");
     }
 
+    #[test]
+    fn select_sync_target_for_arch_picks_the_requested_arch() {
+        let this_os = this_os_family();
+        let native = native_arch_name(std::env::consts::ARCH);
+        let other = if native == "x86_64" {
+            "arm64"
+        } else {
+            "x86_64"
+        };
+        let targets = vec![
+            target("4.6.1", &format!("{}-{}", this_os, native)),
+            target("4.6.1", &format!("{}-{}", this_os, other)),
+        ];
+        let picked = select_sync_target_for_arch(&targets, None, None, Some(other)).unwrap();
+        assert_eq!(
+            platform_arch(&picked.platform)
+                .map(native_arch_name)
+                .as_deref(),
+            Some(other)
+        );
+        let picked = select_sync_target(&targets, None, None).unwrap();
+        assert_eq!(
+            platform_arch(&picked.platform)
+                .map(native_arch_name)
+                .as_deref(),
+            Some(native.as_str())
+        );
+    }
+
+    #[test]
+    fn macos_platform_for_arch_uses_lock_platform_names() {
+        assert_eq!(macos_platform_for_arch("x86_64"), "x86_64-apple-darwin");
+        assert_eq!(macos_platform_for_arch("arm64"), "aarch64-apple-darwin");
+    }
+
     #[test]
     fn select_sync_target_ignores_foreign_os_targets() {
         let this_os = this_os_family();
diff --git a/src/rvenv.rs b/src/rvenv.rs
index c1376bdea..828dec4cf 100644
--- a/src/rvenv.rs
+++ b/src/rvenv.rs
@@ -355,6 +355,45 @@ pub fn project_r_wrapper(root: &Path) -> PathBuf {
     project_bin(root).join(if cfg!(windows) { "R.exe" } else { "R" })
 }
 
+/// What the `.rvenv/bin/R` or `.rvenv/bin/Rscript` wrapper at `wrapper` would
+/// run: the real R binary it forwards to, and the environment variables it
+/// sets (see [`rvenv_env_vars`]). `None` if `wrapper` is not such a wrapper,
+/// or if its environment has no usable `rvenv.cfg`.
+///
+/// `rig run` uses this to start the real R directly, which saves a shell
+/// start (Unix) or a shim start (Windows) on every run. The result is the
+/// same as running the wrapper, both come from the same `rvenv.cfg`.
+pub fn rvenv_wrapper_target(
+    wrapper: &Path,
+) -> Result<Option<(PathBuf, Vec<(String, String)>)>, Box<dyn Error>> {
+    let Some(bin) = wrapper.parent() else {
+        return Ok(None);
+    };
+    let Some(venv) = bin.parent() else {
+        return Ok(None);
+    };
+    if bin.file_name() != Some(RVENV_BIN_SUBDIR.as_ref())
+        || venv.file_name() != Some(RVENV_DIR.as_ref())
+    {
+        return Ok(None);
+    }
+    let Some(root) = venv.parent() else {
+        return Ok(None);
+    };
+    let Some(cfg) = read_rvenv_cfg(root)? else {
+        return Ok(None);
+    };
+    let target = match wrapper.file_stem().and_then(|s| s.to_str()) {
+        Some("R") => cfg.r_binary,
+        Some("Rscript") => rscript_of(&cfg.r_binary),
+        _ => return Ok(None),
+    };
+    if !target.exists() {
+        return Ok(None);
+    }
+    Ok(Some((target, rvenv_env_vars(venv))))
+}
+
 /// Why the project environment in `root` is not usable as it is, or `None` if
 /// it is up to date. Callers use this both to decide whether to run
 /// `rig proj sync` and to tell the user why they are waiting for one.
@@ -1760,7 +1799,7 @@ mod tests {
             );
             // The environment comes from `rvenv_env_vars`, relative to
             // $RVENV, which the wrapper works out from its own location.
-            assert!(body.contains("RVENV=$(cd \"$(dirname \"$0\")/..\" && pwd)"));
+            assert!(body.contains("RVENV=$(cd \"$RVENV/..\" && pwd)"));
             for (name, value) in rvenv_env_vars(Path::new("$RVENV")) {
                 if name == "RVENV" {
                     continue;
diff --git a/src/script_meta.rs b/src/script_meta.rs
new file mode 100644
index 000000000..a4a577fcb
--- /dev/null
+++ b/src/script_meta.rs
@@ -0,0 +1,561 @@
+//! Inline metadata of self-contained R scripts, for `rig run script.R`.
+//!
+//! A script can declare its own dependencies in a comment block, in the
+//! format of Python's PEP 723 (`uv run` uses the same one):
+//!
+//! ```r
+//! # /// script
+//! # [dependencies]
+//! # R = ">= 4.4"
+//! # dplyr = ">= 1.1"
+//! #
+//! # [tool.rig]
+//! # exclude-newer = "2026-06-01"
+//! # ///
+//! ```
+//!
+//! The body is a subset of `rproj.toml`. `rig run` turns it into a small
+//! generated project in the rig cache, one per distinct header, and locks and
+//! syncs that with the usual `rig proj` machinery. Scripts with the same
+//! header share one environment.
+
+use std::collections::BTreeMap;
+use std::error::Error;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use clap::ArgMatches;
+use log::{info, trace};
+use serde::{Deserialize, Serialize};
+use simple_error::bail;
+
+use crate::cache::get_cache_dir;
+use crate::common::get_r_version_data_version;
+use crate::output::OUTPUT;
+use crate::proj::{
+    is_foreign_arch, proj_lock_host, proj_sync, requested_r_installation, ProjSyncOptions,
+};
+use crate::rproj::{Dependency, Repository, Rproj, RPROJ_MANIFEST_FILE};
+use crate::rvenv::{
+    ensure_rvenv_files, project_r_wrapper, read_rvenv_cfg, rvenv_sync_needed, RPROJ_LOCK_FILE,
+};
+use crate::stdout_redirect::StdoutToStderr;
+use crate::utils::{calculate_hash, write_atomically};
+
+/// The cache subdirectory that holds the script environments.
+pub const SCRIPTS_CACHE_SUBDIR: &str = "scripts";
+
+const BLOCK_START: &str = "# /// script";
+
+/// The comment markers a block can use. The opening line decides which one,
+/// and every other line of the block must use the same one. `##` is common
+/// in R code, e.g. for comments that RStudio does not re-indent.
+const BLOCK_MARKERS: [&str; 2] = ["##", "#"];
+
+/// The parsed body of a `# /// script` block.
+#[derive(Serialize, Deserialize, Debug, Default, PartialEq)]
+#[serde(deny_unknown_fields)]
+pub struct ScriptMeta {
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub dependencies: BTreeMap<String, Dependency>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub repository: Vec<Repository>,
+    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
+    pub tool: BTreeMap<String, toml::Table>,
+}
+
+/// The TOML body of the `# /// script` block in `text`, with the comment
+/// prefixes removed, or `None` if there is no such block.
+///
+/// The block can also use `##` instead of `#`, i.e. start with `## ///
+/// script`, see [`BLOCK_MARKERS`]. Every line between the opening and the
+/// closing line must be a comment with the same marker: either the marker
+/// alone, or the marker followed by the content, usually after one space,
+/// which is removed. A file can have at most one `script` block, and the
+/// block must be closed.
+fn extract_script_block(text: &str) -> Result<Option<String>, Box<dyn Error>> {
+    let mut body: Option<String> = None;
+    let mut lines = text.lines().enumerate();
+    while let Some((_, line)) = lines.next() {
+        let line = line.trim_end();
+        let Some(marker) = BLOCK_MARKERS
+            .iter()
+            .find(|m| line == format!("{} /// script", m))
+        else {
+            continue;
+        };
+        if body.is_some() {
+            bail!("more than one `{}` block", BLOCK_START);
+        }
+        let start = format!("{} /// script", marker);
+        let end = format!("{} ///", marker);
+        let mut content = String::new();
+        let mut closed = false;
+        for (lineno, line) in lines.by_ref() {
+            let line = line.trim_end_matches('\r');
+            if line.trim_end() == end {
+                closed = true;
+                break;
+            }
+            let Some(rest) = line.strip_prefix(marker) else {
+                bail!(
+                    "line {} is inside the `{}` block, but it does not start \
+                     with `{}` (is the closing `{}` line missing?)",
+                    lineno + 1,
+                    start,
+                    marker,
+                    end
+                );
+            };
+            content.push_str(rest.strip_prefix(' ').unwrap_or(rest));
+            content.push('\n');
+        }
+        if !closed {
+            bail!("the `{}` block has no closing `{}` line", start, end);
+        }
+        body = Some(content);
+    }
+    Ok(body)
+}
+
+/// The inline metadata of a script, or `None` if it has none.
+pub fn parse_script_metadata(text: &str) -> Result<Option<ScriptMeta>, Box<dyn Error>> {
+    let body = match extract_script_block(text)? {
+        None => return Ok(None),
+        Some(body) => body,
+    };
+    let meta: ScriptMeta = toml::from_str(&body)
+        .map_err(|e| format!("invalid TOML in the `{}` block: {}", BLOCK_START, e))?;
+    Ok(Some(meta))
+}
+
+impl ScriptMeta {
+    /// Make `path = "..."` dependencies absolute, relative to `script_dir`.
+    /// The environment lives in the cache, so a relative path would point
+    /// somewhere else there. It also makes two scripts in different
+    /// directories with the same relative path get different environments.
+    pub fn absolutize_paths(&mut self, script_dir: &Path) {
+        for dep in self.dependencies.values_mut() {
+            if let Dependency::Detailed(table) = dep {
+                if let Some(path) = &table.path {
+                    if Path::new(path).is_relative() {
+                        table.path = Some(script_dir.join(path).display().to_string());
+                    }
+                }
+            }
+        }
+    }
+
+    /// The `rproj.toml` of the generated project for this script.
+    fn to_manifest(&self) -> Rproj {
+        let mut manifest = Rproj::minimal("script");
+        manifest.dependencies = self.dependencies.clone();
+        // R has to be part of the solution, the lock file records the R
+        // version from it. Without an `R` entry, it only is if some package
+        // depends on R, so add one that allows any R.
+        manifest
+            .dependencies
+            .entry("R".to_string())
+            .or_insert_with(|| Dependency::Version("*".to_string()));
+        manifest.repository = self
+            .repository
+            .iter()
+            .map(|r| Repository {
+                name: r.name.clone(),
+                url: r.url.clone(),
+            })
+            .collect();
+        manifest.tool = self.tool.clone();
+        manifest
+    }
+
+    /// The key of the environment of this metadata: the first 16 hex digits
+    /// of the hash of its canonical TOML form, plus the R build selected by
+    /// `--r-version`, if any, because that changes what gets locked. That is
+    /// the R version and architecture of the installation (see
+    /// [`requested_r_installation`]), not the argument as given, so `4.6`,
+    /// `4.6.1` and `release` share an environment if they select the same R.
+    fn env_key(&self, r_version: Option<&str>) -> Result<String, Box<dyn Error>> {
+        let mut canonical = toml::to_string(self)?;
+        if let Some(rver) = r_version {
+            canonical.push_str(&format!("\n# r-version = {}\n", rver));
+        }
+        Ok(calculate_hash(&canonical)[..16].to_string())
+    }
+}
+
+/// The cache directory of the environment of `meta`.
+fn script_env_dir(meta: &ScriptMeta, r_version: Option<&str>) -> Result<PathBuf, Box<dyn Error>> {
+    Ok(get_cache_dir()?
+        .join(SCRIPTS_CACHE_SUBDIR)
+        .join(meta.env_key(r_version)?))
+}
+
+/// Why the synced environment in `envdir` does not use R `version` on
+/// `arch`, or `None` if it does, or if it was never synced.
+fn env_r_mismatch(
+    envdir: &Path,
+    version: &str,
+    arch: &str,
+) -> Result<Option<String>, Box<dyn Error>> {
+    let cfg = match read_rvenv_cfg(envdir)? {
+        None => return Ok(None),
+        Some(cfg) => cfg,
+    };
+    if cfg.r_arch != arch {
+        return Ok(Some(format!(
+            "it uses an {} R instead of {}",
+            cfg.r_arch, arch
+        )));
+    }
+    // An R that is gone is not a mismatch here, the sync reinstalls it.
+    if let Ok(have) = get_r_version_data_version(&cfg.r_version) {
+        if have != version {
+            return Ok(Some(format!("it uses R {} instead of {}", have, version)));
+        }
+    }
+    Ok(None)
+}
+
+/// The R wrapper to run `script` with, if it has inline metadata: the one in
+/// the script's own environment, created or synced first if needed. `None` if
+/// the script has no metadata block, or cannot be read, in which case it runs
+/// the usual way.
+pub fn script_r_binary(
+    script: &Path,
+    args: &ArgMatches,
+    dry_run: bool,
+) -> Result<Option<String>, Box<dyn Error>> {
+    // An unreadable file is not our business here, R reports it the usual
+    // way when it tries to run it.
+    let text = match fs::read_to_string(script) {
+        Ok(text) => text,
+        Err(e) => {
+            trace!("Could not read {}: {}", script.display(), e);
+            return Ok(None);
+        }
+    };
+    let mut meta = match parse_script_metadata(&text) {
+        Ok(None) => return Ok(None),
+        Ok(Some(meta)) => meta,
+        Err(e) => {
+            let msg = format!("{}: {}", script.display(), e);
+            bail!("{}", msg);
+        }
+    };
+
+    // Installing R or packages must not write to stdout, which belongs to
+    // the script, e.g. `rig run script.R > out.csv`.
+    let _stdout_guard = StdoutToStderr::new();
+
+    let script_dir = script
+        .canonicalize()?
+        .parent()
+        .map(|p| p.to_path_buf())
+        .unwrap_or_default();
+    meta.absolutize_paths(&script_dir);
+
+    // Resolve `--r-version` to an installation first, installing it if
+    // needed, so the environment is keyed on the R it actually uses.
+    let (rver, r_arch) = match args.get_one::<String>("r-version") {
+        None => (None, None),
+        Some(requested) => match requested_r_installation(requested, dry_run)? {
+            Some((version, arch)) => (Some(version), Some(arch)),
+            None => {
+                let msg = format!("Would create an environment for {}", script.display());
+                OUTPUT.info(&msg);
+                info!("{}", msg);
+                return Ok(Some(format!("<R {} environment>", requested)));
+            }
+        },
+    };
+    let r_id = rver
+        .as_ref()
+        .zip(r_arch.as_ref())
+        .map(|(version, arch)| format!("{} {}", version, arch));
+    let envdir = script_env_dir(&meta, r_id.as_deref())?;
+    let wrapper = project_r_wrapper(&envdir);
+    trace!(
+        "Environment of {} is at {}",
+        script.display(),
+        envdir.display()
+    );
+
+    // The key says which R the environment is for, but check that it really
+    // uses that R, and start over if not: an environment that runs another
+    // R build is broken, not merely stale.
+    if let (Some(version), Some(arch)) = (&rver, &r_arch) {
+        if let Some(why) = env_r_mismatch(&envdir, version, arch)? {
+            if dry_run {
+                let msg = format!(
+                    "Would re-create the environment of {}, because {}",
+                    script.display(),
+                    why
+                );
+                OUTPUT.info(&msg);
+                info!("{}", msg);
+            } else {
+                let msg = format!(
+                    "Re-creating the environment of {}, because {}",
+                    script.display(),
+                    why
+                );
+                OUTPUT.info(&msg);
+                info!("{}", msg);
+                fs::remove_dir_all(&envdir)?;
+            }
+        }
+    }
+
+    let manifest_path = envdir.join(RPROJ_MANIFEST_FILE);
+    if !manifest_path.exists() {
+        if dry_run {
+            let msg = format!(
+                "Would create an environment for {} in {}",
+                script.display(),
+                envdir.display()
+            );
+            OUTPUT.info(&msg);
+            info!("{}", msg);
+            return Ok(Some(wrapper.display().to_string()));
+        }
+        fs::create_dir_all(&envdir)?;
+        let manifest = toml::to_string(&meta.to_manifest())?;
+        write_atomically(&manifest_path, manifest.as_bytes())?;
+    }
+    ensure_rvenv_files(&envdir)?;
+
+    match rvenv_sync_needed(&envdir)? {
+        None => {}
+        Some(why) if dry_run => {
+            let msg = format!(
+                "Would sync the environment of {} first, because {}",
+                script.display(),
+                why
+            );
+            OUTPUT.info(&msg);
+            info!("{}", msg);
+        }
+        Some(why) => {
+            let msg = format!(
+                "Setting up the environment of {}, because {}",
+                script.display(),
+                why
+            );
+            OUTPUT.info(&msg);
+            info!("{}", msg);
+            if !envdir.join(RPROJ_LOCK_FILE).exists() {
+                proj_lock_host(&envdir, rver, r_arch.as_deref(), args)?;
+            }
+            // An R of another architecture than the machine's, e.g.
+            // `4.6.1-x86_64` on an arm64 Mac, needs that arch's lock target
+            // and R build, not the machine's.
+            let sync_opts = ProjSyncOptions {
+                arch: r_arch.filter(|arch| is_foreign_arch(arch)),
+                ..Default::default()
+            };
+            proj_sync(&envdir, &sync_opts, args)?;
+        }
+    }
+
+    if !wrapper.exists() && !dry_run {
+        let msg = format!(
+            "No R wrapper at {} after syncing the environment of {}",
+            wrapper.display(),
+            script.display()
+        );
+        bail!("{}", msg);
+    }
+
+    Ok(Some(
+        wrapper
+            .to_str()
+            .ok_or("The cache path is not valid Unicode")?
+            .to_string(),
+    ))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn no_block_means_no_metadata() {
+        let text = "library(cli)\n# a comment\ncli::cli_text('hi')\n";
+        assert_eq!(parse_script_metadata(text).unwrap(), None);
+    }
+
+    #[test]
+    fn a_valid_block_is_parsed() {
+        let text = "\
+# /// script
+# [dependencies]
+# R = \">= 4.4\"
+# cli = \"*\"
+# glue = { git = \"https://github.com/tidyverse/glue\" }
+#
+# [tool.rig]
+# exclude-newer = \"2026-06-01\"
+# ///
+library(cli)
+";
+        let meta = parse_script_metadata(text).unwrap().unwrap();
+        assert_eq!(meta.dependencies.len(), 3);
+        assert_eq!(
+            meta.dependencies.get("R"),
+            Some(&Dependency::Version(">= 4.4".to_string()))
+        );
+        assert!(matches!(
+            meta.dependencies.get("glue"),
+            Some(Dependency::Detailed(_))
+        ));
+        assert_eq!(
+            meta.tool["rig"]["exclude-newer"].as_str(),
+            Some("2026-06-01")
+        );
+    }
+
+    #[test]
+    fn a_shebang_can_come_first() {
+        let text =
+            "#!/usr/bin/env -S rig run\n# /// script\n# [dependencies]\n# cli = \"*\"\n# ///\n";
+        let meta = parse_script_metadata(text).unwrap().unwrap();
+        assert!(meta.dependencies.contains_key("cli"));
+    }
+
+    #[test]
+    fn the_space_after_the_hash_is_optional() {
+        let text = "# /// script\n#[dependencies]\n#cli = \"*\"\n# ///\n";
+        let meta = parse_script_metadata(text).unwrap().unwrap();
+        assert!(meta.dependencies.contains_key("cli"));
+    }
+
+    #[test]
+    fn crlf_line_endings_work() {
+        let text = "# /// script\r\n# [dependencies]\r\n# cli = \"*\"\r\n# ///\r\n";
+        let meta = parse_script_metadata(text).unwrap().unwrap();
+        assert!(meta.dependencies.contains_key("cli"));
+    }
+
+    #[test]
+    fn an_empty_block_is_valid() {
+        let text = "# /// script\n# ///\n";
+        assert_eq!(
+            parse_script_metadata(text).unwrap(),
+            Some(ScriptMeta::default())
+        );
+    }
+
+    #[test]
+    fn an_unclosed_block_is_an_error() {
+        let text = "# /// script\n# [dependencies]\n# cli = \"*\"\n";
+        let err = parse_script_metadata(text).unwrap_err().to_string();
+        assert!(err.contains("no closing"), "{}", err);
+    }
+
+    #[test]
+    fn a_code_line_inside_the_block_is_an_error() {
+        let text = "# /// script\n# [dependencies]\nlibrary(cli)\n# ///\n";
+        let err = parse_script_metadata(text).unwrap_err().to_string();
+        assert!(err.contains("line 3"), "{}", err);
+    }
+
+    #[test]
+    fn a_double_hash_block_is_parsed() {
+        let text =
+            "## /// script\n## [dependencies]\n##sessioninfo = \"*\"\n##\n## ///\nR.home()\n";
+        let meta = parse_script_metadata(text).unwrap().unwrap();
+        assert!(meta.dependencies.contains_key("sessioninfo"));
+    }
+
+    #[test]
+    fn a_double_hash_block_needs_double_hash_lines() {
+        let text = "## /// script\n# [dependencies]\n## ///\n";
+        let err = parse_script_metadata(text).unwrap_err().to_string();
+        assert!(err.contains("does not start with `##`"), "{}", err);
+        // and a `#` closing line does not close it
+        let text = "## /// script\n## [dependencies]\n# ///\n";
+        assert!(parse_script_metadata(text).is_err());
+    }
+
+    #[test]
+    fn two_blocks_are_an_error() {
+        let text = "# /// script\n# ///\n# /// script\n# ///\n";
+        let err = parse_script_metadata(text).unwrap_err().to_string();
+        assert!(err.contains("more than one"), "{}", err);
+    }
+
+    #[test]
+    fn an_unknown_key_is_an_error() {
+        let text = "# /// script\n# [dependancies]\n# cli = \"*\"\n# ///\n";
+        let err = parse_script_metadata(text).unwrap_err().to_string();
+        assert!(err.contains("dependancies"), "{}", err);
+    }
+
+    #[test]
+    fn other_block_types_are_ignored() {
+        let text = "# /// other\n# ///\n";
+        assert_eq!(parse_script_metadata(text).unwrap(), None);
+    }
+
+    #[test]
+    fn relative_path_dependencies_are_made_absolute() {
+        let text = "# /// script\n# [dependencies]\n# mypkg = { path = \"pkg\" }\n# ///\n";
+        let mut meta = parse_script_metadata(text).unwrap().unwrap();
+        let dir = std::env::temp_dir();
+        meta.absolutize_paths(&dir);
+        match meta.dependencies.get("mypkg") {
+            Some(Dependency::Detailed(table)) => {
+                assert_eq!(table.path, Some(dir.join("pkg").display().to_string()));
+            }
+            other => panic!("unexpected dependency: {:?}", other),
+        }
+    }
+
+    #[test]
+    fn the_env_key_is_stable_and_depends_on_the_content() {
+        let a = parse_script_metadata(
+            "# /// script\n# [dependencies]\n# cli = \"*\"\n# glue = \"*\"\n# ///\n",
+        )
+        .unwrap()
+        .unwrap();
+        // Same content, different order and formatting.
+        let b = parse_script_metadata(
+            "# /// script\n# [dependencies]\n# glue   = \"*\"\n# cli = \"*\"\n# ///\n",
+        )
+        .unwrap()
+        .unwrap();
+        let c = parse_script_metadata("# /// script\n# [dependencies]\n# cli = \"*\"\n# ///\n")
+            .unwrap()
+            .unwrap();
+        assert_eq!(a.env_key(None).unwrap(), b.env_key(None).unwrap());
+        assert_ne!(a.env_key(None).unwrap(), c.env_key(None).unwrap());
+        assert_ne!(a.env_key(None).unwrap(), a.env_key(Some("4.5")).unwrap());
+        assert_eq!(a.env_key(None).unwrap().len(), 16);
+    }
+
+    #[test]
+    fn the_manifest_has_only_the_scripts_dependencies() {
+        let meta = parse_script_metadata("# /// script\n# [dependencies]\n# cli = \"*\"\n# ///\n")
+            .unwrap()
+            .unwrap();
+        let manifest = meta.to_manifest();
+        assert_eq!(manifest.project.name, "script");
+        assert_eq!(manifest.dependencies.len(), 2);
+        assert!(manifest.dependencies.contains_key("cli"));
+        // no R requirement means any R, but R is always there
+        assert_eq!(
+            manifest.dependencies.get("R"),
+            Some(&Dependency::Version("*".to_string()))
+        );
+
+        let meta =
+            parse_script_metadata("# /// script\n# [dependencies]\n# R = \">= 4.4\"\n# ///\n")
+                .unwrap()
+                .unwrap();
+        assert_eq!(
+            meta.to_manifest().dependencies.get("R"),
+            Some(&Dependency::Version(">= 4.4".to_string()))
+        );
+    }
+}
diff --git a/src/scrun.rs b/src/scrun.rs
index e730920d2..eb565e3e9 100644
--- a/src/scrun.rs
+++ b/src/scrun.rs
@@ -16,7 +16,10 @@ use crate::rproj::Bin;
 use crate::rproj::RPROJ_MANIFEST_FILE;
 use crate::rvenv::{
     ensure_rvenv_files, find_project_root, project_r_wrapper, rscript_of, rvenv_sync_needed,
+    rvenv_wrapper_target,
 };
+use crate::script_meta::script_r_binary;
+use crate::stdout_redirect::StdoutToStderr;
 
 #[cfg(target_os = "macos")]
 use crate::macos::*;
@@ -42,11 +45,44 @@ pub fn sc_run(args: &ArgMatches, _mainargs: &ArgMatches) -> Result<i32, Box<dyn
         return sc_run_list(args);
     }
 
-    let rbin = run_r_binary(args, dry_run)?;
+    let eval = args.get_one::<String>("eval");
+    let script = args.get_one::<String>("script");
+    let shell_or_cmd = args.get_flag("shell") || args.get_flag("cmd");
+
+    // `rig run script.R` is the same as `rig run -f script.R`.
+    let positional_script = !shell_or_cmd
+        && eval.is_none()
+        && script.is_none()
+        && cmdargs.first().is_some_and(|a| is_r_script_file(a));
+
+    // A script with inline metadata runs in its own environment, whether or
+    // not there is a project here.
+    let script_path = if shell_or_cmd || eval.is_some() {
+        None
+    } else if positional_script {
+        Some(cmdargs[0].clone())
+    } else {
+        script.cloned()
+    };
+    let script_rbin = match &script_path {
+        Some(path) => script_r_binary(Path::new(path), args, dry_run)?,
+        None => None,
+    };
+
+    let (rbin, renviron_user) = match script_rbin {
+        Some(rbin) => (rscript_if_asked(args, rbin)?, user_renviron()),
+        None => (run_r_binary(args, dry_run)?, no_project_renviron_user(args)),
+    };
     let path_prepend = activate_path_prepend(args, &rbin);
+    let direct = if dry_run {
+        None
+    } else {
+        rvenv_wrapper_target(Path::new(&rbin))?
+    };
     let env = RunEnv {
         rbin,
-        renviron_user: no_project_renviron_user(args),
+        direct,
+        renviron_user,
         path_prepend,
     };
 
@@ -59,9 +95,6 @@ pub fn sc_run(args: &ArgMatches, _mainargs: &ArgMatches) -> Result<i32, Box<dyn
         return sc_run_cmd(env, cmdargs, dry_run);
     }
 
-    let eval = args.get_one::<String>("eval");
-    let script = args.get_one::<String>("script");
-
     // `Rscript` rejects `-q`/`--slave`: it already behaves as if they were
     // given (and always suppresses startup messages/echo), so passing them
     // is not just redundant, it is a hard error ("cannot open file '-q'").
@@ -83,6 +116,9 @@ pub fn sc_run(args: &ArgMatches, _mainargs: &ArgMatches) -> Result<i32, Box<dyn
         sc_run_eval(env, rargs, eval.to_string(), cmdargs, dry_run)
     } else if let Some(script) = script {
         sc_run_script(env, rargs, script.to_string(), cmdargs, rscript, dry_run)
+    } else if positional_script {
+        let script = cmdargs[0].clone();
+        sc_run_script(env, rargs, script, cmdargs[1..].to_vec(), rscript, dry_run)
     } else if !cmdargs.is_empty() {
         let app_type: Option<&String> = args.get_one("app-type");
         if cmdargs[0].contains("::") {
@@ -150,6 +186,14 @@ fn no_project_renviron_user(args: &ArgMatches) -> Option<PathBuf> {
     if !args.get_flag("no-project") {
         return None;
     }
+    user_renviron()
+}
+
+/// `~/.Renviron`, to use as `R_ENVIRON_USER` instead of a `.Renviron` in the
+/// current directory, which could belong to a project. `None` if
+/// `R_ENVIRON_USER` is already set (never override an explicit choice), or if
+/// the home directory cannot be determined.
+fn user_renviron() -> Option<PathBuf> {
     if std::env::var_os("R_ENVIRON_USER").is_some() {
         return None;
     }
@@ -158,10 +202,15 @@ fn no_project_renviron_user(args: &ArgMatches) -> Option<PathBuf> {
 }
 
 /// The R binary to run and the environment to run it in, bundled together
-/// because every `sc_run_*` execution path needs all three to build its
+/// because every `sc_run_*` execution path needs all of them to build its
 /// `Command`.
 struct RunEnv {
     rbin: String,
+    /// If `rbin` is an environment's `.rvenv/bin` wrapper, the real R binary
+    /// it forwards to and the variables it sets (see
+    /// `rvenv_wrapper_target`). Running these directly skips starting the
+    /// wrapper, `rbin` is still what dry runs and logs show.
+    direct: Option<(PathBuf, Vec<(String, String)>)>,
     /// `R_ENVIRON_USER` override for `--no-project` (see
     /// `no_project_renviron_user`).
     renviron_user: Option<PathBuf>,
@@ -171,13 +220,20 @@ struct RunEnv {
 }
 
 impl RunEnv {
-    /// A `Command` for `rbin`, with `R_ENVIRON_USER` and `PATH` set as
+    /// A `Command` for `rbin` (or its `direct` target), with `R_ENVIRON_USER` and `PATH` set as
     /// configured. The `PATH` change is set on this one `Command` only: it
     /// never touches the parent shell's environment, but it is inherited by
     /// this process and anything it spawns (a nested shell, or R's own
     /// `system("R ...")`).
     fn command(&self) -> Command {
-        let mut cmd = Command::new(&self.rbin);
+        let mut cmd = match &self.direct {
+            Some((target, vars)) => {
+                let mut cmd = Command::new(target);
+                cmd.envs(vars.iter().map(|(k, v)| (k, v)));
+                cmd
+            }
+            None => Command::new(&self.rbin),
+        };
         if let Some(renviron) = &self.renviron_user {
             cmd.env("R_ENVIRON_USER", renviron);
         }
@@ -227,7 +283,11 @@ fn run_r_binary(args: &ArgMatches, dry_run: bool) -> Result<String, Box<dyn Erro
             get_r_binary(&rver)?.to_string_lossy().into_owned()
         }
     };
+    rscript_if_asked(args, rbin)
+}
 
+/// `Rscript` next to `rbin` under `--rscript`, otherwise `rbin` itself.
+fn rscript_if_asked(args: &ArgMatches, rbin: String) -> Result<String, Box<dyn Error>> {
     if args.get_flag("rscript") {
         Ok(rscript_of(Path::new(&rbin))
             .to_str()
@@ -301,6 +361,8 @@ fn project_r_binary(args: &ArgMatches, dry_run: bool) -> Result<Option<String>,
             let msg = format!("Syncing the project in {}, because {}", root.display(), why);
             OUTPUT.info(&msg);
             info!("{}", msg);
+            // stdout belongs to what `rig run` runs, not to the sync.
+            let _stdout_guard = StdoutToStderr::new();
             proj_sync(&root, &ProjSyncOptions::default(), args)?;
         }
     }
@@ -330,6 +392,15 @@ fn project_r_binary(args: &ArgMatches, dry_run: bool) -> Result<Option<String>,
 // anything other than the file `report.R` would be a bad surprise.
 const NOT_BIN_NAME_EXTENSIONS: [&str; 4] = [".R", ".r", ".Rmd", ".qmd"];
 
+/// Whether `arg` is an existing `.R` file, which `rig run <arg>` runs as a
+/// script, same as `rig run -f <arg>`.
+fn is_r_script_file(arg: &str) -> bool {
+    let path = Path::new(arg);
+    path.extension()
+        .is_some_and(|ext| ext.eq_ignore_ascii_case("r"))
+        && path.is_file()
+}
+
 /// Whether `arg` can name a `[[bin]]` in `rproj.toml`. Anything that looks
 /// like a path or like a package script is not a name, so a declared script
 /// can never shadow the `rig run <path-to-app>` and `rig run <pkg>::<script>`
@@ -1168,6 +1239,24 @@ mod tests {
         assert_eq!(got, OsString::from(format!("/opt/R/4.4.1/bin{}", sep)));
     }
 
+    #[test]
+    fn test_is_r_script_file() {
+        let dir = tempfile::tempdir().unwrap();
+        let upper = dir.path().join("a.R");
+        let lower = dir.path().join("b.r");
+        let other = dir.path().join("c.Rmd");
+        for f in [&upper, &lower, &other] {
+            std::fs::write(f, "1\n").unwrap();
+        }
+        assert!(is_r_script_file(upper.to_str().unwrap()));
+        assert!(is_r_script_file(lower.to_str().unwrap()));
+        assert!(!is_r_script_file(other.to_str().unwrap()));
+        assert!(!is_r_script_file(
+            dir.path().join("missing.R").to_str().unwrap()
+        ));
+        assert!(!is_r_script_file(dir.path().to_str().unwrap()));
+    }
+
     #[test]
     fn test_is_bin_name() {
         for name in ["report", "build-site", "check_all", "r2d2"] {
diff --git a/src/stdout_redirect.rs b/src/stdout_redirect.rs
new file mode 100644
index 000000000..672554b17
--- /dev/null
+++ b/src/stdout_redirect.rs
@@ -0,0 +1,109 @@
+//! Send stdout to stderr for a while, at the OS level.
+//!
+//! `rig run` sometimes has to install R or packages before it runs R: for a
+//! script with inline metadata, or a project that needs a sync. Whatever the
+//! user runs owns stdout, e.g. `rig run script.R > out.csv`, so none of that
+//! setup output may go there. Patching every `println!` is not enough:
+//! `R CMD INSTALL`, the R installers and other child processes inherit
+//! rig's stdout too. So [`StdoutToStderr`] points the process's stdout itself
+//! at stderr, until it is dropped.
+
+use std::io::Write;
+
+/// While this is alive, everything written to stdout, by rig or by child
+/// processes started meanwhile, goes to stderr instead. Dropping it restores
+/// the original stdout. If the redirection fails, it does nothing.
+pub struct StdoutToStderr {
+    #[cfg(unix)]
+    saved: Option<libc::c_int>,
+    #[cfg(windows)]
+    saved: Option<win::Handle>,
+}
+
+#[cfg(unix)]
+impl StdoutToStderr {
+    pub fn new() -> Self {
+        let _ = std::io::stdout().flush();
+        // SAFETY: plain file descriptor calls on the standard descriptors.
+        let saved = unsafe {
+            let saved = libc::dup(libc::STDOUT_FILENO);
+            if saved < 0 {
+                None
+            } else if libc::dup2(libc::STDERR_FILENO, libc::STDOUT_FILENO) < 0 {
+                libc::close(saved);
+                None
+            } else {
+                Some(saved)
+            }
+        };
+        StdoutToStderr { saved }
+    }
+}
+
+#[cfg(unix)]
+impl Drop for StdoutToStderr {
+    fn drop(&mut self) {
+        let _ = std::io::stdout().flush();
+        if let Some(saved) = self.saved.take() {
+            // SAFETY: `saved` is the descriptor `new` duplicated, and only
+            // this guard owns it.
+            unsafe {
+                libc::dup2(saved, libc::STDOUT_FILENO);
+                libc::close(saved);
+            }
+        }
+    }
+}
+
+#[cfg(windows)]
+mod win {
+    use std::ffi::c_void;
+
+    pub type Handle = *mut c_void;
+    pub const STD_OUTPUT_HANDLE: u32 = -11i32 as u32;
+    pub const STD_ERROR_HANDLE: u32 = -12i32 as u32;
+    pub const INVALID_HANDLE_VALUE: Handle = -1isize as Handle;
+
+    #[link(name = "kernel32")]
+    extern "system" {
+        pub fn GetStdHandle(std_handle: u32) -> Handle;
+        pub fn SetStdHandle(std_handle: u32, handle: Handle) -> i32;
+    }
+}
+
+// Rust's stdout and `std::process::Command` both look up the standard handle
+// with `GetStdHandle` when they use it, so swapping the handle is enough.
+#[cfg(windows)]
+impl StdoutToStderr {
+    pub fn new() -> Self {
+        let _ = std::io::stdout().flush();
+        // SAFETY: plain calls on the process's standard handles.
+        let saved = unsafe {
+            let out = win::GetStdHandle(win::STD_OUTPUT_HANDLE);
+            let err = win::GetStdHandle(win::STD_ERROR_HANDLE);
+            if out == win::INVALID_HANDLE_VALUE
+                || err == win::INVALID_HANDLE_VALUE
+                || err.is_null()
+                || win::SetStdHandle(win::STD_OUTPUT_HANDLE, err) == 0
+            {
+                None
+            } else {
+                Some(out)
+            }
+        };
+        StdoutToStderr { saved }
+    }
+}
+
+#[cfg(windows)]
+impl Drop for StdoutToStderr {
+    fn drop(&mut self) {
+        let _ = std::io::stdout().flush();
+        if let Some(saved) = self.saved.take() {
+            // SAFETY: restores the handle `new` replaced.
+            unsafe {
+                win::SetStdHandle(win::STD_OUTPUT_HANDLE, saved);
+            }
+        }
+    }
+}
diff --git a/tests/test-linux.sh b/tests/test-linux.sh
index 7be1450b1..9702d9607 100644
--- a/tests/test-linux.sh
+++ b/tests/test-linux.sh
@@ -378,3 +378,47 @@ teardown() {
     [[ "$status" -ne 0 ]]
     grep -q '^praise = "\*"$' rproj.toml
 }
+
+@test "run script with inline dependencies" {
+    cd "$BATS_TEST_TMPDIR"
+    rm -rf scriptdir && mkdir scriptdir && cd scriptdir
+
+    # a plain script runs like `rig run -f`
+    printf 'cat(commandArgs(TRUE), "\\n")\n' > plain.R
+    run rig run plain.R a b
+    [[ "$status" -eq 0 ]]
+    echo "$output" | grep -q "^a b"
+
+    cat > deps.R <<'SCRIPT'
+# /// script
+# [dependencies]
+# R = ">= 4.1"
+# praise = "*"
+# ///
+cat("praise", format(packageVersion("praise")), "\n")
+cat("libpath", .libPaths()[1], "\n")
+cat("args", commandArgs(TRUE), "\n")
+SCRIPT
+    run rig run deps.R x
+    [[ "$status" -eq 0 ]]
+    echo "$output" | grep -q "^praise "
+    echo "$output" | grep -q "^libpath .*scripts"
+    echo "$output" | grep -q "^args x"
+
+    # the second run reuses the environment
+    run rig run deps.R
+    [[ "$status" -eq 0 ]]
+    ! echo "$output" | grep -q "Setting up the environment"
+
+    # setting up the environment writes nothing to stdout, that is the
+    # script's. --no-cache forces a new environment.
+    printf '# /// script\n# [dependencies]\n# praise = "*"\n# ///\ncat("only this\\n")\n' > quiet.R
+    out="$(rig --no-cache run quiet.R 2>/dev/null)"
+    [[ "$out" == "only this" ]]
+
+    # a broken block is an error
+    printf '# /// script\n# [dependencies]\n1\n' > bad.R
+    run rig run bad.R
+    [[ "$status" -ne 0 ]]
+    echo "$output" | grep -q "does not start with"
+}
diff --git a/tests/test-macos.sh b/tests/test-macos.sh
index 9e6d3ae91..2d6b279b5 100644
--- a/tests/test-macos.sh
+++ b/tests/test-macos.sh
@@ -507,3 +507,47 @@ teardown() {
     [[ "$status" -ne 0 ]]
     grep -q '^praise = "\*"$' rproj.toml
 }
+
+@test "run script with inline dependencies" {
+    cd "$BATS_TEST_TMPDIR"
+    rm -rf scriptdir && mkdir scriptdir && cd scriptdir
+
+    # a plain script runs like `rig run -f`
+    printf 'cat(commandArgs(TRUE), "\\n")\n' > plain.R
+    run rig run plain.R a b
+    [[ "$status" -eq 0 ]]
+    echo "$output" | grep -q "^a b"
+
+    cat > deps.R <<'SCRIPT'
+# /// script
+# [dependencies]
+# R = ">= 4.1"
+# praise = "*"
+# ///
+cat("praise", format(packageVersion("praise")), "\n")
+cat("libpath", .libPaths()[1], "\n")
+cat("args", commandArgs(TRUE), "\n")
+SCRIPT
+    run rig run deps.R x
+    [[ "$status" -eq 0 ]]
+    echo "$output" | grep -q "^praise "
+    echo "$output" | grep -q "^libpath .*scripts"
+    echo "$output" | grep -q "^args x"
+
+    # the second run reuses the environment
+    run rig run deps.R
+    [[ "$status" -eq 0 ]]
+    ! echo "$output" | grep -q "Setting up the environment"
+
+    # setting up the environment writes nothing to stdout, that is the
+    # script's. --no-cache forces a new environment.
+    printf '# /// script\n# [dependencies]\n# praise = "*"\n# ///\ncat("only this\\n")\n' > quiet.R
+    out="$(rig --no-cache run quiet.R 2>/dev/null)"
+    [[ "$out" == "only this" ]]
+
+    # a broken block is an error
+    printf '# /// script\n# [dependencies]\n1\n' > bad.R
+    run rig run bad.R
+    [[ "$status" -ne 0 ]]
+    echo "$output" | grep -q "does not start with"
+}
diff --git a/website/_partials/faq.md b/website/_partials/faq.md
index c656885d9..907f6a062 100644
--- a/website/_partials/faq.md
+++ b/website/_partials/faq.md
@@ -100,6 +100,29 @@
 >
 </details>
 
+<details>
+<summary>Can an R script declare the packages it needs?</summary>
+>
+> Yes. Put a `# /// script` comment block at the top of the script, with
+> the packages and the R version it needs, and run it with
+> `rig run script.R`:
+>
+> ```r
+> # /// script
+> # [dependencies]
+> # R = ">= 4.4"
+> # cli = "*"
+> # ///
+> cli::cli_text("Hello from {.pkg cli}!")
+> ```
+>
+> rig creates an environment for the script in its cache directory,
+> installs R and the packages if needed, and runs the script there. Later
+> runs reuse the environment. This works the same in admin and user mode;
+> if rig needs to install R, it installs it the way the current mode does.
+> See [`rig run`](reference/run.qmd) for the details.
+</details>
+
 <details>
 <summary>How is rig different from RSwitch?</summary>
 >
diff --git a/website/assets/logo-mono.svg b/website/assets/logo-mono.svg
new file mode 100644
index 000000000..457d76d38
--- /dev/null
+++ b/website/assets/logo-mono.svg
@@ -0,0 +1,26 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100" role="img" aria-label="rig">
+  <title>rig</title>
+
+  <!-- Single-colour glyph for the macOS menu bar / favicons. No hex, no
+       wordmark: neither survives at 16px. Same mark geometry as logo.svg,
+       scaled from its bounding box (46..140, 36..142) into a 100x100 box.
+       Cuts are slightly fatter than in logo.svg so they stay open at 16px. -->
+
+  <defs>
+    <mask id="rig-mono-cut">
+      <rect x="0" y="0" width="200" height="200" fill="#fff"/>
+      <ellipse cx="88" cy="74" rx="14" ry="12" fill="#000"/>
+      <path d="M 62 90 L 134 100 L 134 116 L 62 106 Z" fill="#000"/>
+      <path d="M 56 104 L 56 140 L 100 140 Z" fill="#000"/>
+    </mask>
+  </defs>
+
+  <g transform="translate(-23.7,-20.5) scale(0.792)" color="inherit">
+    <path d="M 66 48 L 108 58 Q 126 88 130 132 L 66 132 Z"
+          fill="currentColor" mask="url(#rig-mono-cut)"/>
+    <g fill="none" stroke="currentColor" stroke-linecap="round">
+      <line x1="61" y1="40" x2="61" y2="138" stroke-width="13"/>
+      <line x1="54" y1="137" x2="138" y2="137" stroke-width="11"/>
+    </g>
+  </g>
+</svg>
diff --git a/website/assets/logo.svg b/website/assets/logo.svg
new file mode 100644
index 000000000..e05361423
--- /dev/null
+++ b/website/assets/logo.svg
@@ -0,0 +1,45 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 173.2 200" width="173.2" height="200" role="img" aria-label="rig">
+  <title>rig</title>
+
+  <!-- Hex sticker geometry: regular hexagon, points at top and bottom,
+       side 100 => width 100*sqrt(3) = 173.2, height 200. -->
+
+  <!-- hex body -->
+  <path d="M 86.6 0 L 173.2 50 L 173.2 150 L 86.6 200 L 0 150 L 0 50 Z"
+        fill="#1B2A41"/>
+
+  <!-- inner border -->
+  <path d="M 86.6 7 L 167.14 53.5 L 167.14 146.5 L 86.6 193 L 6.06 146.5 L 6.06 53.5 Z"
+        fill="none" stroke="#F2EFE9" stroke-width="6" stroke-linejoin="round"/>
+
+  <!-- Mainsail = the bowl of an R. The head slopes down from the masthead
+       like a gaff, the leech bellies out to leeward, the foot sits on the
+       boom. The counter is the sail's window. -->
+  <path fill="#E8703A" fill-rule="evenodd"
+        d="M 66 46
+           L 94 51
+           C 114 55, 123 62, 123 71
+           C 123 81, 114 92, 94 92
+           L 66 92 Z
+           M 78 61
+           L 92 63
+           C 102 65, 106 67, 106 71
+           C 106 76, 102 80, 92 80
+           L 78 80 Z"/>
+
+  <!-- Jib / R's leg: runs from the bowl junction down to the clew. -->
+  <path fill="#E8703A"
+        d="M 90 92 L 111 92 L 135 132 L 112 132 Z"/>
+
+  <!-- mast: also the R's stem -->
+  <line x1="61" y1="40" x2="61" y2="137"
+        stroke="#F2EFE9" stroke-width="11" stroke-linecap="round"/>
+
+  <!-- boom: also the R's baseline -->
+  <line x1="54" y1="137" x2="140" y2="137"
+        stroke="#F2EFE9" stroke-width="9" stroke-linecap="round"/>
+
+  <text x="86.6" y="172" text-anchor="middle"
+        font-family="Helvetica Neue, Helvetica, Arial, sans-serif"
+        font-size="32" font-weight="600" letter-spacing="3" fill="#F2EFE9">rig</text>
+</svg>

From 768c544c5e7ba7b916c4db193b4400bc386a7218 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A1bor=20Cs=C3=A1rdi?= <csardi.gabor@gmail.com>
Date: Thu, 1 Oct 2026 12:48:36 +0200
Subject: [PATCH 2/3] Fix clippy

---
 src/rvenv.rs | 8 +++++---
 src/scrun.rs | 4 ++--
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/src/rvenv.rs b/src/rvenv.rs
index 828dec4cf..efdb15eac 100644
--- a/src/rvenv.rs
+++ b/src/rvenv.rs
@@ -355,6 +355,10 @@ pub fn project_r_wrapper(root: &Path) -> PathBuf {
     project_bin(root).join(if cfg!(windows) { "R.exe" } else { "R" })
 }
 
+/// The real R binary an rvenv wrapper forwards to, and the environment
+/// variables it sets. See [`rvenv_wrapper_target`].
+pub type WrapperTarget = (PathBuf, Vec<(String, String)>);
+
 /// What the `.rvenv/bin/R` or `.rvenv/bin/Rscript` wrapper at `wrapper` would
 /// run: the real R binary it forwards to, and the environment variables it
 /// sets (see [`rvenv_env_vars`]). `None` if `wrapper` is not such a wrapper,
@@ -363,9 +367,7 @@ pub fn project_r_wrapper(root: &Path) -> PathBuf {
 /// `rig run` uses this to start the real R directly, which saves a shell
 /// start (Unix) or a shim start (Windows) on every run. The result is the
 /// same as running the wrapper, both come from the same `rvenv.cfg`.
-pub fn rvenv_wrapper_target(
-    wrapper: &Path,
-) -> Result<Option<(PathBuf, Vec<(String, String)>)>, Box<dyn Error>> {
+pub fn rvenv_wrapper_target(wrapper: &Path) -> Result<Option<WrapperTarget>, Box<dyn Error>> {
     let Some(bin) = wrapper.parent() else {
         return Ok(None);
     };
diff --git a/src/scrun.rs b/src/scrun.rs
index eb565e3e9..04201d8e6 100644
--- a/src/scrun.rs
+++ b/src/scrun.rs
@@ -16,7 +16,7 @@ use crate::rproj::Bin;
 use crate::rproj::RPROJ_MANIFEST_FILE;
 use crate::rvenv::{
     ensure_rvenv_files, find_project_root, project_r_wrapper, rscript_of, rvenv_sync_needed,
-    rvenv_wrapper_target,
+    rvenv_wrapper_target, WrapperTarget,
 };
 use crate::script_meta::script_r_binary;
 use crate::stdout_redirect::StdoutToStderr;
@@ -210,7 +210,7 @@ struct RunEnv {
     /// it forwards to and the variables it sets (see
     /// `rvenv_wrapper_target`). Running these directly skips starting the
     /// wrapper, `rbin` is still what dry runs and logs show.
-    direct: Option<(PathBuf, Vec<(String, String)>)>,
+    direct: Option<WrapperTarget>,
     /// `R_ENVIRON_USER` override for `--no-project` (see
     /// `no_project_renviron_user`).
     renviron_user: Option<PathBuf>,

From 591c24222621a219dabe0fba3ac5dc363eaff177 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A1bor=20Cs=C3=A1rdi?= <csardi.gabor@gmail.com>
Date: Thu, 1 Oct 2026 12:50:14 +0200
Subject: [PATCH 3/3] Fix a test error on Linux

---
 src/proj.rs | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/src/proj.rs b/src/proj.rs
index ab566e52d..3e6daa6c4 100644
--- a/src/proj.rs
+++ b/src/proj.rs
@@ -5816,21 +5816,23 @@ mod tests {
     fn select_sync_target_for_arch_picks_the_requested_arch() {
         let this_os = this_os_family();
         let native = native_arch_name(std::env::consts::ARCH);
-        let other = if native == "x86_64" {
+        // "arm64" on macOS, "aarch64" on Linux and Windows
+        let other = native_arch_name(if native == "x86_64" {
             "arm64"
         } else {
             "x86_64"
-        };
+        });
         let targets = vec![
             target("4.6.1", &format!("{}-{}", this_os, native)),
             target("4.6.1", &format!("{}-{}", this_os, other)),
         ];
-        let picked = select_sync_target_for_arch(&targets, None, None, Some(other)).unwrap();
+        let picked =
+            select_sync_target_for_arch(&targets, None, None, Some(other.as_str())).unwrap();
         assert_eq!(
             platform_arch(&picked.platform)
                 .map(native_arch_name)
                 .as_deref(),
-            Some(other)
+            Some(other.as_str())
         );
         let picked = select_sync_target(&targets, None, None).unwrap();
         assert_eq!(