diff --git a/.gitignore b/.gitignore
index b66b92e..b2ac7f1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -52,6 +52,7 @@ tests/sdr/
# Sphinx documentation
docs/build/
+docs/_build/
# Jupyter Notebook
.ipynb_checkpoints
diff --git a/docs/_build/html/_sources/intro/getting_started.rst.txt b/docs/_build/html/_sources/intro/getting_started.rst.txt
index f51f9fa..c2386ee 100644
--- a/docs/_build/html/_sources/intro/getting_started.rst.txt
+++ b/docs/_build/html/_sources/intro/getting_started.rst.txt
@@ -21,6 +21,7 @@ This is a practical reference for the ``ria`` CLI from ``ria-toolkit-oss``.
.. contents:: Contents
:local:
:depth: 2
+ :backlinks: none
1) Installation and Setup
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
new file mode 100644
index 0000000..40b2823
--- /dev/null
+++ b/docs/source/_static/custom.css
@@ -0,0 +1,29 @@
+/* Change the hex values below to customize heading colours */
+
+.rst-content h1 { color: #2c3e50; }
+.rst-content h2,
+.rst-content h2 a { color: #ffffff !important; font-size: 22px !important; }
+
+.rst-content h3,
+.rst-content h3 a { color: #ffffff !important; font-size: 16px !important; }
+
+.rst-content h3 code { font-size: inherit !important; }
+
+.rst-content .admonition.warning {
+ background: #1a1a2e !important;
+ border-left: 4px solid #c0392b !important;
+}
+
+.rst-content .admonition.warning .admonition-title {
+ background: #c0392b !important;
+ color: #ffffff !important;
+}
+
+.rst-content .admonition.warning p {
+ color: #ffffff !important;
+}
+.rst-content h4 { color: #404040; }
+
+.highlight * { color: #ffffff !important; }
+
+.ria-cmd { color: #2980b9 !important; }
diff --git a/docs/source/_static/custom.js b/docs/source/_static/custom.js
new file mode 100644
index 0000000..f9caf03
--- /dev/null
+++ b/docs/source/_static/custom.js
@@ -0,0 +1,8 @@
+document.addEventListener('DOMContentLoaded', function () {
+ document.querySelectorAll('.highlight pre').forEach(function (pre) {
+ pre.innerHTML = pre.innerHTML.replace(
+ /((?:^|\n|>))(ria)(?=[ \t]|<)/g,
+ '$1$2'
+ );
+ });
+});
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 0260f78..1a3b6d0 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -73,3 +73,6 @@ def setup(app):
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_css_files = ['custom.css']
+html_js_files = ['custom.js']
diff --git a/docs/source/intro/getting_started.rst b/docs/source/intro/getting_started.rst
index 928e753..c2386ee 100644
--- a/docs/source/intro/getting_started.rst
+++ b/docs/source/intro/getting_started.rst
@@ -1,7 +1,1083 @@
-Getting Started
-===============
-
-.. todo::
-
- Getting started instructions are coming soon! In the meantime, feel free
- to explore the project documentation. Many components include usage examples.
+###############
+Getting Started
+###############
+
+This is a practical reference for the ``ria`` CLI from ``ria-toolkit-oss``.
+
+**Scope of this guide:**
+
+* Installation and setup
+* End-to-end CLI workflows
+* Full command reference for CLI features
+* Brief scripting section
+
+**Official resources:**
+
+* `Project README `_
+* `Documentation `_
+* `PyPI package `_
+* `RIA Hub Conda package `_
+
+.. contents:: Contents
+ :local:
+ :depth: 2
+ :backlinks: none
+
+
+1) Installation and Setup
+==========================
+
+1.1 Installation with Conda
+----------------------------
+
+RIA Toolkit OSS is available as a Conda package on RIA Hub. This is typically the easiest
+path when using SDR tooling that depends on native/system libraries.
+
+.. code-block:: bash
+
+ conda update --force conda
+ conda config --add channels https://riahub.ai/api/packages/qoherent/conda
+ conda activate base
+ conda install ria-toolkit-oss
+
+Verify:
+
+.. code-block:: bash
+
+ conda list | grep ria-toolkit-oss
+
+
+1.2 Installation with pip
+--------------------------
+
+Use pip unless you specifically need to edit toolkit source.
+
+.. code-block:: bash
+
+ python3 -m venv .venv
+ source .venv/bin/activate
+ pip install --upgrade pip
+ pip install ria-toolkit-oss
+
+Verify CLI entrypoint:
+
+.. code-block:: bash
+
+ ria --help
+
+``pyproject.toml`` defines two script entry points:
+
+* ``ria``
+* ``ria-tools``
+
+Both point to the same CLI module (``ria_toolkit_oss_cli.cli:cli``).
+
+
+1.3 Optional install from source
+----------------------------------
+
+Use this for local development or testing unreleased changes.
+
+.. code-block:: bash
+
+ git clone https://riahub.ai/qoherent/ria-toolkit-oss.git
+ cd ria-toolkit-oss
+ python3 -m venv .venv
+ source .venv/bin/activate
+ pip install -e .
+
+
+1.4 SDR driver prerequisites
+-----------------------------
+
+Toolkit package install does not install all system SDR drivers. Install vendor/runtime
+dependencies for the hardware you use.
+
+Examples (depends on device and OS):
+
+* USRP: UHD drivers
+* Pluto: libiio / IIO utilities
+* BladeRF: libbladeRF
+* HackRF: libhackrf
+* RTL-SDR: librtlsdr
+
+See repo docs under ``docs/source/sdr_guides/*`` and your OS package instructions.
+
+
+2) CLI Structure
+=================
+
+Top-level CLI follows this model:
+
+.. code-block:: bash
+
+ ria [GLOBAL_OPTS] [ARGS] [OPTIONS]
+
+**Global:**
+
+* ``-v, --verbose`` (defined on root click group)
+
+**Top-level commands:**
+
+* ``discover``
+* ``init``
+* ``capture``
+* ``view``
+* ``annotate`` (group)
+* ``convert``
+* ``split``
+* ``combine``
+* ``generate`` (group)
+* ``transform`` (group)
+* ``transmit``
+* ``synth`` (alias of ``generate`` in command bindings)
+
+
+3) Quick End-to-End Workflow
+=============================
+
+3.1 Discover radios
+--------------------
+
+Run this first in any new environment to verify drivers and detect hardware before
+attempting RX/TX commands.
+
+.. code-block:: bash
+
+ ria discover
+ ria discover -v
+ ria discover --json-output
+
+
+3.2 Initialize local metadata defaults
+---------------------------------------
+
+Set reusable metadata once so generated/captured files automatically include consistent
+provenance fields.
+
+.. code-block:: bash
+
+ ria init
+ # or non-interactive
+ ria init --author "Jane Doe" --project "rf-campaign-1" --location "Lab-A"
+ # show config
+ ria init --show
+
+
+3.3 Capture IQ
+---------------
+
+Capture baseband data from a connected SDR into a reusable file format.
+
+.. code-block:: bash
+
+ ria capture -d pluto -f 2.44G -s 2e6 -n 500000 -o capture.sigmf-data
+
+
+3.4 Visualize and inspect
+--------------------------
+
+Render quick diagnostic plots to validate signal presence, quality, and rough structure.
+
+.. code-block:: bash
+
+ ria view capture.sigmf-data --type simple
+ ria view capture.sigmf-data --type full --show --no-save
+
+
+3.5 Auto-annotate and inspect annotations
+------------------------------------------
+
+Create initial labels automatically, then inspect annotation objects before downstream use.
+
+.. code-block:: bash
+
+ ria annotate energy capture.sigmf-data --label signal --threshold 1.2
+ ria annotate list capture.sigmf-data --verbose
+
+
+3.6 Convert and split
+----------------------
+
+Normalize file format and split large captures into manageable chunks for processing or
+training.
+
+.. code-block:: bash
+
+ ria convert capture.sigmf-data capture.npy
+ ria split capture.sigmf-data --split-every 100000 --output-dir chunks
+
+
+3.7 Apply transforms
+---------------------
+
+Augment or impair recordings to produce controlled variants.
+
+.. code-block:: bash
+
+ ria transform augment channel_swap capture.npy
+ ria transform impair add_awgn_to_signal capture.npy --params snr=10
+
+
+3.8 Transmit (TX-capable radios only)
+--------------------------------------
+
+Replay recorded or synthesized IQ through a transmit-capable SDR.
+
+.. code-block:: bash
+
+ ria transmit -d hackrf -f 2.44G -s 2e6 --input capture.sigmf-data
+ # or generated waveform
+ ria transmit -d hackrf --generate lfm --continuous
+
+
+4) Command Reference
+=====================
+
+4.1 ``discover``
+-----------------
+
+**Purpose:**
+
+* Probe available SDR drivers and enumerate attached hardware.
+* Confirm whether runtime libraries/drivers are installed and discoverable before
+ capture/transmit.
+
+**Usage:**
+
+.. code-block:: bash
+
+ ria discover [--verbose] [--json-output]
+
+**Options:**
+
+* ``-v, --verbose``: include per-driver probe details and import/init failures.
+* ``--json-output``: emit JSON (useful for automation and inventory scripts).
+
+**Behavior notes:**
+
+* ``discover`` checks multiple backends (USB and network paths, depending on driver support).
+* A device not appearing here usually means one of: missing system driver, permission issue,
+ USB/network connectivity issue.
+* Use ``--verbose`` first when troubleshooting; it surfaces driver-level failures that are
+ hidden in default output.
+
+
+4.2 ``init``
+-------------
+
+**Purpose:**
+
+* Create/manage user config file (defaults to ``~/.ria/config.yaml``, or
+ ``$XDG_CONFIG_HOME/ria/config.yaml``).
+
+**Usage:**
+
+.. code-block:: bash
+
+ ria init [options]
+
+**Key options:**
+
+*Metadata defaults:*
+``--author``, ``--organization``, ``--project``, ``--location``, ``--testbed``,
+``--license``, ``--hw``, ``--dataset``
+
+*Actions:*
+``--show``, ``--reset``
+
+*Control:*
+``--config-path``, ``--interactive`` / ``--no-interactive``, ``-y`` / ``--yes``
+
+**What each option category does:**
+
+* Metadata defaults (``--author``, ``--project``, etc.): stored once and reused for later
+ recordings so files have consistent provenance.
+* SigMF-focused fields (``--license``, ``--hw``, ``--dataset``): populate metadata commonly
+ expected in shared datasets.
+* ``--show``: read-only inspect of the current resolved config.
+* ``--reset``: remove config and start clean.
+* ``--config-path``: use a non-default config location (useful for isolated environments or
+ CI).
+* ``--interactive`` / ``--no-interactive``: force prompts on or off regardless of terminal
+ auto-detection.
+* ``--yes``: suppress confirmation prompts for scripted runs.
+
+.. note::
+ Current command output includes a note that some config integration is still being
+ finalized. Config values are already consumed by multiple commands (capture, convert,
+ generate metadata, and YAML config loading paths).
+
+
+4.3 ``capture``
+----------------
+
+**Purpose:**
+
+* Record IQ samples from a supported SDR and save to ``sigmf``, ``npy``, ``wav``, or
+ ``blue``.
+
+**Usage:**
+
+.. code-block:: bash
+
+ ria capture [options]
+
+Device selection (``--device``) is optional if only one device is detected. Exactly one of
+``--num-samples`` or ``--duration`` is required.
+
+**Core options:**
+
+*Device/connection:*
+
+* ``-d, --device {pluto,hackrf,bladerf,usrp,rtlsdr,thinkrf}``
+* ``-i, --ident``
+* ``-c, --config ``
+
+*RF/capture:*
+
+* ``-s, --sample-rate``
+* ``-f, --center-frequency`` (supports values like ``915e6``, ``2.4G``)
+* ``-g, --gain``
+* ``-b, --bandwidth``
+* ``-n, --num-samples``
+* ``-t, --duration``
+
+*Output:*
+
+* ``-o, --output``
+* ``--output-dir``
+* ``--format {npy,sigmf,wav,blue}``
+* ``--save-image``
+
+*Metadata/logging:*
+
+* ``-m, --metadata KEY=VALUE`` (repeatable)
+* ``-v, --verbose``, ``-q, --quiet``
+
+**How options work in practice:**
+
+* ``--device`` + ``--ident``: select both device class and target instance; ``--ident``
+ takes serial/IP style selectors.
+* ``--config``: load a YAML option set, then override specific fields on the CLI as needed.
+* ``--num-samples`` vs ``--duration``: use exact sample count for deterministic datasets,
+ or time-based capture for quick acquisition.
+* ``--format``: ``sigmf`` is best for metadata/annotation workflows.
+* ``--save-image``: writes a quick visual summary alongside capture output.
+* ``--metadata KEY=VALUE``: injects run-specific metadata (campaign ID, antenna, scenario
+ tag, etc.).
+
+**Output behavior:**
+
+* If ``--output`` is omitted, a timestamped filename is generated automatically.
+* If ``--output-dir`` is omitted, captures default to ``recordings/``.
+* Format is inferred from the ``--output`` extension when no explicit ``--format`` is given.
+
+**Examples:**
+
+.. code-block:: bash
+
+ ria capture -d hackrf -s 2e6 -f 2.44G -n 1000000 -o rf.sigmf-data
+ ria capture -d pluto -f 915e6 -t 2 --format npy --output-dir recordings
+ ria capture -c capture_config.yaml
+
+
+4.4 ``view``
+-------------
+
+**Purpose:**
+
+* Generate visualizations from IQ files.
+* Quickly validate signal quality, occupancy, and annotation coverage without writing custom
+ plotting code.
+
+**Usage:**
+
+.. code-block:: bash
+
+ ria view [options]
+
+```` accepts SigMF, NPY, WAV, and Blue files.
+
+**Mode** (``--type``):
+
+* ``simple``: fast-look plots for sanity checks and quick iteration.
+* ``full``: multi-panel diagnostic figure (IQ, time, frequency, metadata views).
+* ``annotations`` / ``annotation``: render annotation overlays.
+* ``channels``: channelized/segmented visualization.
+* ``annotate``: convenience path used in some annotation workflows.
+
+**Output/display options:**
+
+* ``--output``, ``--format {png,pdf,svg,jpg}``
+* ``--show``: open an interactive window (requires a GUI display environment).
+* ``--no-save``: suppress file output; only meaningful with ``--show``.
+* ``--overwrite``
+
+**Style options:**
+
+* ``--dpi``, ``--figsize WxH``, ``--title``
+* ``--light``: switch to a light theme (useful for reports/slides).
+
+**Loading options:**
+
+* ``--legacy``: force legacy NPY loading path for older datasets.
+* ``--config``
+
+**Mode-specific options:**
+
+*simple:* ``--fast``, ``--compact``, ``--horizontal``, ``--constellation``, ``--labels``,
+``--slice start:end[:step]``
+
+*full:* ``--plot-length``, ``--no-spectrogram``, ``--no-iq``, ``--no-frequency``,
+``--no-constellation``, ``--no-metadata``, ``--no-logo``, ``--spines``
+
+*annotations/channels:* ``--channel``
+
+**Examples:**
+
+.. code-block:: bash
+
+ ria view capture.sigmf-data --type simple
+ ria view capture.npy --type full --title "Test Capture" --format pdf
+ ria view capture.npy --show --no-save
+ ria view old.npy --legacy --type simple
+
+
+4.5 ``annotate`` group
+-----------------------
+
+**Purpose:**
+
+* Manual annotation management and auto-detection/separation.
+* Build or refine label metadata directly in recordings for downstream training, QA, and
+ filtering.
+
+**Command shape:**
+
+.. code-block:: bash
+
+ ria annotate ...
+
+**Subcommands:** ``list``, ``add``, ``remove``, ``clear``, ``energy``, ``cusum``,
+``threshold``, ``separate``
+
+**General behavior:**
+
+* SigMF is the preferred format for durable annotation metadata.
+* For non-SigMF input, many operations write a new output artifact unless overwrite behavior
+ is explicitly requested.
+* ``--type {standalone,parallel,intersection}`` controls annotation relation semantics.
+
+``ria annotate list``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ ria annotate list [--verbose]
+
+Prints all annotations for a recording in index order. ``--verbose`` includes additional
+detail per record.
+
+``ria annotate add``
+~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ ria annotate add --start --count --label [options]
+
+Adds one explicit annotation with sample-domain boundaries.
+
+* ``--start``: first sample index of the annotated region.
+* ``--count``: number of samples in the region.
+* ``--freq-lower``, ``--freq-upper``: optional spectral bounds in Hz.
+* ``--comment``, ``--type``, ``-o`` / ``--output``, ``--overwrite``, ``--quiet``
+
+``ria annotate remove``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ ria annotate remove [--output ...] [--overwrite] [--quiet]
+
+Removes exactly one annotation by list index. Run ``annotate list`` first to confirm the
+index.
+
+``ria annotate clear``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ ria annotate clear [--force] [--overwrite] [--quiet]
+
+Removes all annotations from the recording. ``--force`` bypasses the confirmation prompt.
+
+``ria annotate energy``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ ria annotate energy [options]
+
+Detects energetic regions above the estimated noise floor and writes them as annotations.
+
+* ``--label``
+* ``--threshold``: noise-floor multiplier; higher values reduce false positives but can miss
+ weak signals.
+* ``--segments``: number of segments used to estimate baseline noise.
+* ``--window-size``: smoothing size; larger windows stabilize detections at the cost of
+ sharp transition precision.
+* ``--min-distance``: minimum sample spacing between detections, preventing dense duplicate
+ regions.
+* ``--freq-method {nbw,obw,full-detected,full-bandwidth}``: how frequency bounds are assigned
+ to annotations.
+* ``--nfft``, ``--obw-power``
+* ``--type``, ``-o`` / ``--output``, ``--overwrite``, ``--quiet``
+
+``ria annotate cusum``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ ria annotate cusum [options]
+
+Uses change-point detection (CUSUM-style logic) to find regime changes and annotate
+contiguous segments.
+
+* ``--label``
+* ``--min-duration`` (ms): prevents tiny over-segmented labels.
+* ``--window-size``
+* ``--tolerance``: merges nearby boundaries when set above default.
+* ``--type``, ``-o`` / ``--output``, ``--overwrite``, ``--quiet``
+
+``ria annotate threshold``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ ria annotate threshold --threshold <0.0..1.0> [options]
+
+Uses normalized magnitude thresholding to derive annotation spans. Use where a fixed
+amplitude threshold is sufficient.
+
+* ``--label``, ``--window-size``, ``--type``, ``-o`` / ``--output``, ``--overwrite``,
+ ``--quiet``
+
+``ria annotate separate``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+ ria annotate separate [options]
+
+Decomposes selected annotations into narrower spectral components and emits refined
+annotations.
+
+* ``--indices "0,1,2"``: limit operation to specific annotations; omit to process all.
+* ``--nfft``: larger FFT improves frequency resolution but increases compute time.
+* ``--noise-threshold-db``: stabilizes detection across heterogeneous captures.
+* ``--min-component-bw``: rejects narrow fragments likely to be noise artifacts.
+* ``-o`` / ``--output``, ``--overwrite``, ``--quiet``, ``--verbose``
+
+**Examples:**
+
+.. code-block:: bash
+
+ ria annotate list capture.sigmf-data --verbose
+ ria annotate add capture.sigmf-data --start 10000 --count 5000 --label burst
+ ria annotate energy capture.sigmf-data --label signal --threshold 1.3
+ ria annotate cusum capture.sigmf-data --min-duration 5
+ ria annotate separate capture.sigmf-data --indices 0,1 --verbose
+
+
+4.6 ``convert``
+----------------
+
+**Purpose:**
+
+* Convert between ``sigmf``, ``npy``, ``wav``, and ``blue``.
+* Normalize datasets into the format required by downstream tooling or collaboration targets.
+
+**Usage:**
+
+.. code-block:: bash
+
+ ria convert [output] [options]
+
+If ``output`` is omitted, ``--format`` must be provided. If both are given, format is
+inferred from the output file extension.
+
+**Options:**
+
+* ``--format {npy,sigmf,wav,blue}``
+* ``--output-dir``
+* ``--legacy``: use older NPY loader behavior for historical recordings.
+* ``--wav-sample-rate``: target sample rate for WAV export.
+* ``--wav-bits {16,32}``: output PCM depth; higher preserves more dynamic range.
+* ``--blue-format {CI,CF,CD}``: Bluefile complex sample representation.
+* ``--metadata KEY=VALUE`` (repeatable): add or override metadata during conversion;
+ especially useful when exporting to SigMF.
+* ``--overwrite``, ``-v`` / ``--verbose``, ``-q`` / ``--quiet``
+
+**Examples:**
+
+.. code-block:: bash
+
+ ria convert recording.sigmf-data output.npy
+ ria convert recording.npy --format sigmf
+ ria convert highrate.npy audio.wav --wav-sample-rate 48000
+ ria convert old.npy --format sigmf --legacy --overwrite
+
+
+4.7 ``split``
+--------------
+
+**Purpose:**
+
+* Split, trim, or extract recordings.
+* Create manageable dataset shards or extract windows of interest without custom scripts.
+
+**Usage:**
+
+.. code-block:: bash
+
+ ria split [operation] [options]
+
+Choose exactly one operation per invocation:
+
+* ``--split-at ``: binary split at a specific sample index.
+* ``--split-every ``: fixed-size chunking for ML pipelines.
+* ``--split-duration ``: time-based chunking.
+* ``--trim`` (with ``--start`` + ``--length`` or ``--end``): extract one sub-window.
+* ``--extract-annotations``: write each annotated region as a standalone file.
+
+**Trim controls:** ``--start``, ``--length``, ``--end``
+
+**Annotation extraction filters:** ``--annotation-label``, ``--annotation-index``
+
+**Output controls:**
+``--output-dir``, ``--output-prefix``, ``--output-format {npy,sigmf,wav,blue}``,
+``--overwrite``, ``--legacy``, ``-v`` / ``--verbose``, ``-q`` / ``--quiet``
+
+**Examples:**
+
+.. code-block:: bash
+
+ ria split recording.sigmf-data --split-at 500000 --output-dir out
+ ria split recording.sigmf-data --split-every 100000 --output-dir chunks
+ ria split recording.sigmf-data --split-duration 1.0 --output-dir chunks
+ ria split recording.npy --trim --start 1000 --length 5000 --output-dir trimmed
+ ria split annotated.sigmf-data --extract-annotations --annotation-label payload
+
+
+4.8 ``combine``
+----------------
+
+**Purpose:**
+
+* Merge multiple recordings by concatenation or sample-wise addition.
+* Assemble multi-part captures or synthesize mixtures for testing and model training.
+
+**Usage:**
+
+.. code-block:: bash
+
+ ria combine [input3 ...]