# ONT Ecosystem Quick Start Guide

## Installation

### Standard Installation

```bash
git clone https://github.com/Single-Molecule-Sequencing/ont-ecosystem.git
cd ont-ecosystem
./install.sh
source ~/.ont-ecosystem/env.sh

# Verify installation
ont-check
```

### HPC Installation (Great Lakes / ARMIS2)

```bash
module load python/3.10
git clone https://github.com/Single-Molecule-Sequencing/ont-ecosystem.git
cd ont-ecosystem
./install.sh --hpc
source ~/.ont-ecosystem/env.sh
```

## First Steps

### 1. Initialize the Registry

```bash
ont-experiments init --git
```

This creates `~/.ont-registry/` with git tracking.

### 2. Discover Experiments

```bash
ont-experiments discover /path/to/sequencing/runs --register
```

Or use the fast discovery tool:

```bash
ont-discover scan /path/to/sequencing/runs --quick
```

### 3. List Experiments

```bash
ont-experiments list
ont-experiments list --tags cyp2d6
ont-experiments list --format json
```

### 4. Run Analysis

```bash
# QC analysis
ont-experiments run end-reason exp-001 --json qc.json

# With AI insights
end-reason /path/to/pod5 --json qc.json --insights

# Basecalling
ont-experiments run basecalling exp-001 --model sup@v5.0.0 --output calls.bam

# Alignment
ont-experiments run alignment exp-001 --reference GRCh38 --output aligned.bam
```

### 5. View History

```bash
ont-experiments history exp-001
```

## Key Commands

| Command | Description |
|---------|-------------|
| `ont-experiments init` | Initialize registry |
| `ont-discover scan` | Fast experiment discovery |
| `ont-experiments discover` | Find and register experiments |
| `ont-experiments list` | List experiments |
| `ont-experiments info` | Show experiment details |
| `ont-experiments run` | Run analysis skill with provenance |
| `ont-experiments history` | View event history |
| `ont-check` | System health check |
| `ont-doctor` | Diagnose and fix issues |
| `python bin/ont_tui.py` | Terminal dashboard (script) |
| `lab-search "<topic>"` | Search the SMS textbooks + lab corpus from any cwd |
| `lab-search "<question>" --ai` | Same, but also synthesize an answer via GitHub Models GPT-4o (requires `GITHUB_TOKEN`) |

## Getting Help

```bash
ont-experiments --help
ont-experiments run --help
ont-align --help
ont-help  # List all commands
```

### Need to look up textbook material?

For framework / methods questions, use the SMS textbook surfaces:

- **Web (best for reading)**: [/ask](https://single-molecule-sequencing.github.io/sms-textbook-web/ask.html) — LLM-powered Q&A over the 8-volume corpus, with inline citation links. Bring your own GitHub PAT (with `models:read` scope); the page is fully static and the token never leaves your browser.
- **CLI (best for piping into other tools)**: `lab-search "your question"` (or `--ai` for LLM synthesis). Same retrieval index as /ask.
- **Plain search**: [/search](https://single-molecule-sequencing.github.io/sms-textbook-web/search.html) — Pagefind UI without LLM synthesis.