retold-remote 0.0.22 → 0.0.25

package/web-application/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/web-application/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/web-application/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/web-application/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/web-application/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/web-application/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

package/web-application/docs/stack-launcher.md

@@ -0,0 +1,218 @@
+# Stack Launcher
+
+The `--stack` flag (and the `retold-stack` shortcut) brings up the full Retold stack as a single command: an embedded Ultravisor coordinator, the Retold Remote media browser, and Orator-Conversion (embedded inside Retold Remote). Point it at any directory and it just works — sane XDG-style data paths, automatic readiness polling, and graceful shutdown of all child processes.
+
+## Quick Start
+
+```bash
+# Run the full stack against the current directory
+retold-stack
+
+# Or against any directory
+retold-stack /mnt/nas/media
+
+# Or via the explicit flag
+retold-remote serve --stack /mnt/nas/media
+```
+
+That's it. No config files, no separate terminals, no manual port wiring.
+
+## What Gets Launched
+
+| Component | Where it runs | Port |
+|-----------|---------------|------|
+| **Ultravisor** | Spawned as a child process | 54321 |
+| **Retold Remote** | Main process (the one you started) | Random 7000-7999 (override with `-p`) |
+| **Orator-Conversion** | Embedded inside Retold Remote (no separate process) | Same as Retold Remote |
+
+The stack launcher:
+1. Resolves XDG-style data paths
+2. Detects whether Ultravisor is already running on port 54321 (and reuses it if so)
+3. Spawns Ultravisor as a child process with a generated config file
+4. Polls until Ultravisor is accepting connections (up to 30 seconds)
+5. Sets the `UltravisorURL` automatically so Retold Remote registers as a beacon
+6. Starts the Retold Remote server with Orator-Conversion embedded
+7. Streams the Ultravisor child's stdout/stderr through the main logger with an `[ultravisor]` prefix
+8. On `SIGINT`/`SIGTERM`, disconnects the beacon, kills the Ultravisor child gracefully, and exits
+
+## Default Data Paths
+
+The stack launcher uses [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) defaults so data lives in predictable, user-scoped locations regardless of what directory you launched from.
+
+| Purpose | Default Path | Override |
+|---------|-------------|----------|
+| Ultravisor datastore | `~/.local/share/ultravisor/datastore/` | `$XDG_DATA_HOME/ultravisor/datastore/` |
+| Ultravisor staging | `~/.local/share/ultravisor/staging/` | `$XDG_DATA_HOME/ultravisor/staging/` |
+| Retold Remote cache | `~/.cache/retold-remote/` | `$XDG_CACHE_HOME/retold-remote/`, or `-c` flag |
+| Stack config files | `~/.config/retold-stack/` | `$XDG_CONFIG_HOME/retold-stack/` |
+
+The cache directory holds thumbnails, video frames, audio waveforms, archive extractions, and converted ebooks/PDFs.
+
+The Ultravisor datastore holds the work-queue journal and beacon registry.
+
+These paths are created on first launch if they do not already exist.
+
+## CLI Reference
+
+### `retold-stack`
+
+Convenience entry point that auto-injects `serve --stack`.
+
+```bash
+retold-stack [content-path] [options]
+```
+
+All options accepted by `retold-remote serve` are forwarded.
+
+### `retold-remote serve --stack`
+
+The full form. Useful when you want to combine `--stack` with other flags.
+
+```bash
+retold-remote serve --stack [content-path] [options]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--stack` | Spawn Ultravisor as a child process and connect to it. Sets cache root to `~/.cache/retold-remote/` if `-c` is not passed. Auto-sets the Ultravisor URL to `http://localhost:54321`. |
+
+All other `serve` options still apply (`-p`, `--no-hash`, `-c`, `-l`, etc.).
+
+## Examples
+
+### Browse the current directory with the full stack
+
+```bash
+cd ~/Pictures
+retold-stack
+```
+
+### Browse a specific NAS share
+
+```bash
+retold-stack /mnt/nas/media
+```
+
+### Pin the port and stash logs to a file
+
+```bash
+retold-stack /mnt/nas/media -p 8086 -l ~/retold.log
+```
+
+### Override just the Retold cache location
+
+```bash
+retold-remote serve --stack /mnt/nas/media -c /var/cache/retold
+```
+
+### Reuse an already-running Ultravisor
+
+If port 54321 is already accepting connections, the stack launcher detects this and connects to the existing instance instead of spawning a new one. The log line will read:
+
+```
+[stack] ultravisor already running on port 54321, reusing
+```
+
+This means you can leave Ultravisor running across multiple Retold Remote launches without conflict.
+
+## Logging
+
+The stack launcher streams the Ultravisor child process's output through Retold Remote's logger so you have a single log stream for both processes. Lines from the Ultravisor child are prefixed `[ultravisor]`, and stack-launcher events are prefixed `[stack]`:
+
+```
+[stack] launching ultravisor (port 54321)
+[stack]   data:    /Users/steven/.local/share/ultravisor/datastore
+[stack]   staging: /Users/steven/.local/share/ultravisor/staging
+[ultravisor] UltravisorTaskTypeRegistry: 53 built-in task types registered.
+[stack] ultravisor ready (after 1 attempts)
+==========================================================
+  Retold Remote running on http://localhost:7842
+==========================================================
+  Content: /mnt/nas/media
+  Cache:   /Users/steven/.cache/retold-remote
+  Browse:  http://localhost:7842/
+  Beacon:  registered with Ultravisor at http://localhost:54321
+  Stack:   ultravisor + retold-remote (orator-conversion embedded)
+==========================================================
+```
+
+If you also pass `-l <path>`, both streams are written to the file as well.
+
+## Shutdown
+
+Press `Ctrl+C` once. The launcher will:
+
+1. Log `Shutting down...`
+2. Disconnect the Ultravisor beacon (so Ultravisor knows the worker is leaving cleanly)
+3. Send `SIGTERM` to the Ultravisor child process
+4. Wait up to 1 second for graceful exit
+5. Send `SIGKILL` if it has not exited
+6. Exit the main process
+
+If the launcher reused an already-running Ultravisor (rather than spawning one), it will not kill that Ultravisor — it only manages processes it started itself.
+
+## Architecture
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  retold-stack /mnt/media                                    │
+│                                                             │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │ Main process (retold-remote)                         │  │
+│  │  ┌───────────────────────────────────────────────┐  │  │
+│  │  │ Orator HTTP server (port 7000-7999)           │  │  │
+│  │  │  ├─ Retold Remote routes (/api/media/...)     │  │  │
+│  │  │  ├─ Orator-Conversion (/api/conversion/1.0/)  │  │  │
+│  │  │  └─ Static web app (/)                        │  │  │
+│  │  └───────────────────────────────────────────────┘  │  │
+│  │  ┌───────────────────────────────────────────────┐  │  │
+│  │  │ Ultravisor Beacon client                      │  │  │
+│  │  │  └─ Connects to localhost:54321               │  │  │
+│  │  └───────────────────────────────────────────────┘  │  │
+│  └─────────────────────────────────────────────────────┘  │
+│                          ▲                                  │
+│                          │ HTTP                             │
+│                          ▼                                  │
+│  ┌─────────────────────────────────────────────────────┐  │
+│  │ Child process (ultravisor)                           │  │
+│  │  ├─ Coordinator API (port 54321)                     │  │
+│  │  ├─ Beacon registry                                  │  │
+│  │  ├─ Work queue journal                               │  │
+│  │  └─ Web interface                                    │  │
+│  │  Datastore: ~/.local/share/ultravisor/datastore/     │  │
+│  └─────────────────────────────────────────────────────┘  │
+└────────────────────────────────────────────────────────────┘
+```
+
+## Why Stack Mode?
+
+Use `--stack` when you want a single command that brings up the full Retold experience:
+
+- **Heavy media processing offloaded** through the Ultravisor beacon (video frame extraction, audio waveforms, ebook conversion, PDF page rendering)
+- **Document conversion** via the embedded Orator-Conversion service (with the `doc-to-pdf` converter for Word, RTF, ODT, WordPerfect, etc.)
+- **Persistent state** across launches (the Ultravisor datastore lives at a stable XDG location)
+- **No port juggling** — Ultravisor on its standard port 54321, Retold Remote on a random high port
+
+Use the bare `retold-remote serve` command (without `--stack`) when you just want a quick gallery browser without the coordinator infrastructure.
+
+## Comparison
+
+| Feature | `retold-remote serve` | `retold-stack` |
+|---------|----------------------|----------------|
+| Gallery browser | ✓ | ✓ |
+| Image/video/audio viewers | ✓ | ✓ |
+| Document conversion (doc, rtf, etc.) | Embedded only | Embedded + dispatched |
+| Heavy work offloading | No | Yes (via Ultravisor) |
+| Spawns child processes | No | Yes (Ultravisor) |
+| Default cache location | `./dist/retold-cache/` | `~/.cache/retold-remote/` |
+| Survives `cd` | Yes | Yes (XDG paths are absolute) |
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `Could not locate the ultravisor package` | Run `npm install ultravisor` (or `npm install -g retold-remote` to get the bundled version) |
+| `Ultravisor did not become ready within 30000ms` | Check the `[ultravisor]` log lines for an error. Common causes: port 54321 already bound by another process, missing dependencies, or invalid datastore path permissions |
+| Stack mode hangs at `launching ultravisor` | Ultravisor's child process may be waiting on stdin or hitting an interactive prompt. Run with `-l <path>` to capture full logs |
+| Beacon shows "not connected" | Ultravisor came up but the beacon registration failed. Check the Ultravisor child logs for errors and verify nothing is firewalling localhost:54321 |
+| Want to override XDG paths | Set `XDG_DATA_HOME`, `XDG_CACHE_HOME`, or `XDG_CONFIG_HOME` in your environment before launching, or use the `-c` flag for the Retold Remote cache |

package/web-application/docs/ultravisor-integration.md

@@ -2,6 +2,8 @@
 
 retold-remote can offload heavy media processing to a remote machine running an Ultravisor beacon worker. This is useful when the server (e.g. a NAS) has limited CPU and RAM but needs to process large video files, raw camera images, audio waveforms, and ebook conversions.
 
+> **Tip:** If you just want to run Ultravisor and Retold Remote together on the same machine without configuring anything, use the [Stack Launcher](stack-launcher.md) — `retold-stack /path/to/media` spawns Ultravisor as a child process automatically with sane XDG-style data paths. This page covers the case where Ultravisor runs on a *different* machine.
+
 ## How It Works
 
 When configured, retold-remote dispatches shell commands (ffmpeg, ffprobe, dcraw, ImageMagick, audiowaveform, ebook-convert) to a beacon worker via HTTP instead of running them locally. The beacon downloads the source file from retold-remote's content API, executes the command, and returns the result as base64-encoded data.