Add quantui run app and quantui setup CLI launchers

docs/CLI.md

@@ -9,30 +9,121 @@ command is on your `PATH`.
 quantui --help
 ```
 
-The CLI is meant to *complement* the Voilà app — not replace it. Reach
-for the CLI when you want to:
+The CLI is meant to *complement* the Voilà app. Most commands are
+read-only diagnostics against `~/.quantui/` (or whatever
+`QUANTUI_LOG_DIR` points at). The exception is **`quantui run app`**
+and **`quantui setup`**, which start (or prepare) the student-facing
+Voilà interface.
 
+Reach for the CLI when you want to:
+
+- **launch the app** without remembering Voilà flags or notebook paths
 - check what the app has been doing without opening a notebook
 - confirm GPU offload is wired correctly before starting a long run
 - generate a usage / GPU-speedup report you can share or pin to a tab
 - script log inspection or analytics into a shell pipeline / cron job
 
-The CLI never touches your live calculations or notebook server. All
-commands are read-only against `~/.quantui/` (or whatever
-`QUANTUI_LOG_DIR` points at).
-
 ---
 
 ## Command reference
 
 | Command | What it does |
 | --- | --- |
+| [`quantui run app`](#quantui-run-app) | Start the Voilà student app |
+| [`quantui setup`](#quantui-setup) | Write `~/.quantui/app.ipynb` and a `quantui-app` shell shortcut |
 | [`quantui log tail`](#quantui-log-tail) | Print recent events from `event_log.jsonl` |
 | [`quantui gpu check`](#quantui-gpu-check) | Probe GPU-offload availability and explain failures |
 | [`quantui analytics build`](#quantui-analytics-build) | Build an HTML usage dashboard from `perf_log.jsonl` |
 
 ---
 
+## `quantui run app`
+
+Start the student-facing Voilà interface. On first use (or after
+`quantui setup`), the CLI writes a thin launcher notebook to
+`~/.quantui/app.ipynb` — the same three-line pattern as the repo's
+`notebooks/molecule_computations.ipynb`, without requiring a git clone.
+
+Requires the **`[app]` extra**:
+
+```bash
+pip install 'quantui[app]'
+quantui run app
+```
+
+### Flags
+
+| Flag | Default | Description |
+| --- | --- | --- |
+| `--port PORT` | `8867` | TCP port (matches the native `launchers/` scripts) |
+| `--open` | off | Open `http://localhost:PORT` in the default browser after startup |
+| `--force` | off | Regenerate `~/.quantui/app.ipynb` before starting |
+
+### Examples
+
+```bash
+# Default — prints the URL, runs until Ctrl-C
+quantui run app
+
+# Open the browser automatically (WSL-aware)
+quantui run app --open
+
+# Custom port
+quantui run app --port 8888
+```
+
+### Notes
+
+- Exit code `1` when Voilà is not installed — install `quantui[app]`
+  and ensure `voila` is on your `PATH`.
+- Exit code `1` in **Apptainer + JupyterLab** sessions (NCShare and
+  similar HPC portals) — use `quantui setup` and launch from JupyterLab
+  instead; see [`quantui setup`](#ncshare--hpc-jupyterlab).
+- Override the config directory with `QUANTUI_HOME` (useful in tests).
+
+---
+
+## `quantui setup`
+
+One-time (or idempotent) provisioning for users who want a persistent
+shell shortcut:
+
+1. Writes `~/.quantui/app.ipynb` (same as `quantui run app` uses)
+2. Writes `~/.local/bin/quantui-app` (or `$XDG_BIN_HOME/quantui-app`)
+
+```bash
+quantui setup
+quantui-app          # after ~/.local/bin is on PATH
+```
+
+Pass `--force` to overwrite an existing notebook or script.
+
+### NCShare / HPC JupyterLab
+
+On cluster portals that launch QuantUI inside **Apptainer + JupyterLab**
+(NCShare is the primary example), the browser proxies only the Jupyter
+connection. A standalone Voilà server on port 8867 is **not reachable**.
+
+When the CLI detects that environment (Apptainer + Jupyter server env
+vars), `quantui setup` also writes **`~/QuantUI.ipynb`** — visible in the
+JupyterLab file browser — and prints NCShare-specific launch instructions
+instead of the usual `quantui run app` guidance.
+
+Launch QuantUI from JupyterLab:
+
+1. Open **`~/QuantUI.ipynb`** and click **Render with Voilà** (clean
+   student view), or
+2. Run the one-liner in any notebook:
+   ```python
+   from quantui.app import QuantUIApp
+   QuantUIApp().display()
+   ```
+
+`quantui run app` exits with code `1` in this context and explains the
+above — do not use it for browser access on NCShare.
+
+---
+
 ## `quantui log tail`
 
 Print the last *N* entries from the QuantUI event log
@@ -249,6 +340,8 @@ successfully; only the auto-open is best-effort.
 
 | Variable | Effect |
 | --- | --- |
+| `QUANTUI_HOME` | Override `~/.quantui/` for the generated launcher notebook (`app.ipynb`) and setup output. |
+| `XDG_BIN_HOME` | Override `~/.local/bin` as the destination for the `quantui-app` shell shortcut. |
 | `QUANTUI_LOG_DIR` | Override the default `~/.quantui/logs/` location. The dashboard's default output (`~/.quantui/dashboard.html`) follows: it lives one level up from the active `QUANTUI_LOG_DIR`. |
 | `QUANTUI_DISABLE_GPU` | Force CPU mode even when gpu4pyscf is installed. `quantui gpu check` reports this as the reason. Accepted truthy values: `1`, `true`, `True`. |
 | `QUANTUI_FREQ_PARALLEL` | Opt in to parallel **CPU** workers for the IR-intensity finite-difference loop in frequency calculations (`6N` displaced SCFs). Same effect as the **Parallelize IR intensity displacements** checkbox on the System Settings tab; when this env var is set it overrides the saved setting. Reference SCF and Hessian still use gpu4pyscf when available. Requires ≥4 cores and ≥2 atoms. Off by default. Accepted truthy values: `1`, `true`, `yes`, `on`. |
@@ -260,12 +353,21 @@ successfully; only the auto-open is best-effort.
 ### Verify GPU is wired before a long run
 
 ```bash
-quantui gpu check && voila notebooks/molecule_computations.ipynb
+quantui gpu check && quantui run app
 ```
 
-If `gpu check` exits non-zero, the Voilà launch is skipped and the
+If `gpu check` exits non-zero, the app launch is skipped and the
 reason was printed to stderr.
 
+### Launch the app (pip install, no git clone)
+
+```bash
+pip install 'quantui[app]'
+quantui run app
+# optional one-time shell shortcut:
+quantui setup
+```
+
 ### Quick "what happened in my last session?"
 
 ```bash