docs: compile --self-extracting, upgrade caching, jsr/overrides in package.json (#2954)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Jo Franchetti <jofranchetti@gmail.com>

Author: 3 people

runtime/fundamentals/modules.md

@@ -563,6 +563,45 @@ When using a `package.json` file, dev dependencies can be added to the separate
 }
 ```
 
+### JSR packages in package.json
+
+You can depend on JSR packages directly from `package.json` using the `jsr:`
+scheme, without needing a separate `deno.json`:
+
+```json title="package.json"
+{
+  "dependencies": {
+    "@std/path": "jsr:^1.0.9"
+  }
+}
+```
+
+This works with `deno install` and brings JSR packages to any project that uses
+`package.json` for dependency management.
+
+### Dependency overrides
+
+The `overrides` field in `package.json` lets you control transitive dependency
+versions throughout your dependency tree. This is useful for applying security
+patches, fixing version compatibility issues, or replacing packages:
+
+```json title="package.json"
+{
+  "dependencies": {
+    "express": "^4.18.0"
+  },
+  "overrides": {
+    "cookie": "0.7.0",
+    "express": {
+      "qs": "6.13.0"
+    }
+  }
+}
+```
+
+In this example, `cookie` is pinned globally to `0.7.0`, while `qs` is
+overridden only when required by `express`.
+
 ### Why does Deno not have a `devImports` field?
 
 To understand why Deno does not separate out dev dependencies in the package

runtime/reference/cli/compile.md

@@ -136,6 +136,43 @@ import "./worker.ts";
 deno compile main.ts
 ```
 
+## Self-Extracting Executables
+
+By default, compiled executables serve embedded files from an in-memory virtual
+file system. The `--self-extracting` flag changes this behavior so that the
+binary extracts all embedded files to disk on first run and uses real file
+system operations at runtime.
+
+```shell
+deno compile --self-extracting main.ts
+```
+
+This is useful for scenarios where code needs real files on disk, such as native
+addons or native code that reads relative files.
+
+The extraction directory is chosen in order of preference:
+
+1. `<exe_dir>/<exe_name>.fs/<hash>/` (next to the compiled binary)
+2. Platform data directory fallback:
+   - Linux: `$XDG_DATA_HOME/<exe_name>/<hash>` or
+     `~/.local/share/<exe_name>/<hash>`
+   - macOS: `~/Library/Application Support/<exe_name>/<hash>`
+   - Windows: `%LOCALAPPDATA%\<exe_name>\<hash>`
+
+Files are only extracted once — subsequent runs reuse the extracted directory if
+it already exists and the hash matches.
+
+### Trade-offs
+
+Self-extracting mode enables broader compatibility, but comes with some
+trade-offs:
+
+- **Initial startup cost**: The first run takes longer due to file extraction.
+- **Disk usage**: Extracted files take up additional space on disk.
+- **Memory usage**: Higher memory usage since embedded content can no longer be
+  referenced as static data.
+- **Tamper risk**: Users or other code can modify the extracted files on disk.
+
 ## Code Signing
 
 ### macOS

runtime/reference/cli/upgrade.md

@@ -63,6 +63,30 @@ $ deno upgrade --quiet
 This is useful for scripting environments or when you want cleaner output in CI
 pipelines.
 
+## Cached downloads
+
+Downloaded Deno binaries are cached in `$DENO_DIR/dl/`. If you reinstall the
+same version later, the cached archive is reused instead of re-downloading. For
+canary builds, old entries are automatically removed, keeping only the 10 most
+recent versions.
+
+## Checksum verification
+
+Use the `--checksum` flag to verify a downloaded binary against a known SHA-256
+hash. This protects against tampering in CI environments and security-sensitive
+setups:
+
+```shell
+$ deno upgrade --checksum=<sha256-hash> 2.7.0
+```
+
+SHA-256 checksums are published as `.sha256sum` files alongside release archives
+on GitHub:
+
+```shell
+$ curl -sL https://github.com/denoland/deno/releases/download/v2.7.0/deno-x86_64-unknown-linux-gnu.zip.sha256sum
+```
+
 ## Canary build
 
 By default, Deno will upgrade from the official GitHub releases. You can specify