nds-mapviewer 2026.4.4.dev270__tar.gz → 2026.4.5.dev294__tar.gz

{nds_mapviewer-2026.4.4.dev270 → nds_mapviewer-2026.4.5.dev294}/CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Enable unauthenticated MCP through the launcher with `--mcp-local`, using
+  ordinary bind/network settings and the selected host port for discovery
+  (requires a supporting container image).
+- Set a public MCP URL with `--mcp-endpoint` for LAN access.
 - `--debug` flag to enable container debug logging (sets `HTTP_LOG_LEVEL=debug`)
 - `--env KEY=VALUE` (repeatable, short `-E`) to pass custom environment
   variables into the container; overrides `--debug` on key collision

{nds_mapviewer-2026.4.4.dev270/src/nds_mapviewer.egg-info → nds_mapviewer-2026.4.5.dev294}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nds-mapviewer
-Version: 2026.4.4.dev270
+Version: 2026.4.5.dev294
 Summary: CLI to run the NDS MapViewer Docker container for visualizing map data (NDS.Live, GeoJSON, and more)
 Author-email: NDS Association <support@nds-association.org>
 License: Proprietary
@@ -121,9 +121,55 @@ appear in the Docker screen's "Copy Command" output.
 
 `--network NAME` attaches the container to a specific network (e.g. a custom
 bridge or `host`). With `--network host` the container binds the host's port
-directly, so `--port`/`--bind` are ignored and the MapViewer is reached on its
-internal port (8089). Host networking behaves differently across platforms and
-runtimes — it is intended as a connectivity workaround.
+directly, so `--port` is ignored and the MapViewer is reached on its internal
+port (8089). With `--mcp-local`, `--bind` selects the native listener in this mode;
+otherwise it is ignored. Host networking behaves differently across platforms
+and runtimes — it is intended as a connectivity workaround.
+
+### Local MCP
+
+MCP requires **Member Edition**. Select `--edition member` and use `--mcp-local`
+with a supporting Member image. Community Edition does not provide MCP tools or
+browser-agent access. No peer addresses are needed; ordinary server networking applies:
+
+```bash
+mapviewer --edition member --demo --mcp-local --port 8099
+```
+
+Connect your MCP client to `http://localhost:8099/mcp` and open the viewer at
+`http://localhost:8099` for browser-control tools. Without `--port`, the endpoint
+uses the free port selected by the launcher, shown in the run screen. The Docker
+screen shows the generated native options in its copyable command.
+
+For LAN access, set the public URL explicitly so native MCP discovery and its
+default Host/Origin allowlists use the address seen by remote browsers. For
+example, replace `192.168.1.50` with your server's LAN address:
+
+```bash
+mapviewer --edition member --demo --mcp-local --bind 0.0.0.0 --port 8099 --no-browser \
+  --mcp-endpoint http://192.168.1.50:8099/mcp
+```
+
+Open `http://192.168.1.50:8099` and connect the MCP client to that URL plus `/mcp`.
+The override describes the public URL; it does not change the listener, enable
+TLS or change the launcher's ordinary localhost browser URL/readiness probe.
+`--mcp-endpoint` requires `--mcp-local`; the native server validates URL syntax.
+
+**Local MCP is unauthenticated. Everyone who can reach the server shares access
+to its enabled MCP tools.** The name `local` does not enforce loopback access.
+The ordinary `--bind` and `--network` settings control reachability: the default
+bind is `127.0.0.1`; `--bind 0.0.0.0` or the TUI's **Allow network access** checkbox
+exposes the published port on all host interfaces. Use firewall, container or
+proxy policy to limit access, or OAuth when authentication is required. See the
+[container setup](../docs/mv-mcp-workflows.md) and
+[native MCP documentation](../deps/mapget/docs/mapget-mcp.md).
+
+On hosts supporting host networking, `mapviewer --edition member --demo --network host --mcp-local`
+instead uses port 8089 directly and honors `--bind` for the native listener.
+The Python API accepts `edition="member"`, `mcp_local=True` and optional
+`mcp_endpoint="http://host:port/mcp"` arguments to `MapViewer`.
+
+### Local configuration
 
 If `~/.nds/config.yaml` exists, `mapviewer` (with no arguments) loads it
 automatically and goes straight to the RunScreen.
@@ -150,6 +196,9 @@ durable map-preset write target.
 | **community** | NDS.Live, GeoJSON, open formats | Free — [nds.live](https://nds.live) |
 | **member** | + NDS.Classic | [NDS membership](https://nds-association.org/#contact) |
 
+MCP server access, browser-agent tools and MCP tunnels are available only in
+Member Edition. Selecting Community with `--mcp-local` is rejected before launch.
+
 ## Open-Source Building Blocks
 
 - **[mapget](https://github.com/ndsev/mapget)** — tile-based map data server with caching

{nds_mapviewer-2026.4.4.dev270 → nds_mapviewer-2026.4.5.dev294}/README.md

@@ -88,9 +88,55 @@ appear in the Docker screen's "Copy Command" output.
 
 `--network NAME` attaches the container to a specific network (e.g. a custom
 bridge or `host`). With `--network host` the container binds the host's port
-directly, so `--port`/`--bind` are ignored and the MapViewer is reached on its
-internal port (8089). Host networking behaves differently across platforms and
-runtimes — it is intended as a connectivity workaround.
+directly, so `--port` is ignored and the MapViewer is reached on its internal
+port (8089). With `--mcp-local`, `--bind` selects the native listener in this mode;
+otherwise it is ignored. Host networking behaves differently across platforms
+and runtimes — it is intended as a connectivity workaround.
+
+### Local MCP
+
+MCP requires **Member Edition**. Select `--edition member` and use `--mcp-local`
+with a supporting Member image. Community Edition does not provide MCP tools or
+browser-agent access. No peer addresses are needed; ordinary server networking applies:
+
+```bash
+mapviewer --edition member --demo --mcp-local --port 8099
+```
+
+Connect your MCP client to `http://localhost:8099/mcp` and open the viewer at
+`http://localhost:8099` for browser-control tools. Without `--port`, the endpoint
+uses the free port selected by the launcher, shown in the run screen. The Docker
+screen shows the generated native options in its copyable command.
+
+For LAN access, set the public URL explicitly so native MCP discovery and its
+default Host/Origin allowlists use the address seen by remote browsers. For
+example, replace `192.168.1.50` with your server's LAN address:
+
+```bash
+mapviewer --edition member --demo --mcp-local --bind 0.0.0.0 --port 8099 --no-browser \
+  --mcp-endpoint http://192.168.1.50:8099/mcp
+```
+
+Open `http://192.168.1.50:8099` and connect the MCP client to that URL plus `/mcp`.
+The override describes the public URL; it does not change the listener, enable
+TLS or change the launcher's ordinary localhost browser URL/readiness probe.
+`--mcp-endpoint` requires `--mcp-local`; the native server validates URL syntax.
+
+**Local MCP is unauthenticated. Everyone who can reach the server shares access
+to its enabled MCP tools.** The name `local` does not enforce loopback access.
+The ordinary `--bind` and `--network` settings control reachability: the default
+bind is `127.0.0.1`; `--bind 0.0.0.0` or the TUI's **Allow network access** checkbox
+exposes the published port on all host interfaces. Use firewall, container or
+proxy policy to limit access, or OAuth when authentication is required. See the
+[container setup](../docs/mv-mcp-workflows.md) and
+[native MCP documentation](../deps/mapget/docs/mapget-mcp.md).
+
+On hosts supporting host networking, `mapviewer --edition member --demo --network host --mcp-local`
+instead uses port 8089 directly and honors `--bind` for the native listener.
+The Python API accepts `edition="member"`, `mcp_local=True` and optional
+`mcp_endpoint="http://host:port/mcp"` arguments to `MapViewer`.
+
+### Local configuration
 
 If `~/.nds/config.yaml` exists, `mapviewer` (with no arguments) loads it
 automatically and goes straight to the RunScreen.
@@ -117,6 +163,9 @@ durable map-preset write target.
 | **community** | NDS.Live, GeoJSON, open formats | Free — [nds.live](https://nds.live) |
 | **member** | + NDS.Classic | [NDS membership](https://nds-association.org/#contact) |
 
+MCP server access, browser-agent tools and MCP tunnels are available only in
+Member Edition. Selecting Community with `--mcp-local` is rejected before launch.
+
 ## Open-Source Building Blocks
 
 - **[mapget](https://github.com/ndsev/mapget)** — tile-based map data server with caching

{nds_mapviewer-2026.4.4.dev270 → nds_mapviewer-2026.4.5.dev294/src/nds_mapviewer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nds-mapviewer
-Version: 2026.4.4.dev270
+Version: 2026.4.5.dev294
 Summary: CLI to run the NDS MapViewer Docker container for visualizing map data (NDS.Live, GeoJSON, and more)
 Author-email: NDS Association <support@nds-association.org>
 License: Proprietary
@@ -121,9 +121,55 @@ appear in the Docker screen's "Copy Command" output.
 
 `--network NAME` attaches the container to a specific network (e.g. a custom
 bridge or `host`). With `--network host` the container binds the host's port
-directly, so `--port`/`--bind` are ignored and the MapViewer is reached on its
-internal port (8089). Host networking behaves differently across platforms and
-runtimes — it is intended as a connectivity workaround.
+directly, so `--port` is ignored and the MapViewer is reached on its internal
+port (8089). With `--mcp-local`, `--bind` selects the native listener in this mode;
+otherwise it is ignored. Host networking behaves differently across platforms
+and runtimes — it is intended as a connectivity workaround.
+
+### Local MCP
+
+MCP requires **Member Edition**. Select `--edition member` and use `--mcp-local`
+with a supporting Member image. Community Edition does not provide MCP tools or
+browser-agent access. No peer addresses are needed; ordinary server networking applies:
+
+```bash
+mapviewer --edition member --demo --mcp-local --port 8099
+```
+
+Connect your MCP client to `http://localhost:8099/mcp` and open the viewer at
+`http://localhost:8099` for browser-control tools. Without `--port`, the endpoint
+uses the free port selected by the launcher, shown in the run screen. The Docker
+screen shows the generated native options in its copyable command.
+
+For LAN access, set the public URL explicitly so native MCP discovery and its
+default Host/Origin allowlists use the address seen by remote browsers. For
+example, replace `192.168.1.50` with your server's LAN address:
+
+```bash
+mapviewer --edition member --demo --mcp-local --bind 0.0.0.0 --port 8099 --no-browser \
+  --mcp-endpoint http://192.168.1.50:8099/mcp
+```
+
+Open `http://192.168.1.50:8099` and connect the MCP client to that URL plus `/mcp`.
+The override describes the public URL; it does not change the listener, enable
+TLS or change the launcher's ordinary localhost browser URL/readiness probe.
+`--mcp-endpoint` requires `--mcp-local`; the native server validates URL syntax.
+
+**Local MCP is unauthenticated. Everyone who can reach the server shares access
+to its enabled MCP tools.** The name `local` does not enforce loopback access.
+The ordinary `--bind` and `--network` settings control reachability: the default
+bind is `127.0.0.1`; `--bind 0.0.0.0` or the TUI's **Allow network access** checkbox
+exposes the published port on all host interfaces. Use firewall, container or
+proxy policy to limit access, or OAuth when authentication is required. See the
+[container setup](../docs/mv-mcp-workflows.md) and
+[native MCP documentation](../deps/mapget/docs/mapget-mcp.md).
+
+On hosts supporting host networking, `mapviewer --edition member --demo --network host --mcp-local`
+instead uses port 8089 directly and honors `--bind` for the native listener.
+The Python API accepts `edition="member"`, `mcp_local=True` and optional
+`mcp_endpoint="http://host:port/mcp"` arguments to `MapViewer`.
+
+### Local configuration
 
 If `~/.nds/config.yaml` exists, `mapviewer` (with no arguments) loads it
 automatically and goes straight to the RunScreen.
@@ -150,6 +196,9 @@ durable map-preset write target.
 | **community** | NDS.Live, GeoJSON, open formats | Free — [nds.live](https://nds.live) |
 | **member** | + NDS.Classic | [NDS membership](https://nds-association.org/#contact) |
 
+MCP server access, browser-agent tools and MCP tunnels are available only in
+Member Edition. Selecting Community with `--mcp-local` is rejected before launch.
+
 ## Open-Source Building Blocks
 
 - **[mapget](https://github.com/ndsev/mapget)** — tile-based map data server with caching

{nds_mapviewer-2026.4.4.dev270 → nds_mapviewer-2026.4.5.dev294}/src/ndslive/mapviewer/browser.py

@@ -97,7 +97,10 @@ def is_playwright_available() -> bool:
 
 
 def is_playwright_chromium_installed() -> bool:
-    """Check if playwright's Chromium browser is installed."""
+    """Check whether Playwright exposes a Chromium executable path.
+
+    This probe does not check that the file exists or that Chromium can launch.
+    """
     if not is_playwright_available():
         return False
 
@@ -135,13 +138,19 @@ def open_browser(
     """
     Open a URL in a web browser.
 
+    Bundled Chromium blocks until the user presses Enter and is then closed.
+    System-browser launches return immediately; they do not verify that the
+    page loaded. Missing Playwright or a failed browser-path probe raises before
+    launch, while errors during launch/navigation return False.
+
     Args:
         url: The URL to open
         use_bundled: Use playwright's bundled Chromium
         prefer_chromium: Prefer Chromium-based browsers for best performance
 
     Returns:
-        True if the browser was opened successfully
+        True if the launch path completed without an exception. The default
+        browser's own boolean result is not checked.
     """
     # Option 1: Use bundled Chromium via playwright
     if use_bundled:
@@ -152,7 +161,7 @@ def open_browser(
             )
 
         if not is_playwright_chromium_installed():
-            # Prompt user or auto-install
+            # Installation remains an explicit caller/user action.
             raise RuntimeError(
                 "Playwright Chromium is not installed. Install with:\n"
                 "  playwright install chromium"
@@ -164,7 +173,7 @@ def open_browser(
                 browser = p.chromium.launch(headless=False)
                 page = browser.new_page()
                 page.goto(url)
-                # Keep browser open - user closes manually
+                    # Keep the browser open until the user presses Enter.
                 input("Press Enter to close the browser...")
                 browser.close()
             return True

{nds_mapviewer-2026.4.4.dev270 → nds_mapviewer-2026.4.5.dev294}/src/ndslive/mapviewer/cli.py

@@ -28,7 +28,7 @@ def _build_run_subtitle(edition: str, image_version_raw: str | None) -> str:
 
 
 def _stop_existing_container() -> None:
-    """Stop the current MapViewer container if it is running."""
+    """Stop and remove the default MapViewer container if it exists."""
     from .viewer import MapViewer
     from .exceptions import ContainerNotFound
 
@@ -40,7 +40,7 @@ def _stop_existing_container() -> None:
 
 
 def _get_edition_default() -> str:
-    """Read edition from ndslive-setup config, or detect member access, fallback to community."""
+    """Use the edition saved by ndslive-setup, then local member credentials, else community."""
     setup_config = Path.home() / ".nds" / "setup.json"
     if setup_config.exists():
         import json
@@ -109,7 +109,14 @@ def _build_environment(args: argparse.Namespace) -> dict[str, str]:
 # ---------------------------------------------------------------------------
 
 def cmd_main(args: argparse.Namespace) -> int:
-    """Unified handler: sources → resolve & launch, no sources → HomeScreen."""
+    """Resolve launch inputs and run the corresponding TUI until it exits.
+
+    Demo mode takes precedence. Without explicit sources, try the default then
+    legacy config before showing HomeScreen. Explicit inputs combine their
+    sources and HTTP settings; retain a config path for live reload only when
+    the sole input is a YAML config. Return 1 for source resolution errors and
+    2 for incompatible MCP flags.
+    """
     from .config import (
         load_config,
         resolve_config_source,
@@ -133,6 +140,14 @@ def cmd_main(args: argparse.Namespace) -> int:
     source_args = args.sources
     environment = _build_environment(args)
     network = getattr(args, "network", None)
+    mcp_local = args.mcp_local
+    mcp_endpoint = args.mcp_endpoint
+    if mcp_endpoint is not None and not mcp_local:
+        console.print("[red]Error:[/red] --mcp-endpoint requires --mcp-local.")
+        return 2
+    if mcp_local and edition != "member":
+        console.print("[red]Error:[/red] MCP requires MapViewer Member Edition. Select --edition member.")
+        return 2
 
     # --demo → demo config
     if args.demo:
@@ -146,6 +161,8 @@ def cmd_main(args: argparse.Namespace) -> int:
             pull_policy=pull_policy,
             environment=environment,
             network=network,
+            mcp_local=mcp_local,
+            mcp_endpoint=mcp_endpoint,
             run_config=config,
             run_label="Demo (NDS Islands)",
             is_demo=True,
@@ -168,6 +185,8 @@ def cmd_main(args: argparse.Namespace) -> int:
                     pull_policy=pull_policy,
                     environment=environment,
                     network=network,
+                    mcp_local=mcp_local,
+                    mcp_endpoint=mcp_endpoint,
                     run_config=config,
                     run_config_path=DEFAULT_CONFIG,
                     run_label="~/.nds/config.yaml",
@@ -193,6 +212,8 @@ def cmd_main(args: argparse.Namespace) -> int:
                     pull_policy=pull_policy,
                     environment=environment,
                     network=network,
+                    mcp_local=mcp_local,
+                    mcp_endpoint=mcp_endpoint,
                     run_config=config,
                     run_config_path=LEGACY_CONFIG,
                     run_label="~/.nds/mapviewer.yaml",
@@ -211,6 +232,8 @@ def cmd_main(args: argparse.Namespace) -> int:
             pull_policy=pull_policy,
             environment=environment,
             network=network,
+            mcp_local=mcp_local,
+            mcp_endpoint=mcp_endpoint,
         )
         app.run()
         return 0
@@ -306,6 +329,8 @@ def cmd_main(args: argparse.Namespace) -> int:
         pull_policy=pull_policy,
         environment=environment,
         network=network,
+        mcp_local=mcp_local,
+        mcp_endpoint=mcp_endpoint,
         run_config=merged,
         run_config_path=source_config_path,
         run_label=source_desc,
@@ -411,8 +436,20 @@ Examples:
         "--network",
         metavar="NAME",
         default=None,
-        help="Container network to attach (e.g. 'host'). With 'host' the "
-             "MapViewer binds the host port directly and --port/--bind are ignored.",
+        help="Container network to attach (e.g. 'host'). With 'host', --port is "
+             "ignored (8089 is used); with --mcp-local, --bind selects the native listener.",
+    )
+    parser.add_argument(
+        "--mcp-local",
+        action="store_true",
+        help="Enable Member Edition's unauthenticated MCP with one shared user. Anyone who can "
+             "reach the server can use its enabled MCP tools; normal --bind/--network settings apply.",
+    )
+    parser.add_argument(
+        "--mcp-endpoint",
+        metavar="URL",
+        help="Public MCP URL ending in /mcp (requires --mcp-local). Defaults to the "
+             "local launcher URL; set it for LAN/public browser access. Does not change the bind address.",
     )
 
     pull_group = parser.add_mutually_exclusive_group()

{nds_mapviewer-2026.4.4.dev270 → nds_mapviewer-2026.4.5.dev294}/src/ndslive/mapviewer/clipboard.py

@@ -4,7 +4,7 @@ Textual's ``App.copy_to_clipboard`` relies on the OSC 52 terminal escape
 sequence, which many Windows terminals (conhost, some Windows Terminal
 configs, PowerShell hosts) silently drop — so the copy buttons appear to do
 nothing.  This module copies via the native OS clipboard utility first and
-only falls back to OSC 52 when no native tool is available.
+falls back to OSC 52 when native copying is unavailable or fails.
 """
 
 from __future__ import annotations
@@ -65,8 +65,8 @@ def copy_text(text: str, app=None) -> bool:
     """Copy *text* to the clipboard, returning True on confirmed success.
 
     Tries the native OS clipboard utility first (reliable on Windows where
-    OSC 52 is commonly unsupported).  If no native tool is available and an
-    *app* is given, falls back to Textual's OSC 52 escape — which cannot be
+    OSC 52 is commonly unsupported). If native copying fails and an *app* is
+    given, falls back to Textual's OSC 52 escape — which cannot be
     confirmed, so this returns False to let callers warn the user.
     """
     if _native_copy(text):

{nds_mapviewer-2026.4.4.dev270 → nds_mapviewer-2026.4.5.dev294}/src/ndslive/mapviewer/config.py

@@ -286,6 +286,15 @@ def transform_config(
     - Rewrites paths to use container mount points
     - Transforms localhost references to host.docker.internal
     - Rewrites CLI-managed erdblick asset paths to static container paths
+
+    The input is deep-copied. ``base_dir`` resolves relative browser assets;
+    local datasource URIs must already contain absolute paths. ``existing_volumes``
+    reserves the original container paths during hot reload, including mounts no
+    longer referenced. The returned plan may require new mounts: the caller must
+    check it against the running container before publishing a reload.
+
+    ``ephemeral`` marks generated configs so browser preset edits are not offered
+    as durable writes to a temporary launcher-owned file.
     """
     import copy
 
@@ -306,6 +315,7 @@ def transform_config(
     assigned_by_host: dict[tuple[Path, str], str] = dict(existing_by_host)
 
     def existing_container_path(host_path: Path, root: str) -> str | None:
+        """Reuse a host mapping only within its data/style/background mount category."""
         container_path = assigned_by_host.get((host_path.expanduser().resolve(), root))
         if container_path == root or (
             container_path is not None
@@ -315,6 +325,7 @@ def transform_config(
         return None
 
     def next_container_path(root: str, preferred: str) -> str:
+        """Reserve an unused target without displacing mounts from an earlier config."""
         candidate = preferred
         if candidate not in used_container_paths:
             used_container_paths.add(candidate)
@@ -329,12 +340,14 @@ def transform_config(
             index += 1
 
     def assign_volume(host_path: Path, root: str, preferred: str) -> str:
+        """Assign one stable destination per canonical host path and mount category."""
         host_path = host_path.expanduser().resolve()
         container_path = existing_container_path(host_path, root)
         if container_path is None:
             container_path = next_container_path(root, preferred)
         assigned_by_host[(host_path, root)] = container_path
         return container_path
+
     local_paths: list[Path] = []
     path_locations: list[tuple[str, int, str, str]] = []  # (section, index, field, original)
 
@@ -430,6 +443,7 @@ def transform_config(
     asset_volume_keys: set[tuple[Path, str]] = set()
 
     def add_asset_volume(host_path: Path, root: str, preferred: str) -> str:
+        """Deduplicate browser assets while sharing the launcher's target allocation."""
         resolved_host_path = host_path.expanduser().resolve()
         container_path = assign_volume(resolved_host_path, root, preferred)
         key = (resolved_host_path, container_path)
@@ -444,6 +458,7 @@ def transform_config(
     background_asset_index = 0
 
     def transform_additional_style_url(url: str) -> str:
+        """Mount local style files or wildcard directories and preserve remote URLs."""
         nonlocal style_asset_index
         url = url.strip()
         if (
@@ -473,6 +488,7 @@ def transform_config(
         return container_path
 
     def transform_background_template(template: str) -> str:
+        """Mount the fixed directory prefix and keep XYZ placeholders in the URL suffix."""
         nonlocal background_asset_index
         template = template.strip()
         if (
@@ -569,8 +585,13 @@ def validate_paths(
     base_dir: str | Path | None = None,
 ) -> list[str]:
     """
-    Validate that all local paths in the config exist.
-    Returns a list of error messages for missing paths.
+    Validate that supported datasource paths and CLI-managed erdblick assets exist.
+
+    Source URI/folder paths use the working directory for relative paths;
+    erdblick assets use ``base_dir``. External/browser asset URLs are skipped,
+    and XYZ templates require only their static root directory to exist.
+    Return accumulated path/extension errors; this does not validate the full
+    configuration schema or the contents of asset files.
     """
     errors = []
     sources = config.get("sources", [])
@@ -831,6 +852,10 @@ def create_service_config(
 ) -> dict[str, Any]:
     """Create a config dict for connecting to a remote service.
 
+    HTTP settings apply to all paths on the URL's origin. Only the selected
+    authentication method is emitted, and incomplete credentials omit that
+    method rather than raising. Proxy settings are independent of authentication.
+
     Args:
         url: Service URL (e.g., https://api.example.com/openapi.json)
         service_type: SmartLayer datasource type, see ``detect_service_type``
@@ -941,7 +966,7 @@ def resolve_config_source(arg: str) -> ResolvedConfig | None:
     """Resolve a CLI argument to a config source.
 
     Resolution order:
-    1. If arg is an absolute path or starts with ./ → treat as local path
+    1. If arg starts with /, ./ or ../ → resolve only as a local path
     2. If arg exists as local file/folder → use it
     3. If ~/.nds/configs/<arg>.yaml exists → use saved config
     4. Return None if not found
@@ -1024,7 +1049,7 @@ def resolve_config_source(arg: str) -> ResolvedConfig | None:
 
 
 def save_config(config: dict[str, Any], name: str) -> Path:
-    """Save a config to the workspace directory.
+    """Write a named YAML config under ``~/.nds/configs``, replacing its contents.
 
     Args:
         config: Config dict to save

{nds_mapviewer-2026.4.4.dev270 → nds_mapviewer-2026.4.5.dev294}/src/ndslive/mapviewer/container_runtime.py

@@ -71,10 +71,14 @@ def detect_runtime() -> str:
 
     1. Saved ``runtime_name`` in ``~/.nds/setup.json`` (written by ``ndslive-setup``).
     2. ``CONTAINER_RUNTIME`` environment variable (``docker`` or ``podman``).
-    3. ``docker`` on ``$PATH``.
-    4. ``podman`` on ``$PATH``.
-
-    Raises :class:`FileNotFoundError` when no runtime is found.
+    3. A responsive installed runtime, checking Docker before Podman.
+    4. The first installed runtime when neither responds, so the caller can
+       diagnose a stopped service instead of reporting a missing installation.
+
+    Saved and environment choices must exist on ``PATH`` but are not probed here.
+    An unavailable saved choice falls through; an unavailable explicit environment
+    choice raises :class:`FileNotFoundError`, as does finding no runtime at all.
+    The result is cached for this process.
     """
     saved = _saved_runtime_preference()
     if saved and _runtime_exists(saved):
@@ -160,8 +164,10 @@ def stream(
 ) -> subprocess.Popen[str]:
     """Start a long-running runtime command for line-by-line streaming.
 
-    The caller is responsible for reading ``proc.stdout`` and
-    eventually calling ``proc.terminate()`` / ``proc.wait()``.
+    The caller must read ``proc.stdout`` and eventually call ``proc.terminate()``
+    and/or ``proc.wait()``. With separate stderr, also read ``proc.stderr`` to
+    avoid blocking a verbose subprocess; otherwise request combined output
+    with ``merge_stderr``.
 
     Parameters
     ----------