retold-remote 0.0.22 → 0.0.25

package/css/retold-remote.css

@@ -2263,26 +2263,7 @@ html, body
 {
 	opacity: 1;
 }
-.retold-remote-image-explore-btn
-{
-	position: absolute;
-	bottom: 16px;
-	right: 16px;
-	background: rgba(40, 44, 52, 0.85);
-	color: #abb2bf;
-	border: 1px solid rgba(255, 255, 255, 0.15);
-	padding: 6px 14px;
-	border-radius: 6px;
-	font-size: 0.82rem;
-	cursor: pointer;
-	z-index: 20;
-	transition: background 0.2s, color 0.2s;
-}
-.retold-remote-image-explore-btn:hover
-{
-	background: rgba(97, 175, 239, 0.3);
-	color: #fff;
-}
+/* Explore button overlay styles removed — button moved to nav bar */
 .retold-remote-image-large-badge
 {
 	position: absolute;
@@ -2480,6 +2461,75 @@ html, body
 	text-align: center;
 	color: var(--retold-text-secondary);
 }
+/* Subimage region overlays */
+.retold-remote-iex-region-overlay
+{
+	border: 2px solid rgba(229, 192, 123, 0.85);
+	background: rgba(229, 192, 123, 0.08);
+	pointer-events: none;
+	position: relative;
+}
+/* Subimages sidebar panel */
+.retold-remote-subimages-panel
+{
+	overflow-y: auto;
+	height: 100%;
+}
+.retold-remote-subimages-item
+{
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	padding: 6px 10px;
+	border-bottom: 1px solid var(--retold-border);
+	cursor: default;
+	transition: background 0.15s;
+}
+.retold-remote-subimages-item:hover
+{
+	background: rgba(255, 255, 255, 0.04);
+}
+.retold-remote-subimages-item-info
+{
+	flex: 1;
+	min-width: 0;
+	overflow: hidden;
+}
+.retold-remote-subimages-item-label
+{
+	font-size: 0.82rem;
+	color: var(--retold-text);
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+.retold-remote-subimages-item-dims
+{
+	font-size: 0.7rem;
+	color: var(--retold-text-dim);
+	margin-top: 1px;
+}
+.retold-remote-subimages-item-actions
+{
+	display: flex;
+	gap: 2px;
+	margin-left: 6px;
+	flex-shrink: 0;
+}
+.retold-remote-subimages-item-actions button
+{
+	background: transparent;
+	border: 1px solid var(--retold-border);
+	border-radius: 3px;
+	color: var(--retold-text-dim);
+	cursor: pointer;
+	transition: color 0.15s, border-color 0.15s;
+}
+.retold-remote-subimages-item-actions button:hover
+{
+	color: var(--retold-text);
+	border-color: var(--retold-accent);
+}
 
 /* ============================================================
    AudioExplorer
@@ -3515,6 +3565,23 @@ html, body
 	border-color: var(--retold-accent);
 	color: var(--retold-text-primary);
 }
+.retold-remote-collections-export-btn
+{
+	padding: 3px 8px;
+	border: 1px solid var(--retold-border);
+	border-radius: 3px;
+	background: transparent;
+	color: var(--retold-text-muted);
+	font-size: 0.72rem;
+	cursor: pointer;
+	font-family: inherit;
+	margin-left: auto;
+}
+.retold-remote-collections-export-btn:hover
+{
+	border-color: var(--retold-accent);
+	color: var(--retold-text-primary);
+}
 /* ---- Item rows ---- */
 .retold-remote-collection-item
 {

package/docs/README.md

@@ -4,10 +4,18 @@ A browser-based media server and NAS file explorer. Point it at a folder and bro
 
 ## Quick Start
 
+Just the media browser:
+
 ```bash
 npx retold-remote serve /path/to/media
 ```
 
+The full stack (Retold Remote + embedded Orator-Conversion + child Ultravisor):
+
+```bash
+retold-stack /path/to/media
+```
+
 Or with Docker:
 
 ```bash
@@ -17,17 +25,24 @@ docker run -p 8086:8086 -v /path/to/media:/media retold-remote
 
 Then open `http://localhost:8086` in a browser.
 
+See [Stack Launcher](stack-launcher.md) for what `retold-stack` does and how the XDG-style data paths work.
+
 ## Features
 
 - **Gallery browser** with grid and list views, thumbnail generation, and lazy loading
 - **Image viewer** with three fit modes, 0.25x-8x zoom, and EXIF orientation support
 - **Video viewer** with action menu, in-browser playback, VLC streaming, and frame explorer
 - **Audio viewer** with waveform visualization, selection-based playback, and segment extraction
-- **eBook reader** for EPUB and MOBI with table of contents and page navigation
+- **eBook reader** for EPUB and MOBI with table of contents, page navigation, text selection capture, and visual region selection
+- **PDF viewer** with full pdf.js rendering, page navigation, text layer selection, and visual region selection
+- **Document conversion** for DOC, DOCX, RTF, ODT, WPD, ODP, PPT(X), ODS, XLS(X) — converted to PDF on the fly via Orator-Conversion + LibreOffice
 - **Code/text viewer** with syntax highlighting for 30+ languages
-- **PDF viewer** via native browser rendering
 - **Archive browsing** into zip, 7z, rar, tar.gz, cbz, and cbr files as virtual folders
 - **Filtering and sorting** by media type, extension, file size, date, and text search (with regex)
+- **Subimage regions** — draw labeled rectangles on images, ebook pages, and PDF pages; persisted per file
+- **Collections & Export** — bookmark files, image crops, video clips, audio clips, and document regions; export the whole collection to a folder with proper file cutting
+- **Stack mode** — single command launches Ultravisor coordinator + Retold Remote + embedded Orator-Conversion with sane XDG data paths
+- **Ultravisor offload** — heavy work (frame extraction, waveforms, conversions) dispatched to a beacon worker on a faster machine
 - **15 themes** from greyscale to retro and cyberpunk
 - **Full keyboard navigation** across every mode
 - **Media type override** to force any file open as image, video, audio, or text (keys 1-4)
@@ -40,14 +55,16 @@ Then open `http://localhost:8086` in a browser.
 | Document | Contents |
 |----------|----------|
 | [Server Setup and Docker](server-setup.md) | Installation, CLI options, environment variables, configuration, Docker |
+| [Stack Launcher](stack-launcher.md) | `retold-stack` and `--stack` flag, XDG paths, child process orchestration |
+| [Ultravisor Integration](ultravisor-integration.md) | Offloading heavy media processing to a beacon worker |
 | [Image Viewer](image-viewer.md) | Fit modes, zoom, keyboard shortcuts, mouse interactions |
 | [Video Viewer](video-viewer.md) | Action menu, in-browser playback, VLC streaming |
 | [Audio Viewer](audio-viewer.md) | HTML5 playback, autoplay, VLC streaming |
-| [eBook Reader](ebook-reader.md) | EPUB/MOBI support, table of contents, page navigation |
-| [Image Explorer](image-explorer.md) | Deep-zoom with OpenSeadragon, DZI tiling, coordinate display |
+| [eBook Reader](ebook-reader.md) | EPUB/MOBI support, TOC, page nav, text/region selection |
+| [Image Explorer](image-explorer.md) | Deep-zoom with OpenSeadragon, DZI tiling, region selection |
 | [Video Explorer](video-explorer.md) | Frame grid, timeline, range selection, clip extraction |
 | [Audio Explorer](audio-explorer.md) | Waveform visualization, selection, zoom, segment playback |
-| [Collections](collections.md) | Bookmarks, favorites, quick-add, item types, operation plans |
+| [Collections](collections.md) | Bookmarks, favorites, quick-add, item types, operation plans, export |
 | [File Metadata](metadata.md) | Info overlay, sidebar metadata, EXIF/GPS, ffprobe, explorer info bars |
 
 ## Keyboard Shortcuts (All Modes)
@@ -158,11 +175,24 @@ In the frame preview overlay:
 | `+` / `=` | Zoom in |
 | `-` | Zoom out |
 | `0` | Reset zoom |
-| `a` | Quick-add to collection |
+| `s` | Toggle region selection mode (draw rectangles) |
+| `a` | Quick-add to collection (current region if selected) |
 | `b` | Toggle collection panel |
 | `h` | Toggle favorite |
 | `Esc` | Back to viewer |
 
+### Document Viewer (PDF / EPUB)
+
+| Key | Action |
+|-----|--------|
+| `s` | Toggle visual region selection mode |
+| `a` | Quick-add document region to collection |
+| `Esc` | Back to gallery |
+
+In the PDF viewer, page navigation buttons and a page input are in the controls bar. The text layer supports native browser text selection — use the **Save Selection** button to capture selected text as a labeled region.
+
+In the EPUB reader, the controls bar exposes **Save Selection** (captures the selected text + CFI) and **Select Region** (draws a rectangle over the rendered page).
+
 ### Sidebar (F9)
 
 | Key | Action |
@@ -184,7 +214,9 @@ mp4, webm, mov, mkv, avi, wmv, flv, m4v, ogv, mpg, mpeg, mpe, mpv, m2v, ts, mts,
 mp3, wav, ogg, flac, aac, m4a, wma, oga
 
 ### Documents
-pdf, epub, mobi
+pdf, epub, mobi, doc, docx, rtf, odt, wpd, wps, pages, odp, ppt, pptx, ods, xls, xlsx
+
+Documents beyond pdf/epub/mobi are converted to PDF on the fly via the embedded Orator-Conversion service (requires LibreOffice or Calibre on the server).
 
 ### Archives
 zip, 7z, rar, tar, tar.gz, tar.bz2, tar.xz, tgz, cbz, cbr
@@ -204,13 +236,16 @@ These external tools enhance functionality when available on the server:
 
 | Tool | Feature |
 |------|---------|
-| **sharp** (npm) | Fast image thumbnail generation |
+| **sharp** (npm) | Fast image thumbnail generation, region cropping |
 | **ImageMagick** | Fallback image thumbnails |
-| **ffmpeg** | Video thumbnails, frame extraction, audio waveforms |
+| **ffmpeg** | Video thumbnails, frame extraction, audio waveforms, clip cutting |
 | **ffprobe** | Media metadata (duration, resolution, codec) |
 | **7-Zip** (7z) | Archive browsing for rar, 7z, tar.* formats |
 | **VLC** | External video streaming |
-| **ebook-convert** (Calibre) | MOBI to EPUB conversion |
+| **audiowaveform** (BBC) | Faster audio waveform peak generation |
+| **ebook-convert** (Calibre) | MOBI/AZW to EPUB conversion (and PDF fallback for documents) |
+| **LibreOffice** (`soffice`) | DOC/DOCX/RTF/ODT/WPD/PPT(X)/XLS(X) to PDF conversion |
+| **pdftk** + **pdftoppm** (poppler) | PDF page extraction and rendering (used by Orator-Conversion) |
 
 Without these tools the application still works -- images serve directly, videos play in-browser, and zip/cbz archives use native extraction.
 
@@ -231,7 +266,20 @@ Without these tools the application still works -- images serve directly, videos
 | GET | `/api/media/audio-waveform?path=&peaks=` | Audio waveform peak data |
 | GET | `/api/media/audio-segment?path=&start=&end=` | Extract audio segment |
 | GET | `/api/media/ebook-convert?path=` | Convert MOBI to EPUB |
-| GET | `/api/media/ebook/:cacheKey/:filename` | Serve converted ebook |
+| GET | `/api/media/doc-convert?path=` | Convert DOC/DOCX/RTF/ODT/WPD/etc. to PDF |
+| GET | `/api/media/ebook/:cacheKey/:filename` | Serve converted ebook or PDF |
+| GET | `/api/media/pdf-text?path=&page=` | Extract text from a PDF page |
+| GET | `/api/media/subimage-regions?path=` | List labeled regions for an image, ebook, or PDF |
+| POST | `/api/media/subimage-regions` | Add a labeled region (visual or text-selection) |
+| PUT | `/api/media/subimage-regions/:id` | Update a region's label or coordinates |
+| DELETE | `/api/media/subimage-regions/:id?path=` | Remove a labeled region |
+| GET | `/api/collections` | List all collections |
+| POST | `/api/collections/:guid/items` | Add items to a collection |
+| POST | `/api/collections/:guid/export` | Export collection to a folder (cuts clips, crops images) |
+| POST | `/api/conversion/1.0/doc-to-pdf` | Convert any document buffer to PDF (via Orator-Conversion) |
+| POST | `/api/conversion/1.0/pdf-to-page-png/:Page` | Render a PDF page as PNG |
+| POST | `/api/conversion/1.0/pdf-to-page-jpg/:Page/:LongSidePixels` | Render and resize a PDF page as JPEG |
+| POST | `/api/conversion/1.0/image/resize` | Resize an image |
 | POST | `/api/media/open` | Open file in external player (VLC) |
 
 ## License

package/docs/_sidebar.md

@@ -2,6 +2,7 @@
 
 - Getting Started
   - [Server Setup & Docker](server-setup.md)
+  - [Stack Launcher](stack-launcher.md)
   - [Ultravisor Integration](ultravisor-integration.md)
   - [Ultravisor Beacon Tool Setup](ultravisor-configuration.md)
 

package/docs/collections.md

@@ -16,6 +16,11 @@ Press `a` in any mode to add the current item to a collection. If a collection i
 | Video explorer | Video frame | Path, timestamp, cached frame image |
 | Video explorer (with selection) | Video clip | Path, start time, end time |
 | Audio explorer (with selection) | Audio clip | Path, start time, end time |
+| Image explorer (with active region) | Image crop | Path, X, Y, Width, Height in original pixels |
+| PDF viewer (with text selection) | Document region (text) | Path, page number, selected text |
+| PDF viewer (with visual region) | Document region (visual) | Path, page number, X/Y/Width/Height in PDF units |
+| EPUB reader (with text selection) | Document region (text) | Path, CFI, spine index, chapter title, selected text |
+| EPUB reader (with visual region) | Document region (visual) | Path, X/Y/Width/Height in container coordinates |
 
 ### Folder Choice
 
@@ -136,11 +141,35 @@ Pending item destinations can be edited inline by clicking the destination path.
 | `a` | Gallery, viewer, all explorers | Quick-add current item to collection |
 | `s` | Video explorer | Add selected range as video clip |
 | `s` | Audio explorer | Save audio snippet to collection |
+| `s` | Image explorer | Toggle region selection mode |
+| `s` | Document viewer (PDF/EPUB) | Toggle visual region selection mode |
 | `[` | Video explorer | Set selection start at current frame |
 | `]` | Video explorer | Set selection end at current frame |
 | `b` | All modes | Toggle collection panel |
 | `h` | All modes | Toggle favorite |
 
+## Export
+
+Collections can be exported to a folder within the content root. Each item is processed according to its type:
+
+| Item Type | Export Behavior |
+|-----------|----------------|
+| `file` / `subfile` | Copied directly to the destination |
+| `image-crop` | Cropped via sharp at the original resolution |
+| `video-clip` | Extracted via `ffmpeg -ss -t -c copy` |
+| `video-frame` | Extracted via `ffmpeg -ss -vframes 1` |
+| `audio-clip` | Extracted via `ffmpeg -ss -t -vn` |
+| `document-region` (text) | Written as a `.txt` file with the captured text and source metadata |
+| `document-region` (visual) | Metadata file describing the page and region |
+| `folder` | Copied recursively |
+| `folder-contents` | Files copied flat into the destination |
+
+Exported files are named `{sortOrder}_{label}.{ext}` so the order is preserved on disk.
+
+To export, click the **⇩ Export** button in the collection detail header. You will be prompted for a destination path (relative to the content root).
+
+The export endpoint is restricted to paths within the content root for safety — paths containing `..` or absolute paths are rejected.
+
 ## Data Storage
 
 Collections are stored server-side as Bibliograph records. Each collection is a JSON document containing the collection metadata and its items array. The favorites collection uses a well-known GUID and is created automatically.
@@ -160,3 +189,4 @@ Client-side state (which collection is open, panel width, last-used collection)
 | PUT | `/api/collections/:guid/reorder` | Reorder items (manual sort) |
 | POST | `/api/collections/copy-items` | Copy items between collections |
 | POST | `/api/collections/:guid/execute` | Execute pending operations (operation plans) |
+| POST | `/api/collections/:guid/export` | Export the collection to a folder within the content root |

package/docs/ebook-reader.md

@@ -79,12 +79,86 @@ RUN apt-get update && apt-get install -y calibre && rm -rf /var/lib/apt/lists/*
 
 ## PDF Files
 
-PDF files are rendered using the browser's native PDF viewer in an iframe. No additional tools or libraries are required. The browser provides its own controls for page navigation, zoom, and search.
+PDF files are rendered using a full **pdf.js** canvas pipeline. The library is loaded from CDN on first use; no server-side dependencies are required for basic display.
+
+### Page Navigation
+
+The controls bar exposes:
+
+- **← Prev** / **Next →** — page navigation
+- **Page input** — type a page number and press Enter to jump
+- **Zoom In / Out / Fit** — adjust scale (0.25x – 5x)
+
+### Text Selection
+
+PDF.js renders an invisible text layer over the canvas, so native browser text selection works. Drag to select text, then click **💾 Save Selection** to capture it as a labeled region.
+
+The capture stores: page number, selected text, optional label.
+
+### Visual Region Selection
+
+Click **✂ Select Region** to enter visual selection mode. A crosshair cursor appears over the page canvas. Drag a rectangle, release, and a label input appears in the controls bar.
+
+The capture stores: page number, X/Y/Width/Height in PDF units (so the region remaps correctly at any zoom level), optional label.
+
+### Server-Side Text Extraction
+
+`GET /api/media/pdf-text?path=<file>&page=<num>` returns the extracted text for a specific page (via pdf-parse). This is useful for search indexing or for when you want the full text without selecting it manually.
+
+## Convertible Document Formats
+
+Beyond PDF/EPUB/MOBI, the viewer also handles `.doc`, `.docx`, `.rtf`, `.odt`, `.wpd`, `.wps`, `.pages`, `.odp`, `.ppt`, `.pptx`, `.ods`, `.xls`, and `.xlsx` files. These are converted to PDF on the fly via the embedded **Orator-Conversion** service, then displayed in the same pdf.js viewer.
+
+### Conversion Pipeline
+
+1. The browser opens a convertible document
+2. Retold Remote shows a "Converting document to PDF..." spinner
+3. The server calls `GET /api/media/doc-convert?path=<file>` which delegates to `orator-conversion`'s `doc-to-pdf` custom converter
+4. The converter pipes the file through LibreOffice headless (`soffice --headless --convert-to pdf`)
+5. Falls back to Calibre's `ebook-convert` if LibreOffice is unavailable
+6. The resulting PDF is cached in the same Parime cache as ebooks (separate `manifest-pdf.json`)
+7. The browser loads the PDF in the standard pdf.js viewer with full text and region selection
+
+Conversion results are cached per file (keyed by path + mtime), so reopening the same document is instant after the first conversion.
+
+### Required Tools
+
+| Tool | Use |
+|------|-----|
+| **LibreOffice** (`soffice`) | Best fidelity for Word, RTF, ODT, WordPerfect, PowerPoint, Excel |
+| **Calibre** (`ebook-convert`) | Fallback for documents LibreOffice can't handle |
+
+Install at least one of them on the server. On macOS: `brew install --cask libreoffice` or `brew install calibre`.
+
+## eBook Selection Features
+
+The EPUB reader supports the same labeled-region capture pattern as PDF and image viewers.
+
+### Save Text Selection
+
+1. Select text in the rendered EPUB content (works through the epub.js iframe via `getContents()`)
+2. Click **💾 Save Selection** in the controls bar
+3. Enter a label and save
+
+The capture stores:
+
+- **CFI** (Canonical Fragment Identifier) — exact location for re-navigating later
+- **Spine index** — which section of the book
+- **Chapter title** — best-effort lookup from the TOC
+- **Selected text** — the actual highlighted prose
+
+Click a saved text selection in the **Regions** sidebar tab to navigate back to its exact location via `rendition.display(cfi)`.
+
+### Visual Region Selection
+
+Click **✂ Select Region** to overlay a transparent crosshair on the rendered page. Drag a rectangle to capture a visual area. The capture stores X/Y/Width/Height plus the viewport dimensions at capture time (so coordinates can be remapped if the window is resized later).
 
 ## Limitations
 
 - MOBI conversion requires Calibre's `ebook-convert` on the server
+- Document conversion (DOC, DOCX, RTF, etc.) requires LibreOffice or Calibre on the server
 - DRM-protected ebooks cannot be read
 - Complex EPUB layouts (fixed-layout EPUBs, heavy CSS) may not render perfectly
 - The reader uses single-page mode only (no two-page spreads)
 - Page numbers shown in the UI correspond to the reflowed content, not the original book pagination
+- EPUB visual region coordinates are container-relative; they remap reasonably at different window sizes but are not perfectly stable across major layout reflows

package/docs/image-explorer.md

@@ -51,11 +51,37 @@ If Sharp is not available on the server, the image loads directly regardless of
 | `+` / `=` | Zoom in (1.5x) |
 | `-` | Zoom out (1.5x) |
 | `0` | Reset to home zoom (fit to view) |
-| `a` | Quick-add to active collection |
+| `s` | Toggle region selection mode |
+| `a` | Quick-add to active collection (current region if one is selected) |
 | `b` | Toggle collection panel |
 | `h` | Toggle favorite |
 | `Esc` | Back to image viewer |
 
+## Subimage Regions
+
+Press `s` (or click the **✂ Select** button in the header) to enter region selection mode. The cursor changes to a crosshair and OpenSeadragon's drag-to-pan is temporarily disabled.
+
+Drag a rectangle on the image. On release, an inline label input appears in the controls bar — type a name and hit Enter. The region is saved with these coordinates:
+
+- **X, Y** — top-left corner in original image pixels
+- **Width, Height** — dimensions in original image pixels
+
+Saved regions render as gold-bordered overlays with floating label badges. They persist per file via the SubimageService and appear in the **Regions** sidebar tab.
+
+### Region Actions
+
+From the **Regions** sidebar tab you can:
+
+- 🔍 **Navigate** — zoom the explorer to the saved region (`viewport.fitBounds(imageRect)`)
+- ➕ **Add to Collection** — saves as an `image-crop` collection item with the original-pixel `CropRegion`
+- 🗑️ **Delete** — removes the region
+
+### Multiple Regions
+
+You can save unlimited labeled regions per image. They never lose resolution because the coordinates are stored in the original image pixel space, not in viewport pixels. When the collection is exported, each region is cropped at full resolution via `sharp.extract()`.
+
+This same labeling pattern works on CBZ/CBR comic pages (each page is a regular image inside an archive — no special handling needed) and is the foundation for the document region system in the EPUB and PDF viewers.
+
 ## Coordinate Display
 
 In DZI tile mode, the info bar shows the pixel coordinates of the point under the cursor in real time (e.g., "(4096, 3072)"). This updates as the mouse moves across the canvas and reflects the actual pixel position in the original full-resolution image.

package/docs/server-setup.md

@@ -21,31 +21,31 @@ The build step bundles the client-side JavaScript with Quackage and copies asset
 
 ## Running the Server
 
-### CLI Command
+### CLI Commands
 
-```bash
-retold-remote serve [content-path] [options]
-```
-
-Or using the short alias:
+There are three bin entries provided by the `retold-remote` package:
 
 ```bash
-rr serve /path/to/media
+retold-remote serve [content-path] [options]   # full form
+rr serve [content-path] [options]               # short alias
+retold-stack [content-path] [options]           # convenience: serve --stack
 ```
 
 If `content-path` is omitted, the current directory is served.
 
+The `retold-stack` shortcut auto-injects `serve --stack`, which spawns Ultravisor as a child process and uses XDG-style data paths. See [Stack Launcher](stack-launcher.md) for the full story.
+
 ### Options
 
 | Flag | Description | Default |
 |------|-------------|---------|
 | `-p, --port [port]` | Port to listen on | Random 7000-7999 |
-| `-H, --hashed-filenames` | Enable hashed filename mode (hides real paths from browser) | Off |
-| `-c, --cache-path [path]` | Root cache directory | `./dist/retold-cache/` |
-| `--cache-thumbnails [path]` | Override thumbnail cache location | `<cache-root>/thumbnails/` |
-| `--cache-archives [path]` | Override archive extraction cache | `<cache-root>/archives/` |
-| `--cache-video-frames [path]` | Override video frame cache | `<cache-root>/video-frames/` |
-| `--cache-audio-waveforms [path]` | Override audio waveform cache | `<cache-root>/audio-waveforms/` |
+| `--no-hash` | Disable hashed filename mode (use plain paths in URLs) | Hashing on |
+| `-c, --cache-path [path]` | Root cache directory | `./dist/retold-cache/` (or `~/.cache/retold-remote/` in stack mode) |
+| `--cache-server [url]` | URL of a remote Parime cache server | None |
+| `-u, --ultravisor [url]` | Connect to an Ultravisor mesh; URL defaults to `http://localhost:54321` if omitted | None |
+| `--stack` | Spawn Ultravisor as a child process and connect to it. Uses XDG-style data paths under `~/.local/share` and `~/.cache`. See [Stack Launcher](stack-launcher.md) | Off |
+| `-l, --logfile [path]` | Write logs to a file (auto-generates timestamped name if path omitted) | Console only |
 
 ### Direct Node.js
 
@@ -65,20 +65,30 @@ Default port is `8086` when using `server.js` directly.
 ### Examples
 
 ```bash
-# Serve current directory on port 8086
-node server.js
+# Serve current directory on a random port
+retold-remote serve
 
 # Serve a specific folder
-node server.js /mnt/nas/media
+retold-remote serve /mnt/nas/media
 
 # CLI with custom port
 retold-remote serve /mnt/nas/media -p 3000
 
-# Hashed filenames for privacy
-retold-remote serve /mnt/nas/media -H
+# Plain paths in URLs (disable hashing)
+retold-remote serve /mnt/nas/media --no-hash
 
 # Custom cache location (useful for Docker volumes)
 retold-remote serve /media -c /cache
+
+# Connect to an existing Ultravisor mesh
+retold-remote serve /media -u http://192.168.1.100:54321
+
+# Full stack: spawn Ultravisor as a child process, embed Orator-Conversion,
+# use XDG paths (~/.local/share/ultravisor, ~/.cache/retold-remote)
+retold-stack /mnt/nas/media
+
+# Same thing via the explicit flag
+retold-remote serve --stack /mnt/nas/media
 ```
 
 ## Configuration