docs: document squiggy-session.json across all docs

Add documentation for the generate_squiggy_session rule and script
to CLAUDE.md, outputs guide, scripts reference, and rules reference.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jayhesselberth

CLAUDE.md

@@ -80,6 +80,7 @@ workflow/
 │   ├── aatrnaseq-modifications.smk    # Modification calling: coverage, modkit outputs (4 rules)
 │   └── warpdemux.smk                  # WarpDemuX demultiplexing (conditionally loaded)
 ├── scripts/                           # Python scripts called by rules
+│   └── generate_squiggy_session.py    # Generate Squiggy/Positron session JSON
 └── envs/
     └── aatrnaseqpipe-env.yml          # Conda environment (legacy)
 ```
@@ -125,6 +126,9 @@ After classification, generates (split across three rule files):
 - Modkit modification pileups
 - Modkit per-read modification calls
 
+**common.smk:**
+- Squiggy session JSON (`squiggy-session.json`) for loading outputs in Positron IDE
+
 ## Configuration
 
 ### Main Config Files
@@ -265,3 +269,6 @@ Key outputs per sample:
 - `summary/tables/{sample}/{sample}.charging.cpm.tsv.gz` - CPM-normalized charging counts
 - `summary/tables/{sample}/{sample}.charging_prob.tsv.gz` - Per-read charging probabilities
 - `bam/final/{sample}/{sample}.bam` - Final BAM with CL/CM (charging) and PT (adapter positions) tags
+
+Pipeline-level outputs:
+- `squiggy-session.json` - Squiggy session file for loading samples in Positron

docs/user-guide/outputs.md

@@ -13,7 +13,8 @@ This guide documents all output files produced by the pipeline.
 │   ├── tables/             # Tabular summaries
 │   └── modkit/             # Modification calling
 ├── demux/                   # Demultiplexing outputs (if enabled)
-└── logs/                    # Rule execution logs
+├── logs/                    # Rule execution logs
+└── squiggy-session.json     # Squiggy session file for Positron
 ```
 
 ## Data Flow and Outputs
@@ -208,6 +209,41 @@ Individual modification calls per read.
 
 Comprehensive modification information including all modkit fields.
 
+## Squiggy Session File
+
+`squiggy-session.json`
+
+A JSON session file generated at the root of the output directory for loading pipeline outputs in the [Squiggy](https://github.com/rnabioco/squiggy) extension for Positron IDE.
+
+**Contents:**
+
+- Relative paths to POD5, BAM, and reference FASTA files for each sample
+- MD5 checksums and file metadata for integrity verification
+- Default plot options (eventalign mode, z-normalization)
+
+**JSON structure:**
+
+```json
+{
+  "version": "1.0.0",
+  "timestamp": "...",
+  "sessionName": "aa-tRNA-seq: ...",
+  "samples": {
+    "sample1": {
+      "pod5Paths": ["pod5/sample1/sample1.pod5"],
+      "bamPath": "bam/final/sample1/sample1.bam",
+      "fastaPath": "../path/to/reference.fa"
+    }
+  },
+  "plotOptions": { ... },
+  "fileChecksums": { ... }
+}
+```
+
+**Usage:**
+
+Open the `squiggy-session.json` file in Positron to load all samples with their associated POD5, BAM, and reference files.
+
 ## Intermediate Files
 
 These files are produced but typically not used directly:

docs/workflow/rules-reference.md

@@ -485,6 +485,37 @@ modkit extract full \
 
 ---
 
+## Utility Rules
+
+### generate_squiggy_session
+
+Generate a Squiggy session JSON file for loading pipeline outputs in Positron IDE.
+
+**File:** `workflow/rules/common.smk`
+
+| Property | Value |
+|----------|-------|
+| Input | All final BAMs, all merged POD5s, reference FASTA |
+| Output | `squiggy-session.json` (at output root) |
+| GPU | No |
+
+**Command:**
+```bash
+python generate_squiggy_session.py \
+    --samples {sample_names} \
+    --output-dir {output_dir} \
+    --fasta {fasta} \
+    --output {output.session}
+```
+
+**Notes:**
+
+- Generates relative paths to POD5, BAM, and FASTA files for each sample
+- Computes MD5 checksums for file integrity verification
+- Includes default plot options for the Squiggy viewer (eventalign mode, z-normalization)
+
+---
+
 ## Demultiplexing Rules
 
 See [Demultiplexing](demultiplexing.md) for detailed documentation.
@@ -531,4 +562,6 @@ flowchart LR
     add_adapter_tags --> bam_to_coverage
     add_adapter_tags --> modkit_pileup
     get_cca_trna --> get_cca_trna_cpm
+    add_adapter_tags --> generate_squiggy_session
+    merge_pods --> generate_squiggy_session
 ```

docs/workflow/scripts-reference.md

@@ -14,6 +14,7 @@ Documentation for Python scripts in `workflow/scripts/`.
 | `get_align_stats.py` | Summarize alignment statistics |
 | `extract_signal_metrics.py` | Extract Remora signal metrics |
 | `filter_reads.py` | Filter BAM by quality criteria |
+| `generate_squiggy_session.py` | Generate Squiggy session JSON for Positron |
 
 ---
 
@@ -382,6 +383,48 @@ Tracks filtering reasons with methods:
 
 ---
 
+## generate_squiggy_session.py
+
+Generate a Squiggy session JSON file for loading pipeline outputs in Positron IDE.
+
+### Usage
+
+```bash
+python generate_squiggy_session.py \
+    --samples sample1 sample2 \
+    --output-dir /path/to/output \
+    --fasta /path/to/reference.fa \
+    --output squiggy-session.json \
+    [--session-name "My session"] \
+    [--no-checksums]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `--samples` | Sample names to include (space-separated) |
+| `--output-dir` | Pipeline output directory (paths are relative to this) |
+| `--fasta` | Path to reference FASTA file |
+| `--output` | Output JSON file path |
+| `--session-name` | Optional session name (defaults to `aa-tRNA-seq: {directory}`) |
+| `--no-checksums` | Skip computing MD5 checksums (faster but no integrity verification) |
+
+### Output Format
+
+JSON with the following structure:
+
+| Key | Description |
+|-----|-------------|
+| `version` | Schema version (`1.0.0`) |
+| `timestamp` | ISO 8601 generation time |
+| `sessionName` | Display name for the session |
+| `samples` | Per-sample `pod5Paths`, `bamPath`, `fastaPath` (relative paths) |
+| `plotOptions` | Default plot settings (eventalign mode, z-normalization) |
+| `fileChecksums` | MD5, size, and last-modified per file (unless `--no-checksums`) |
+
+---
+
 ## Common Patterns
 
 ### Reading BAM Files