Mkdocs

.github/workflows/mkdocs.yml

@@ -0,0 +1,56 @@
+# Build MkDocs and publish to GitHub Pages.
+# Repo Settings → Pages → Build and deployment: Source = "GitHub Actions".
+#
+# You can list any branch(es) below. A push to any of them deploys to the same
+# site URL for this repo (the latest successful run wins). For docs-only testing,
+# use e.g. only `mkdocs`; for production after merge, use only `main` or both.
+
+name: Publish docs
+
+on:
+  push:
+    branches:
+      - main
+      - mkdocs
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install MkDocs
+        run: pip install -r requirements-docs.txt
+
+      - name: Build site
+        run: mkdocs build --strict
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

README.md

@@ -54,7 +54,7 @@ With **LITTLE JOHN**, ROBIN can run two PromethION flow cells simultaneously on
 
 Use **conda** so native and Python dependencies stay consistent. Create the environment from **`robin.yml`** (Python 3.12); older Python 3.9-era env files are removed.
 
-For a step-by-step walkthrough, see [`docs/installation_guide.md`](docs/installation_guide.md).
+For a step-by-step walkthrough, see [`docs/getting-started/installation.md`](docs/getting-started/installation.md).
 
 ### Prerequisites
 
@@ -130,7 +130,7 @@ For a step-by-step walkthrough, see [`docs/installation_guide.md`](docs/installa
 
 After any of these, run **`pip install -e .`** again from the repository root with the env you intend to use.
 
-More detail: [`docs/installation_guide.md` → If the `robin` environment already exists](docs/installation_guide.md#if-the-robin-environment-already-exists).
+More detail: [`docs/getting-started/installation.md` → If the `robin` environment already exists](docs/getting-started/installation.md#if-the-robin-environment-already-exists).
 
 ---
 

docs/cli/index.md

@@ -0,0 +1,39 @@
+# Command-line reference
+
+ROBIN exposes a **`robin`** CLI (Click). This section documents each command group. For a first run, see [Installation](../getting-started/installation.md) and [Quickstart](../getting-started/quickstart.md).
+
+## Command tree
+
+| Command | Purpose |
+|---------|---------|
+| [`robin workflow`](workflow.md) | Watch a directory of BAMs and run the selected analysis pipeline (Ray, NiceGUI optional). |
+| [`robin list-job-types`](jobs.md) | Print job types and queue layout. |
+| [`robin list-panels`](panels.md) / [`add-panel`](panels.md#robin-add-panel) / [`remove-panel`](panels.md#robin-remove-panel) | Manage target gene panels. |
+| [`robin utils …`](utils.md) | Models, ClinVar, reference/panel staging, MGMT summaries. |
+| [`robin password …`](password.md) | Set the NiceGUI login password. |
+
+Run **`robin --help`** and **`robin <command> --help`** for the exact options shipped with your install.
+
+## Disclaimer prompt
+
+Many commands that change state or start processing show a **disclaimer** and require you to type **`I agree`** exactly (research-use acknowledgment).
+
+## Environment variables (selected)
+
+| Variable | Effect |
+|----------|--------|
+| `GITHUB_TOKEN` | Used by `robin utils update-models` when assets are fetched from private GitHub. |
+| `ROBIN_PROCESS_LARGE_BAMS` | If enabled, warns that large-BAM mode must not be used alongside live runs. |
+| `LJ_BAM_THREADS` | Optional tuning for multi-threaded BAM handling (see [README — Performance](https://github.com/LooseLab/littlejohn/blob/main/README.md#performance)). |
+
+## First-time startup experience
+
+When you run **`robin workflow`**, ROBIN performs model checks, optional reference validation, the **research disclaimer** (`I agree`), and (if the GUI is enabled) **GUI password** prompts. See **[What happens at startup](../getting-started/startup.md)**.
+
+## Web interface
+
+For a **browser user guide** (navigation, each screen, reading results), see **[Using ROBIN](../using-robin/index.md)**.
+
+## See also
+
+- [README — Command reference](https://github.com/LooseLab/littlejohn/blob/main/README.md#command-reference) (repo mirror of common invocations)

docs/cli/jobs.md

@@ -0,0 +1,60 @@
+# `robin list-job-types` and job model
+
+`robin list-job-types` prints the **job types** ROBIN knows about, grouped by **queue**. Understanding this helps you build `-w` / `--workflow` strings for [`robin workflow`](workflow.md).
+
+## Command
+
+```bash
+robin list-job-types
+```
+
+You must complete the **disclaimer** (`I agree`).
+
+## Queues and job types
+
+The orchestration layer assigns each job type to a queue (simplified names here; internal Ray queue names may differ slightly):
+
+| Queue (concept) | Job types | Role |
+|-----------------|-----------|------|
+| **Preprocessing** | `preprocessing` | Read BAM headers/metadata; entry point for each new file. |
+| **BED conversion** | `bed_conversion` | Prepare inputs for classifiers that need BED-level views. |
+| **Analysis** | `mgmt`, `cnv`, `target`, `fusion` | Methylation (MGMT), copy number, targeted variant/fusion panels. |
+| **Classification** | `sturgeon`, `nanodx`, `pannanodx` | Methylation / expression classifiers. |
+| **Slow** | `random_forest` | Heavier or batched models. |
+
+## Automatic steps
+
+When you use the **simplified** workflow format (`-w mgmt,sturgeon`, …):
+
+1. **`preprocessing`** is prepended if you did not list it.
+2. **`bed_conversion`** is inserted when any of **`sturgeon`**, **`nanodx`**, **`pannanodx`**, or **`random_forest`** appear — those jobs expect BED conversion upstream.
+
+You do not need to list `bed_conversion` manually for those classifiers unless you are hand-editing **legacy** queue-prefixed pipelines.
+
+## Valid job type names
+
+The CLI accepts only these **job** identifiers in workflow strings:
+
+`preprocessing`, `bed_conversion`, `mgmt`, `cnv`, `target`, `fusion`, `sturgeon`, `nanodx`, `pannanodx`, `random_forest`
+
+Unknown names produce warnings and are skipped.
+
+## Examples
+
+```bash
+# Minimal classifier run (preprocessing + bed_conversion added as needed)
+robin workflow /data/bams -w sturgeon --center Demo --target-panel rCNS2 -d /out --reference /ref/hg38.fa
+
+# Full stack (typical)
+robin workflow /data/bams \
+  -w target,cnv,fusion,mgmt,sturgeon,nanodx,pannanodx,random_forest \
+  --center Sherwood \
+  --target-panel rCNS2 \
+  -d ~/results \
+  --reference ~/references/hg38.fa
+```
+
+## Related
+
+- [`robin workflow`](workflow.md)  
+- [Quickstart](../getting-started/quickstart.md)  

docs/cli/panels.md

@@ -0,0 +1,93 @@
+# Panel commands
+
+Target **panels** define which genes/regions drive **target**, **CNV**, and **fusion** analyses and which packaged BED files ROBIN uses. Built-in panels ship with the install; you can add **custom** panels from BED files.
+
+Commands:
+
+- [`robin list-panels`](#robin-list-panels)
+- [`robin add-panel`](#robin-add-panel)
+- [`robin remove-panel`](#robin-remove-panel)
+
+All require the interactive **disclaimer** (`I agree`).
+
+---
+
+## `robin list-panels`
+
+Lists **built-in** panels (`rCNS2`, `AML`, `PanCan`, …) and **custom** panels registered in `robin.resources`.
+
+```bash
+robin list-panels
+```
+
+Use the printed names with **`robin workflow --target-panel`** and **`robin utils sequencing-files --panel`**.
+
+---
+
+## `robin add-panel`
+
+Register a new panel from a BED file.
+
+```bash
+robin add-panel /path/to/panel.bed MyPanelName
+```
+
+### BED format
+
+- At least **4 columns**: `chrom`, `start`, `end`, `gene` (or comma-separated genes).
+- **6-column** BED is allowed (`score`, `strand`).
+- Regions spanning multiple genes can list **comma-separated** gene symbols in the name column.
+
+### Options
+
+| Flag | Meaning |
+|------|---------|
+| `--validate-only` | Check the BED only; do not copy files into resources. |
+
+### Reserved names
+
+You **cannot** use `rCNS2`, `AML`, or `PanCan` as custom names.
+
+### What ROBIN stores
+
+- **Processed** unique-gene BED: `{PanelName}_panel_name_uniq.bed` under `robin.resources`.
+- **Original upload** copy: `{PanelName}_panel_source.bed` (for traceability and [`sequencing-files`](utils.md#robin-utils-sequencing-files)).
+
+If a panel with the same name already exists, the command fails until you [`remove-panel`](#robin-remove-panel).
+
+---
+
+## `robin remove-panel`
+
+Remove a **custom** panel (not built-ins).
+
+```bash
+robin remove-panel MyPanelName
+robin remove-panel MyPanelName --force
+```
+
+| Flag | Meaning |
+|------|---------|
+| `-f` / `--force` | Skip the `yes` confirmation (destructive). |
+
+Built-in panels **cannot** be removed.
+
+---
+
+## Using panels in a workflow
+
+```bash
+robin workflow /data/bams \
+  -w target,cnv,fusion \
+  --target-panel MyPanelName \
+  --center Sherwood \
+  -d ~/results \
+  --reference ~/references/hg38.fa
+```
+
+---
+
+## Related
+
+- [Utilities — `sequencing-files`](utils.md#robin-utils-sequencing-files) (copy panel BED + reference for MinKNOW)  
+- [`robin workflow`](workflow.md)  

docs/cli/password.md

@@ -0,0 +1,25 @@
+# `robin password`
+
+Configure the **NiceGUI** workflow monitor login password.
+
+For the full startup sequence (disclaimer, when the GUI prompts for a password), see **[What happens at startup](../getting-started/startup.md)**.
+
+## `robin password set`
+
+```bash
+robin password set
+```
+
+- Prompts twice for the new password (no echo).
+- Replaces any previously stored password.
+
+If the GUI password module fails to import (minimal install / broken env), the command prints an error and exits non-zero.
+
+## When it applies
+
+The password is used when the **[`robin workflow`](workflow.md)** GUI is enabled (`--with-gui`, default) and password protection is active in the GUI layer — see application logs and on-screen prompts if login is required.
+
+## Related
+
+- [`robin workflow` GUI options](workflow.md#gui-nicegui)  
+- [CLI overview](index.md)  

docs/cli/utils.md

@@ -0,0 +1,93 @@
+# `robin utils`
+
+Utility subcommands for **assets**, **reference/panel staging**, and **post-hoc** MGMT summaries. The group is separate from the live [`workflow`](workflow.md) so you can update models or prepare files without starting the orchestrator.
+
+```bash
+robin utils --help
+```
+
+Subcommands documented below:
+
+| Command | Purpose |
+|---------|---------|
+| [`update-models`](#robin-utils-update-models) | Download or refresh model files from the assets manifest. |
+| [`update-clinvar`](#robin-utils-update-clinvar) | Update ClinVar resources used for annotation paths. |
+| [`sequencing-files`](#robin-utils-sequencing-files) | Copy panel BED(s) and download or link a GRCh38 FASTA for MinKNOW / alignment. |
+| [`mgmt`](#robin-utils-mgmt) | Tabulate MGMT CpG methylation from existing `mgmt_sorted.bam` outputs. |
+
+---
+
+## `robin utils update-models`
+
+Downloads or refreshes **model** files (checksums via the manifest). Typical after install or when assets change.
+
+```bash
+robin utils update-models
+robin utils update-models --overwrite
+```
+
+| Option | Description |
+|--------|-------------|
+| `--models-dir` | Override output directory (default: ROBIN models directory). |
+| `--manifest` | Path to `assets.json` (default: packaged manifest or `ROBIN_ASSETS_MANIFEST`). |
+| `--overwrite` | Replace existing files. |
+
+For **private** GitHub-hosted assets, set **`GITHUB_TOKEN`** before running.
+
+More context: [Installation — models](../getting-started/installation.md#step-4-download-models-and-clinvar).
+
+---
+
+## `robin utils update-clinvar`
+
+Updates **ClinVar** in ROBIN’s resource tree (best-effort “newer NCBI drop” behaviour).
+
+```bash
+robin utils update-clinvar
+```
+
+Pair with `update-models` when setting up a new environment.
+
+---
+
+## `robin utils sequencing-files`
+
+Stages **panel BED** files and a **reference FASTA** into one folder for **MinKNOW** (adaptive sampling + alignment) and for passing the same path to **`robin workflow --reference`**.
+
+```bash
+robin utils sequencing-files --panel rCNS2 --output-dir ~/references/robin_ref
+```
+
+| Option | Description |
+|--------|-------------|
+| `-p` / `--panel` | **Required.** Panel name (same as `--target-panel`). |
+| `-r` / `--reference` | URL to download or local `.fa` / `.fa.gz`. Default: NCBI **GRCh38 no-alt** (large download). |
+| `-o` / `--output-dir` | Output directory (default: `./reference_files`). |
+| `-y` / `--yes` | Non-interactive confirmation. |
+
+The command copies packaged **`{panel}_panel_name_uniq.bed`** and, when present, **`{panel}_panel_source.bed`**, then materializes the reference.
+
+See also: [Quickstart — Reference and panel BEDs](../getting-started/quickstart.md#reference-and-panel-beds).
+
+---
+
+## `robin utils mgmt`
+
+Summarises **MGMT** CpG methylation from **`mgmt_sorted.bam`** files already produced under a ROBIN output tree (offline inspection / QC).
+
+```bash
+robin utils mgmt /path/to/robin_output --recursive -o mgmt_summary.tsv
+```
+
+| Option | Description |
+|--------|-------------|
+| `OUTPUT_DIR` | Root directory to search (required). |
+| `-r` / `--recursive` | Find `mgmt_sorted.bam` recursively. |
+| `-o` / `--out` | TSV path; default `-` (stdout). |
+
+---
+
+## Related
+
+- [Installation](../getting-started/installation.md)  
+- [Quickstart](../getting-started/quickstart.md)