Clarify path conventions and skip-denoise workflow in stage docs

Author: MihinP

docs/docs/getting-started.md

@@ -32,27 +32,29 @@ project_directory/
 │   ├── micrograph1.mrc
 │   ├── micrograph2.mrc
 │   └── ...
-├── denoised/                  # Created by denoise stage
-│   ├── micrograph1.mrc
-│   ├── micrograph2.mrc
+├── denoised/                  # Created by denoise stage (default: .png)
+│   ├── micrograph1.png
+│   ├── micrograph2.png
 │   └── ...
 ├── exp/                       # Created by detect stage
 │   ├── labels/               # Detection coordinates (YOLO format)
 │   │   ├── micrograph1.txt
 │   │   ├── micrograph2.txt
 │   │   └── ...
-│   ├── micrograph1.png    # Micrographs with detections drawn
-│   ├── micrograph2.
+│   ├── micrograph1.png       # Micrographs with detections drawn
+│   ├── micrograph2.png
 │   └── ...
 └── partinet_particles.star   # CryoSPARC-style STAR file (created by star stage)
 ```
 
 **Pipeline Flow:**
 1. **Input** → `motion_corrected/` (your micrographs)
-2. **Stage 1** → `denoised/` (cleaned micrographs)
+2. **Stage 1** → `denoised/` (cleaned micrographs, PNG by default)
 3. **Stage 2** → `exp*/` (detections + visualizations)
 4. **Stage 3** → `*.star` (final particle coordinates)
 
+See [Detect — skip denoise](stages/detect.md#skip-denoise-raw-mrc) if picking directly on raw MRC without denoising.
+
 ## Stage 1: Denoise
 
 The first stage removes noise from your micrographs and improves signal-to-noise ratios:
@@ -61,8 +63,8 @@ The first stage removes noise from your micrographs and improves signal-to-noise
 
 ```shell title="Local Installation"
 partinet denoise \
-    --source /data/my_project/motion_corrected \
-    --project /data/my_project
+    --source /data/partinet_picking/motion_corrected \
+    --project /data/partinet_picking
 ```
 
 </div>
@@ -108,9 +110,9 @@ The final stage converts detections to STAR format and applies confidence filter
 
 ```shell title="Local Installation"
 partinet star \
-    --labels /data/my_project/exp/labels \
-    --images /data/my_project/denoised \
-    --output /data/my_project/partinet_particles.star \
+    --labels /data/partinet_picking/exp/labels \
+    --images /data/partinet_picking/denoised \
+    --output /data/partinet_picking/partinet_particles.star \
     --conf 0.1
 ```
 
@@ -126,7 +128,7 @@ partinet star \
 After running all three stages, you'll have:
 
 1. **Denoised micrographs** (`denoised/`) - Cleaned input for particle detection
-2. **Detection visualizations** (`exp/*.mrc`) - Micrographs with particle boxes drawn
+2. **Detection visualizations** (`exp/*.png`) - Micrographs with particle boxes drawn
 3. **Detection coordinates** (`exp/labels/*.txt`) - Raw detection data
 4. **STAR file** (`*.star`) - Final particle coordinates ready for downstream processing
 

docs/docs/stages/denoise.md

@@ -12,10 +12,12 @@ Denoising can vastly improve particle picking by helping to increase signal to n
 
 ### Required Parameters
 
-| Parameter | Description | Example |
-|-----------|-------------|---------|
-| `--source` | Directory containing motion-corrected micrographs in MRC format | `/data/partinet_picking/motion_corrected` |
-| `--project` | Parent project directory where all outputs will be saved | `/data/partinet_picking` |
+| Parameter | Role | Example |
+|-----------|------|---------|
+| `--source` | Input folder for this stage (motion-corrected `.mrc` files) | `/data/partinet_picking/motion_corrected` |
+| `--project` | Dataset root where outputs and logs are written | `/data/partinet_picking` |
+
+Denoised micrographs are always written to `<project>/denoised/`. The `--source` directory is never modified.
 
 ### Optional Parameters
 
@@ -166,7 +168,7 @@ partinet denoise \
 
 
 ### Different Output Formats
-By default PartiNet outputs denoised images in `png` format. This is necessary for compatibility with the detection architecture. `png` is a lossless compression, however micrographs are normalised from 32 bit depth `mrc` files to 8 bit `png`. `jpg` is also available (as a legacy format) but is not recommended for use due to lossy compression.
+By default PartiNet outputs denoised images in `png` format. This is the recommended format for the Detect stage. `png` is lossless; micrographs are normalised from 32-bit MRC to 8-bit PNG. `jpg` is available but not recommended due to lossy compression.
 
 ```shell
 # JPEG format (smaller file size, lossy compression)

docs/docs/stages/detect.md

@@ -105,8 +105,30 @@ partinet detect \
 
 ### Supported Formats
 
-- **PNG files** (`.png`)
-- **JPEG files** (`.jpg`, `.jpeg`)
+**Standard workflow (recommended):**
+
+- **PNG files** (`.png`) from the Denoise stage — use with `denoised_micrographs.pt`
+
+**Skip-denoise workflow:**
+
+- **MRC files** (`.mrc`) motion-corrected micrographs — use with `raw_micrographs.pt`
+- Raw MRC inputs are per-micrograph min–max normalised to 8-bit before inference (not the same as EMAN2 or CryoSegNet display)
+
+### Skip denoise (raw MRC)
+
+If you want to pick directly on motion-corrected micrographs without denoising:
+
+```shell
+partinet detect \
+    --weight /path/to/raw_micrographs.pt \
+    --source /data/partinet_picking/motion_corrected \
+    --project /data/partinet_picking \
+    --device 0
+```
+
+Use `raw_micrographs.pt` only with raw MRC inputs. For denoised PNG, use `denoised_micrographs.pt`.
+
+When generating a STAR file after skip-denoise, set `--images` to the **same folder** used as detect `--source` (e.g. `motion_corrected/`, not `denoised/`).
 
 ### Directory Structure
 
@@ -133,16 +155,16 @@ partinet_picking/
 │   ├── micrograph2.mrc
 │   └── ...
 ├── denoised/                  # 🧹 Created by denoise stage
-│   ├── micrograph1.mrc
-│   ├── micrograph2.mrc
+│   ├── micrograph1.png
+│   ├── micrograph2.png
 │   └── ...
 ├── exp/                       # 🎯 Created by detect stage
 │   ├── labels/               # 📋 Detection coordinates
 │   │   ├── micrograph1.txt
 │   │   ├── micrograph2.txt
 │   │   └── ...
-│   ├── micrograph1.mrc       # 🖼️ Micrographs with detections drawn
-│   ├── micrograph2.mrc
+│   ├── micrograph1.png       # 🖼️ Micrographs with detections drawn
+│   ├── micrograph2.png
 │   └── ...
 └── partinet_detect.log
 ```

docs/docs/stages/star.md

@@ -40,12 +40,14 @@ docker run --gpus all -v /data:/data \
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `--labels` | Path | Yes | Directory containing the particle coordinate files (`.txt` format) from the detection stage |
-| `--images` | Path | Yes | Directory containing the denoised micrographs corresponding to the labels |
+| `--images` | Path | Yes | Directory containing micrographs used during Detect — usually `<project>/denoised/`; if you skipped denoise, use the same folder as detect `--source` |
 | `--output` | Path | Yes | Output path for the generated STAR file |
 | `--conf` | Float | Yes | Confidence threshold for filtering particle coordinates (0.0-1.0) |
 
 ## Input Requirements
 
+**Important:** `--images` must match the folder passed to `partinet detect --source`. After the standard pipeline that is `<project>/denoised/`; after skip-denoise on raw MRC it is `<project>/motion_corrected/` (or wherever your `.mrc` files live).
+
 At this stage of the pipeline, your directory structure should look like:
 ```
 partinet_picking/