From 1a11710df731e769dc7a4ae3552d8c7b2821126c Mon Sep 17 00:00:00 2001
From: Javanaut <javanaut@refulgent.de>
Date: Mon, 15 Jun 2026 11:14:21 +0200
Subject: [PATCH] Convert docs to sphinx

---
 .gitignore              |   4 +-
 .vscode/extensions.json |  11 +
 .vscode/settings.json   |  18 ++
 SCRATCHPAD.md           |   8 +
 docs/Makefile           |  21 ++
 docs/api.rst            |  31 +++
 docs/conf.py            |  44 ++++
 docs/development.rst    |  50 +++++
 docs/esbonio.db         | Bin 0 -> 4096 bytes
 docs/file_formats.md    | 170 ---------------
 docs/file_formats.rst   | 192 ++++++++++++++++
 docs/index.rst          |  25 +++
 docs/installation.rst   |  52 +++++
 docs/make.bat           |  42 ++++
 docs/usage.rst          |  75 +++++++
 pyproject.toml          |   6 +
 tests/prepare.sh        | 471 ++++++++++++++++++++++++++++++++++++++++
 17 files changed, 1048 insertions(+), 172 deletions(-)
 create mode 100644 .vscode/extensions.json
 create mode 100644 .vscode/settings.json
 create mode 100644 docs/Makefile
 create mode 100644 docs/api.rst
 create mode 100644 docs/conf.py
 create mode 100644 docs/development.rst
 create mode 100644 docs/esbonio.db
 delete mode 100644 docs/file_formats.md
 create mode 100644 docs/file_formats.rst
 create mode 100644 docs/index.rst
 create mode 100644 docs/installation.rst
 create mode 100644 docs/make.bat
 create mode 100644 docs/usage.rst
 create mode 100755 tests/prepare.sh

diff --git a/.gitignore b/.gitignore
index c624ec6..25d914e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,6 @@
 __pycache__/
 *.py[cod]
 junk/
-.vscode
 .ipynb_checkpoints/
 tools/ansible/inventory/hawaii.yml
 tools/ansible/inventory/peppermint.yml
@@ -17,6 +16,7 @@ dist/
 *.egg-info/
 .venv/
 venv/
+docs/_build/
 .codex
 
 
@@ -24,4 +24,4 @@ venv/
 *.webm
 *.mp4
 ffmpeg2pass-0.log
-*.sup
\ No newline at end of file
+*.sup
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 0000000..6c7e62c
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,11 @@
+{
+  "recommendations": [
+    "swyddfa.esbonio",
+    "ms-python.python",
+    "ms-python.vscode-pylance",
+    "ms-python.debugpy",
+    "tamasfe.even-better-toml",
+    "redhat.vscode-yaml",
+    "DavidAnson.vscode-markdownlint"
+  ]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..daa653b
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,18 @@
+{
+  "esbonio.sphinx.pythonCommand": "${venv:.venv}/bin/python",
+  "esbonio.sphinx.buildCommand": [
+    "sphinx-build",
+    "-b",
+    "html",
+    "docs",
+    "docs/_build/html"
+  ],
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.testing.pytestEnabled": true,
+  "python.testing.pytestArgs": [
+    "--ignore=tests/legacy",
+    "--ignore=tests/support",
+    "tests"
+  ],
+  "restructuredtext.confPath": "${workspaceFolder}/docs"
+}
diff --git a/SCRATCHPAD.md b/SCRATCHPAD.md
index 89eaddd..25f63bb 100644
--- a/SCRATCHPAD.md
+++ b/SCRATCHPAD.md
@@ -69,3 +69,11 @@
 ## Delete When
 
 - Delete this scratchpad once the optimization backlog is either converted into issues/work items or distilled into durable project guidance.
+
+
+<!--
+
+DuplicatePatternMatchError: Filename 'conan_S01E727_amalgam.avi.mkv' matched more than one pattern: show #30983 pattern #123 'conan_([sS][0-9]+[eE][0-9]+)_amalgam.avi.mkv', show #30983 pattern #124 
+'conan_([sS][0-9]+[eE][0-9]+)_amalgam.avi'
+
+-->
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..38f13a3
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,21 @@
+SPHINXOPTS       ?=
+VENV_SPHINXBUILD = ../.venv/bin/sphinx-build
+SPHINXBUILD      ?= $(if $(wildcard $(VENV_SPHINXBUILD)),$(VENV_SPHINXBUILD),sphinx-build)
+SOURCEDIR        = .
+BUILDDIR         = _build
+
+.PHONY: help clean html linkcheck
+
+help:
+	@echo "Please use 'make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  linkcheck  to check all external links for integrity"
+
+clean:
+	rm -rf "$(BUILDDIR)"
+
+html:
+	@$(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
+
+linkcheck:
+	@$(SPHINXBUILD) -b linkcheck "$(SOURCEDIR)" "$(BUILDDIR)/linkcheck" $(SPHINXOPTS)
diff --git a/docs/api.rst b/docs/api.rst
new file mode 100644
index 0000000..7abda7a
--- /dev/null
+++ b/docs/api.rst
@@ -0,0 +1,31 @@
+API Reference
+=============
+
+This section exposes selected modules that are useful when working on tests,
+diagnostics, process execution, metadata editing, and file probing.
+
+CLI Helpers
+-----------
+
+.. automodule:: ffx.cli
+   :members:
+   :undoc-members:
+
+Process Helpers
+---------------
+
+.. automodule:: ffx.process
+   :members:
+   :undoc-members:
+
+File Probing
+------------
+
+.. automodule:: ffx.file_properties
+
+Metadata Editing
+----------------
+
+.. automodule:: ffx.metadata_editor
+   :members:
+   :undoc-members:
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..54a69b5
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as package_version
+from pathlib import Path
+import sys
+
+
+ROOT_DIR = Path(__file__).resolve().parents[1]
+SRC_DIR = ROOT_DIR / "src"
+sys.path.insert(0, str(SRC_DIR))
+
+project = "FFX"
+author = "javanaut@maveno.de"
+copyright = "2026, Maveno"
+
+try:
+    release = package_version("ffx")
+except PackageNotFoundError:
+    release = "0.0.0"
+version = release
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+}
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"
+html_title = "FFX"
+html_static_path = []
+
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+napoleon_google_docstring = True
+napoleon_numpy_docstring = True
+
diff --git a/docs/development.rst b/docs/development.rst
new file mode 100644
index 0000000..0d9281e
--- /dev/null
+++ b/docs/development.rst
@@ -0,0 +1,50 @@
+Development
+===========
+
+The repo-local ``.venv`` is the preferred environment for contributors working
+on tests or documentation:
+
+.. code-block:: sh
+
+   tests/prepare.sh
+
+The preparation script installs the package in editable mode with both test and
+documentation extras:
+
+.. code-block:: text
+
+   .[test,docs]
+
+Run Tests
+---------
+
+Run the modern pytest suite:
+
+.. code-block:: sh
+
+   .venv/bin/python -m pytest --ignore=tests/legacy --ignore=tests/support tests
+
+The legacy harness remains available separately and is intentionally not part of
+the default pytest run.
+
+Build Docs
+----------
+
+Build HTML documentation:
+
+.. code-block:: sh
+
+   .venv/bin/sphinx-build -b html docs docs/_build/html
+
+The same command is wrapped by the Sphinx ``Makefile``:
+
+.. code-block:: sh
+
+   make -C docs html
+
+VS Code
+-------
+
+The repository includes ``.vscode/extensions.json`` with recommended
+extensions, including Esbonio for Sphinx language-server support. The workspace
+settings point Python tooling and Esbonio at the repo-local ``.venv``.
diff --git a/docs/esbonio.db b/docs/esbonio.db
new file mode 100644
index 0000000000000000000000000000000000000000..0de02ecf623141161c863ee065d9f7dd83cbe849
GIT binary patch
literal 4096
zcmWFz^vNtqRY=P(%1ta$FlG>7U}9o$P*7lCU|@t|AVoG{WYDWB<OOLLAlr;ljiVtj
n8UmvsFd71*Aut*OqaiRF0;3@?8UmvsFd71*Aut*O6ovo*9}Ncl

literal 0
HcmV?d00001

diff --git a/docs/file_formats.md b/docs/file_formats.md
deleted file mode 100644
index 25f827c..0000000
--- a/docs/file_formats.md
+++ /dev/null
@@ -1,170 +0,0 @@
-# File Formats
-
-This document captures source-file-format notes that complement the normative
-requirements in `requirements/source_file_formats.md`.
-
-The first documented format is a Matroska source that carries styled ASS/SSA
-subtitle streams together with embedded font attachments.
-
-## Styled ASS In Matroska With Embedded Fonts
-
-These files are typically `.mkv` releases where subtitle rendering quality
-depends on keeping both parts of the subtitle package together:
-
-- one or more subtitle streams with codec `ass`
-- one or more attachment streams that embed font files used by those subtitles
-
-This matters because ASS subtitles are not plain text subtitles in the narrow
-WebVTT sense. They can carry layout, styling, positioning, karaoke, signs, and
-other typesetting effects. If the matching embedded fonts are lost, consumers
-can still see subtitle text but the intended styling and sometimes glyph
-coverage can be degraded.
-
-For FFX this format is special because the ASS subtitle streams should remain
-normally editable and mappable, while the related font attachments should be
-transported unchanged.
-
-## Observed Sample
-
-Assessment date: `2026-04-17`
-
-Observed sample file:
-
-- `tests/assets/boruto_s01e283_ssa.mkv`
-
-Commands used for assessment:
-
-```bash
-ffprobe tests/assets/boruto_s01e283_ssa.mkv
-ffprobe -hide_banner -show_format -show_streams -of json tests/assets/boruto_s01e283_ssa.mkv
-```
-
-Observed stream layout:
-
-| Stream index | Kind | Key details |
-| --- | --- | --- |
-| `0` | video | `codec_name=h264` |
-| `1` | audio | `codec_name=aac`, `language=jpn` |
-| `2` | subtitle | `codec_name=ass`, `language=ger`, default |
-| `3` | subtitle | `codec_name=ass`, `language=eng` |
-| `4`-`13` | attachment | `tags.mimetype=font/ttf`, `.ttf` filenames |
-
-Observed attachment filenames:
-
-- `AmazonEmberTanuki-Italic.ttf`
-- `AmazonEmberTanuki-Regular.ttf`
-- `Arial.ttf`
-- `Arial Bold.ttf`
-- `Georgia.ttf`
-- `Times New Roman.ttf`
-- `Times New Roman Bold.ttf`
-- `Trebuchet MS.ttf`
-- `Verdana.ttf`
-- `Verdana Bold.ttf`
-
-Important probe behavior from the real sample:
-
-- Plain `ffprobe` lists the font streams as `Attachment: none`.
-- Plain `ffprobe` also prints warnings such as `Could not find codec
-  parameters for stream 4 (Attachment: none): unknown codec` and later
-  `Unsupported codec with id 0 for input stream ...`.
-- The JSON produced by `FileProperties.FFPROBE_COMMAND_TOKENS`
-  (`ffprobe -hide_banner -show_format -show_streams -of json`) still exposes
-  the attachment streams clearly through `codec_type="attachment"` and the
-  attachment tags.
-- In that JSON, the attachment streams do not expose `codec_name`.
-
-This last point is important for FFX: robust detection must not depend on
-attachment `codec_name` being present.
-
-## Detection Guidance
-
-Current known indicators for this format are:
-
-- one or more subtitle streams with `codec_type="subtitle"` and
-  `codec_name="ass"`
-- one or more attachment streams with `codec_type="attachment"`
-- attachment tags that identify embedded fonts, especially
-  `tags.mimetype="font/ttf"`
-- attachment filenames that end in `.ttf`
-
-The pattern can vary. FFX should therefore treat the above as a cluster of
-signals rather than an exact signature tied to one file.
-
-Inference from the observed sample plus FFmpeg documentation:
-
-- MIME matching should not be limited to `font/ttf` alone.
-- The Boruto sample uses `font/ttf`.
-- FFmpeg's Matroska attachment example uses
-  `mimetype=application/x-truetype-font` for a `.ttf` attachment.
-- Detection should therefore normalize multiple TTF-like MIME values rather
-  than depend on a single exact string.
-
-## Processing Expectations In FFX
-
-The format-specific requirements live in
-`requirements/source_file_formats.md`. In practical terms, FFX should:
-
-- recognize the ASS-plus-font-attachment pattern even when attachment probe
-  data is incomplete
-- tell the operator that the pattern was detected and that special handling is
-  being used
-- reject sidecar subtitle import for such sources, because converting or
-  replacing these subtitle tracks with ordinary external text subtitles would
-  break the intended subtitle package
-- continue to allow normal manipulation of the ASS subtitle tracks themselves
-- preserve the font attachment streams unchanged
-
-## FFmpeg Notes
-
-Relevant FFmpeg documentation confirms several behaviors that line up with
-FFX's needs:
-
-- FFmpeg documents `-attach` as adding an attachment stream to the output, and
-  explicitly names Matroska fonts used in subtitle rendering as an example.
-- FFmpeg documents attachment streams as regular streams that are created after
-  the mapped media streams.
-- FFmpeg documents `-dump_attachment` for extracting attachment streams, which
-  is useful for debugging or validating a source file's embedded fonts.
-- FFmpeg's Matroska example requires a `mimetype` metadata tag for attached
-  fonts, which is consistent with using attachment tags as detection signals.
-- FFmpeg also notes that attachments are implemented as codec extradata. That
-  helps explain why probe output for attachment streams can look different from
-  ordinary audio, video, and subtitle streams.
-
-Implication for FFX:
-
-- Attachment preservation is not an optional cosmetic feature for this format.
-  It is part of preserving the subtitle package correctly.
-
-## Jellyfin Notes
-
-Jellyfin's documentation also supports keeping this format intact:
-
-- Jellyfin's subtitle compatibility table lists `ASS/SSA` as supported in
-  `MKV` and not supported in `MP4`.
-- Jellyfin notes that when subtitles must be transcoded, they are either
-  converted to a supported format or burned into the video, and burning them in
-  is the most CPU-intensive path.
-- Jellyfin's subtitle-extraction example for `SSA/ASS` first dumps attachment
-  streams and then extracts the ASS subtitle stream, which reflects the real
-  relationship between ASS subtitles and embedded fonts in MKV releases.
-- Jellyfin's font documentation says text-based subtitles require fonts to
-  render properly.
-- Jellyfin's configuration documentation says the web client uses configured
-  fallback fonts for ASS subtitles when other fonts such as MKV attachments or
-  client-side fonts are not available.
-
-Inference from the Jellyfin compatibility tables:
-
-- Keeping this subtitle format in Matroska is the safest interoperability
-  choice for Jellyfin consumers.
-- Converting the subtitle payload to WebVTT would lose styled ASS behavior.
-- Dropping the attachment streams would force client or fallback font
-  substitution and can change appearance or glyph coverage.
-
-## References
-
-- FFmpeg documentation: https://ffmpeg.org/ffmpeg.html
-- Jellyfin codec support: https://jellyfin.org/docs/general/clients/codec-support/
-- Jellyfin configuration and fonts: https://jellyfin.org/docs/general/administration/configuration/
diff --git a/docs/file_formats.rst b/docs/file_formats.rst
new file mode 100644
index 0000000..df9af19
--- /dev/null
+++ b/docs/file_formats.rst
@@ -0,0 +1,192 @@
+File Formats
+============
+
+This document captures source-file-format notes that complement the normative
+requirements in ``requirements/source_file_formats.md``.
+
+The first documented format is a Matroska source that carries styled ASS/SSA
+subtitle streams together with embedded font attachments.
+
+Styled ASS In Matroska With Embedded Fonts
+------------------------------------------
+
+These files are typically ``.mkv`` releases where subtitle rendering quality
+depends on keeping both parts of the subtitle package together:
+
+* one or more subtitle streams with codec ``ass``
+* one or more attachment streams that embed font files used by those subtitles
+
+This matters because ASS subtitles are not plain text subtitles in the narrow
+WebVTT sense. They can carry layout, styling, positioning, karaoke, signs, and
+other typesetting effects. If the matching embedded fonts are lost, consumers
+can still see subtitle text but the intended styling and sometimes glyph
+coverage can be degraded.
+
+For FFX this format is special because the ASS subtitle streams should remain
+normally editable and mappable, while the related font attachments should be
+transported unchanged.
+
+Observed Sample
+---------------
+
+Assessment date: ``2026-04-17``
+
+Observed sample file:
+
+* ``tests/assets/boruto_s01e283_ssa.mkv``
+
+Commands used for assessment:
+
+.. code-block:: bash
+
+   ffprobe tests/assets/boruto_s01e283_ssa.mkv
+   ffprobe -hide_banner -show_format -show_streams -of json tests/assets/boruto_s01e283_ssa.mkv
+
+Observed stream layout:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Stream index
+     - Kind
+     - Key details
+   * - ``0``
+     - video
+     - ``codec_name=h264``
+   * - ``1``
+     - audio
+     - ``codec_name=aac``, ``language=jpn``
+   * - ``2``
+     - subtitle
+     - ``codec_name=ass``, ``language=ger``, default
+   * - ``3``
+     - subtitle
+     - ``codec_name=ass``, ``language=eng``
+   * - ``4``-``13``
+     - attachment
+     - ``tags.mimetype=font/ttf``, ``.ttf`` filenames
+
+Observed attachment filenames:
+
+* ``AmazonEmberTanuki-Italic.ttf``
+* ``AmazonEmberTanuki-Regular.ttf``
+* ``Arial.ttf``
+* ``Arial Bold.ttf``
+* ``Georgia.ttf``
+* ``Times New Roman.ttf``
+* ``Times New Roman Bold.ttf``
+* ``Trebuchet MS.ttf``
+* ``Verdana.ttf``
+* ``Verdana Bold.ttf``
+
+Important probe behavior from the real sample:
+
+* Plain ``ffprobe`` lists the font streams as ``Attachment: none``.
+* Plain ``ffprobe`` also prints warnings such as ``Could not find codec
+  parameters for stream 4 (Attachment: none): unknown codec`` and later
+  ``Unsupported codec with id 0 for input stream ...``.
+* The JSON produced by ``FileProperties.FFPROBE_COMMAND_TOKENS``
+  (``ffprobe -hide_banner -show_format -show_streams -of json``) still exposes
+  the attachment streams clearly through ``codec_type="attachment"`` and the
+  attachment tags.
+* In that JSON, the attachment streams do not expose ``codec_name``.
+
+This last point is important for FFX: robust detection must not depend on
+attachment ``codec_name`` being present.
+
+Detection Guidance
+------------------
+
+Current known indicators for this format are:
+
+* one or more subtitle streams with ``codec_type="subtitle"`` and
+  ``codec_name="ass"``
+* one or more attachment streams with ``codec_type="attachment"``
+* attachment tags that identify embedded fonts, especially
+  ``tags.mimetype="font/ttf"``
+* attachment filenames that end in ``.ttf``
+
+The pattern can vary. FFX should therefore treat the above as a cluster of
+signals rather than an exact signature tied to one file.
+
+Inference from the observed sample plus FFmpeg documentation:
+
+* MIME matching should not be limited to ``font/ttf`` alone.
+* The Boruto sample uses ``font/ttf``.
+* FFmpeg's Matroska attachment example uses
+  ``mimetype=application/x-truetype-font`` for a ``.ttf`` attachment.
+* Detection should therefore normalize multiple TTF-like MIME values rather
+  than depend on a single exact string.
+
+Processing Expectations In FFX
+------------------------------
+
+The format-specific requirements live in
+``requirements/source_file_formats.md``. In practical terms, FFX should:
+
+* recognize the ASS-plus-font-attachment pattern even when attachment probe data
+  is incomplete
+* tell the operator that the pattern was detected and that special handling is
+  being used
+* reject sidecar subtitle import for such sources, because converting or
+  replacing these subtitle tracks with ordinary external text subtitles would
+  break the intended subtitle package
+* continue to allow normal manipulation of the ASS subtitle tracks themselves
+* preserve the font attachment streams unchanged
+
+FFmpeg Notes
+------------
+
+Relevant FFmpeg documentation confirms several behaviors that line up with
+FFX's needs:
+
+* FFmpeg documents ``-attach`` as adding an attachment stream to the output, and
+  explicitly names Matroska fonts used in subtitle rendering as an example.
+* FFmpeg documents attachment streams as regular streams that are created after
+  the mapped media streams.
+* FFmpeg documents ``-dump_attachment`` for extracting attachment streams, which
+  is useful for debugging or validating a source file's embedded fonts.
+* FFmpeg's Matroska example requires a ``mimetype`` metadata tag for attached
+  fonts, which is consistent with using attachment tags as detection signals.
+* FFmpeg also notes that attachments are implemented as codec extradata. That
+  helps explain why probe output for attachment streams can look different from
+  ordinary audio, video, and subtitle streams.
+
+Implication for FFX:
+
+* Attachment preservation is not an optional cosmetic feature for this format.
+  It is part of preserving the subtitle package correctly.
+
+Jellyfin Notes
+--------------
+
+Jellyfin's documentation also supports keeping this format intact:
+
+* Jellyfin's subtitle compatibility table lists ``ASS/SSA`` as supported in
+  ``MKV`` and not supported in ``MP4``.
+* Jellyfin notes that when subtitles must be transcoded, they are either
+  converted to a supported format or burned into the video, and burning them in
+  is the most CPU-intensive path.
+* Jellyfin's subtitle-extraction example for ``SSA/ASS`` first dumps attachment
+  streams and then extracts the ASS subtitle stream, which reflects the real
+  relationship between ASS subtitles and embedded fonts in MKV releases.
+* Jellyfin's font documentation says text-based subtitles require fonts to
+  render properly.
+* Jellyfin's configuration documentation says the web client uses configured
+  fallback fonts for ASS subtitles when other fonts such as MKV attachments or
+  client-side fonts are not available.
+
+Inference from the Jellyfin compatibility tables:
+
+* Keeping this subtitle format in Matroska is the safest interoperability choice
+  for Jellyfin consumers.
+* Converting the subtitle payload to WebVTT would lose styled ASS behavior.
+* Dropping the attachment streams would force client or fallback font
+  substitution and can change appearance or glyph coverage.
+
+References
+----------
+
+* FFmpeg documentation: https://ffmpeg.org/ffmpeg.html
+* Jellyfin codec support: https://jellyfin.org/docs/general/clients/codec-support/
+* Jellyfin configuration and fonts: https://jellyfin.org/docs/general/administration/configuration/
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..bb60bc9
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,25 @@
+FFX Documentation
+=================
+
+FFX is a local command-line and Textual terminal UI for inspecting TV episode
+files, storing normalization rules, and converting media into predictable
+archive-ready outputs.
+
+This documentation covers operator setup, day-to-day command usage, contributor
+workflow, format-specific notes, and generated API references for the smaller
+utility modules.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
+
+   installation
+   usage
+   file_formats
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contributor Guide
+
+   development
+   api
diff --git a/docs/installation.rst b/docs/installation.rst
new file mode 100644
index 0000000..a2bface
--- /dev/null
+++ b/docs/installation.rst
@@ -0,0 +1,52 @@
+Installation
+============
+
+FFX is designed for a Linux-like workstation with local command execution. The
+runtime media tools must be available on ``PATH``:
+
+* ``ffmpeg``
+* ``ffprobe``
+* ``cpulimit``
+
+User Bundle
+-----------
+
+The persistent user installation is prepared with the two-step flow described in
+the project README:
+
+.. code-block:: sh
+
+   bash tools/setup.sh
+   bash tools/configure_workstation.sh
+
+``tools/setup.sh`` creates the long-lived bundle virtualenv at
+``~/.local/share/ffx.venv`` and exposes the ``ffx`` command. The workstation
+script checks system tools and seeds local config directories.
+
+Local Test And Docs Environment
+-------------------------------
+
+Contributor test and documentation work uses the repo-local virtualenv:
+
+.. code-block:: sh
+
+   tests/prepare.sh
+
+The script creates ``.venv``, installs FFX in editable mode with test and docs
+extras, and verifies the Sphinx toolchain. Use check-only mode when you only
+want to inspect readiness:
+
+.. code-block:: sh
+
+   tests/prepare.sh --check
+
+Documentation Build
+-------------------
+
+After preparation, build the documentation with:
+
+.. code-block:: sh
+
+   .venv/bin/sphinx-build -b html docs docs/_build/html
+
+The generated site starts at ``docs/_build/html/index.html``.
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 0000000..2ec8f45
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,42 @@
+@ECHO OFF
+
+pushd %~dp0
+
+if "%SPHINXBUILD%" == "" if exist ..\.venv\Scripts\sphinx-build.exe (
+	set SPHINXBUILD=..\.venv\Scripts\sphinx-build.exe
+)
+if "%SPHINXBUILD%" == "" set SPHINXBUILD=sphinx-build
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo The 'sphinx-build' command was not found. Make sure Sphinx is installed,
+	echo then set SPHINXBUILD to the full path if needed.
+	exit /b 1
+)
+
+if "%1" == "" goto help
+if "%1" == "html" goto html
+if "%1" == "linkcheck" goto linkcheck
+echo.
+echo Unknown target "%1".
+goto help
+
+:html
+%SPHINXBUILD% -b html %SOURCEDIR% %BUILDDIR%\html %SPHINXOPTS%
+goto end
+
+:linkcheck
+%SPHINXBUILD% -b linkcheck %SOURCEDIR% %BUILDDIR%\linkcheck %SPHINXOPTS%
+goto end
+
+:help
+echo.
+echo Please use 'make.bat ^<target^>' where ^<target^> is one of
+echo   html       to make standalone HTML files
+echo   linkcheck  to check all external links for integrity
+
+:end
+popd
diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000..5599e8d
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,75 @@
+Usage
+=====
+
+FFX exposes a single ``ffx`` command with subcommands for inspection,
+conversion, metadata editing, setup, and maintenance.
+
+Inspect Files
+-------------
+
+Open the inspection workflow for one or more files:
+
+.. code-block:: sh
+
+   ffx inspect /path/to/episode.mkv
+
+Print resolved season-shift mappings without opening the TUI:
+
+.. code-block:: sh
+
+   ffx inspect --shift /path/to/episode.mkv
+
+Convert Files
+-------------
+
+Convert one or more source files using stored rules where available:
+
+.. code-block:: sh
+
+   ffx convert /path/to/episode.mkv
+
+Useful overrides include:
+
+* ``--no-pattern`` to skip database pattern matching
+* ``--show``, ``--season``, and ``--episode`` for explicit episode identity
+* ``--output-directory`` for generated output placement
+* ``--subtitle-directory`` and ``--subtitle-prefix`` for sidecar subtitle
+  imports
+* ``--copy-video`` or ``--copy-audio`` to preserve selected stream types
+* ``--rename-only`` for filename normalization without media rewriting
+
+Manage Shows And Patterns
+-------------------------
+
+Open the Textual interface for show and pattern management:
+
+.. code-block:: sh
+
+   ffx shows
+
+Extract Streams
+---------------
+
+Extract streams from a file:
+
+.. code-block:: sh
+
+   ffx unmux /path/to/episode.mkv
+
+For subtitle-only extraction:
+
+.. code-block:: sh
+
+   ffx unmux --subtitles-only --label show-name /path/to/episode.mkv
+
+Detect Crop
+-----------
+
+Ask FFmpeg to suggest crop parameters:
+
+.. code-block:: sh
+
+   ffx cropdetect /path/to/episode.mkv
+
+The default sampling window is controlled by the application defaults and can be
+overridden with command options.
diff --git a/pyproject.toml b/pyproject.toml
index 1d50c85..6a75f42 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -31,6 +31,12 @@ Issues = "https://gitea.maveno.de/Javanaut/ffx/issues"
 test = [
   "pytest",
 ]
+docs = [
+  "esbonio",
+  "sphinx",
+  "sphinx-copybutton",
+  "sphinx-rtd-theme",
+]
 
 [build-system]
 requires = [
diff --git a/tests/prepare.sh b/tests/prepare.sh
new file mode 100755
index 0000000..f5a3ec5
--- /dev/null
+++ b/tests/prepare.sh
@@ -0,0 +1,471 @@
+#!/usr/bin/env bash
+
+set -u
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd -- "${SCRIPT_DIR}/.." && pwd)"
+VENV_DIR="${FFX_TEST_VENV_DIR:-${ROOT_DIR}/.venv}"
+VENV_BIN_DIR="${VENV_DIR}/bin"
+VENV_PYTHON="${VENV_BIN_DIR}/python"
+VENV_PIP="${VENV_BIN_DIR}/pip"
+
+CHECK_ONLY=0
+READINESS_FAILURES=0
+INSTALL_FAILURES=0
+
+MISSING_REQUIRED_SYSTEM=()
+
+COLOR_RESET=""
+COLOR_GREEN=""
+COLOR_YELLOW=""
+COLOR_RED=""
+
+if [ -t 1 ]; then
+    COLOR_RESET="$(printf '\033[0m')"
+    COLOR_GREEN="$(printf '\033[32m')"
+    COLOR_YELLOW="$(printf '\033[33m')"
+    COLOR_RED="$(printf '\033[31m')"
+fi
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") [--check] [--help]
+
+Prepare the repo-local FFX test environment at:
+  ${VENV_DIR}
+
+Actions:
+  - verify or install required system commands for tests
+  - create or reuse the repo-local test virtualenv
+  - install this repository into the venv with Python test and docs extras
+
+Options:
+  --check  Report readiness only. Do not create, install, or modify.
+  --help   Show this help text.
+
+Environment overrides:
+  FFX_TEST_VENV_DIR  Override the test virtualenv path. Defaults to ${ROOT_DIR}/.venv.
+
+Notes:
+  - This script prepares a project-local test environment, not the persistent user bundle.
+  - The persistent bundle setup remains owned by tools/setup.sh.
+EOF
+}
+
+status_ok() {
+    printf '%sok%s' "${COLOR_GREEN}" "${COLOR_RESET}"
+}
+
+status_warn() {
+    printf '%swarn%s' "${COLOR_YELLOW}" "${COLOR_RESET}"
+}
+
+status_fail() {
+    printf '%sfailed%s' "${COLOR_RED}" "${COLOR_RESET}"
+}
+
+report_component() {
+    local level="$1"
+    local label="$2"
+    local detail="$3"
+    local rendered_status=""
+
+    case "${level}" in
+        ok)
+            rendered_status="$(status_ok)"
+            ;;
+        warn)
+            rendered_status="$(status_warn)"
+            ;;
+        *)
+            rendered_status="$(status_fail)"
+            ;;
+    esac
+
+    printf '[%s] %s%s\n' "${rendered_status}" "${label}" "${detail:+: $detail}"
+}
+
+command_exists() {
+    command -v "$1" >/dev/null 2>&1
+}
+
+check_python_venv_support() {
+    python3 -m venv --help >/dev/null 2>&1
+}
+
+check_system_command() {
+    command_exists "$1"
+}
+
+check_venv_python() {
+    [ -x "${VENV_PYTHON}" ]
+}
+
+check_venv_pip() {
+    check_venv_python && "${VENV_PIP}" --version >/dev/null 2>&1
+}
+
+check_venv_ffx() {
+    check_venv_python && "${VENV_PYTHON}" -m ffx version >/dev/null 2>&1
+}
+
+check_venv_pytest() {
+    check_venv_python && "${VENV_PYTHON}" -m pytest --version >/dev/null 2>&1
+}
+
+check_venv_sphinx() {
+    check_venv_python && "${VENV_BIN_DIR}/sphinx-build" --version >/dev/null 2>&1
+}
+
+check_venv_docs_packages() {
+    check_venv_python && "${VENV_PYTHON}" - <<'PY' >/dev/null 2>&1
+import esbonio
+import sphinx
+import sphinx_rtd_theme
+PY
+}
+
+check_editable_install() {
+    check_venv_python && FFX_REPO_ROOT="${ROOT_DIR}" "${VENV_PYTHON}" - <<'PY' >/dev/null 2>&1
+from __future__ import annotations
+
+import os
+from pathlib import Path
+import ffx
+
+repo_root = Path(os.environ["FFX_REPO_ROOT"]).resolve()
+package_path = Path(ffx.__file__).resolve()
+
+raise SystemExit(0 if repo_root in package_path.parents else 1)
+PY
+}
+
+check_python_environment_ready() {
+    check_venv_python &&
+        check_venv_pip &&
+        check_venv_pytest &&
+        check_venv_sphinx &&
+        check_venv_docs_packages &&
+        check_venv_ffx &&
+        check_editable_install
+}
+
+command_detail() {
+    command -v "$1" || printf "command '%s' not found" "$1"
+}
+
+python_venv_detail() {
+    if check_python_venv_support; then
+        printf 'python3 -m venv is available'
+    else
+        printf 'python3 venv support is unavailable'
+    fi
+}
+
+venv_python_detail() {
+    if check_venv_python; then
+        printf '%s' "${VENV_PYTHON}"
+    else
+        printf 'missing %s' "${VENV_PYTHON}"
+    fi
+}
+
+venv_pip_detail() {
+    if check_venv_pip; then
+        "${VENV_PIP}" --version
+    else
+        printf 'missing pip in %s' "${VENV_DIR}"
+    fi
+}
+
+venv_ffx_detail() {
+    if check_venv_ffx; then
+        printf 'ffx import and CLI entry are available'
+    else
+        printf 'ffx is not installed in %s' "${VENV_DIR}"
+    fi
+}
+
+venv_pytest_detail() {
+    if check_venv_pytest; then
+        "${VENV_PYTHON}" -m pytest --version 2>/dev/null | head -n 1
+    else
+        printf 'pytest is not installed in %s' "${VENV_DIR}"
+    fi
+}
+
+venv_sphinx_detail() {
+    if check_venv_sphinx; then
+        "${VENV_BIN_DIR}/sphinx-build" --version 2>&1
+    else
+        printf 'sphinx-build is not installed in %s' "${VENV_DIR}"
+    fi
+}
+
+venv_docs_packages_detail() {
+    if check_venv_docs_packages; then
+        printf 'Sphinx, Read the Docs theme, and Esbonio packages are importable'
+    else
+        printf 'one or more docs packages are missing in %s' "${VENV_DIR}"
+    fi
+}
+
+editable_install_detail() {
+    if check_editable_install; then
+        printf 'ffx resolves from %s' "${ROOT_DIR}"
+    else
+        printf 'ffx does not resolve from the project source tree'
+    fi
+}
+
+report_required_command() {
+    local label="$1"
+    local command_name="$2"
+
+    if check_system_command "${command_name}"; then
+        report_component ok "${label}" "$(command_detail "${command_name}")"
+    else
+        report_component failed "${label}" "$(command_detail "${command_name}")"
+        MISSING_REQUIRED_SYSTEM+=("${command_name}")
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+}
+
+print_system_status() {
+    MISSING_REQUIRED_SYSTEM=()
+
+    echo "System toolchain status:"
+    report_required_command "git" "git"
+    report_required_command "python3" "python3"
+
+    if check_system_command "python3" && check_python_venv_support; then
+        report_component ok "python3 venv" "$(python_venv_detail)"
+    else
+        report_component failed "python3 venv" "$(python_venv_detail)"
+        MISSING_REQUIRED_SYSTEM+=("python3-venv")
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    report_required_command "ffmpeg" "ffmpeg"
+    report_required_command "ffprobe" "ffprobe"
+    report_required_command "cpulimit" "cpulimit"
+}
+
+print_python_status() {
+    echo "Repo test and docs virtualenv status:"
+
+    if check_venv_python; then
+        report_component ok "test virtualenv" "$(venv_python_detail)"
+    else
+        report_component failed "test virtualenv" "$(venv_python_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_venv_pip; then
+        report_component ok "test pip" "$(venv_pip_detail)"
+    else
+        report_component failed "test pip" "$(venv_pip_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_venv_pytest; then
+        report_component ok "test pytest" "$(venv_pytest_detail)"
+    else
+        report_component failed "test pytest" "$(venv_pytest_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_venv_sphinx; then
+        report_component ok "docs sphinx" "$(venv_sphinx_detail)"
+    else
+        report_component failed "docs sphinx" "$(venv_sphinx_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_venv_docs_packages; then
+        report_component ok "docs packages" "$(venv_docs_packages_detail)"
+    else
+        report_component failed "docs packages" "$(venv_docs_packages_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_venv_ffx; then
+        report_component ok "test ffx" "$(venv_ffx_detail)"
+    else
+        report_component failed "test ffx" "$(venv_ffx_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+
+    if check_editable_install; then
+        report_component ok "editable source" "$(editable_install_detail)"
+    else
+        report_component failed "editable source" "$(editable_install_detail)"
+        READINESS_FAILURES=$((READINESS_FAILURES + 1))
+    fi
+}
+
+print_status_report() {
+    READINESS_FAILURES=0
+
+    print_system_status
+    echo
+    print_python_status
+}
+
+detect_package_manager() {
+    if command_exists apt-get; then
+        printf 'apt-get\n'
+        return 0
+    fi
+    if command_exists pacman; then
+        printf 'pacman\n'
+        return 0
+    fi
+    return 1
+}
+
+run_root_command() {
+    if [ "${EUID}" -eq 0 ]; then
+        "$@"
+    elif command_exists sudo; then
+        sudo -n "$@"
+    else
+        return 1
+    fi
+}
+
+install_system_requirements() {
+    local package_manager
+
+    if [ "${#MISSING_REQUIRED_SYSTEM[@]}" -eq 0 ]; then
+        return 0
+    fi
+
+    if ! package_manager="$(detect_package_manager)"; then
+        printf 'No supported package manager found for automatic system preparation.\n' >&2
+        INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+        return 1
+    fi
+
+    case "${package_manager}" in
+        apt-get)
+            printf 'Installing required system dependencies via apt-get...\n'
+            if ! run_root_command apt-get update; then
+                printf 'apt-get update failed or requires interactive sudo.\n' >&2
+                INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+                return 1
+            fi
+            if ! run_root_command apt-get install -y git python3 python3-venv ffmpeg cpulimit; then
+                printf 'apt-get install failed or requires interactive sudo.\n' >&2
+                INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+                return 1
+            fi
+            ;;
+        pacman)
+            printf 'Installing required system dependencies via pacman...\n'
+            if ! run_root_command pacman -Sy --noconfirm git python ffmpeg cpulimit; then
+                printf 'pacman install failed or requires interactive sudo.\n' >&2
+                INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+                return 1
+            fi
+            ;;
+    esac
+
+    return 0
+}
+
+ensure_test_venv() {
+    if ! check_venv_python; then
+        printf 'Creating repo test virtualenv at %s...\n' "${VENV_DIR}"
+        if ! python3 -m venv "${VENV_DIR}"; then
+            printf 'Failed to create test virtualenv at %s.\n' "${VENV_DIR}" >&2
+            INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+            return 1
+        fi
+    fi
+
+    if ! check_venv_pip; then
+        printf 'Missing pip in %s.\n' "${VENV_DIR}" >&2
+        INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+        return 1
+    fi
+
+    printf 'Installing FFX package with test and docs extras into %s...\n' "${VENV_DIR}"
+    if ! (
+        cd "${ROOT_DIR}" &&
+        "${VENV_PIP}" install --editable '.[test,docs]'
+    ); then
+        printf 'Failed to install FFX package with test and docs extras into %s.\n' "${VENV_DIR}" >&2
+        INSTALL_FAILURES=$((INSTALL_FAILURES + 1))
+        return 1
+    fi
+
+    return 0
+}
+
+parse_args() {
+    while [ "$#" -gt 0 ]; do
+        case "$1" in
+            --check)
+                CHECK_ONLY=1
+                ;;
+            --help|-h)
+                usage
+                exit 0
+                ;;
+            *)
+                printf 'Unknown option: %s\n\n' "$1" >&2
+                usage >&2
+                exit 2
+                ;;
+        esac
+        shift
+    done
+}
+
+main() {
+    parse_args "$@"
+
+    print_status_report
+
+    if [ "${CHECK_ONLY}" -eq 0 ]; then
+        if [ "${#MISSING_REQUIRED_SYSTEM[@]}" -gt 0 ]; then
+            echo
+            install_system_requirements
+        fi
+
+        if check_python_environment_ready; then
+            echo
+            report_component ok "Python package install" "repo test and docs virtualenv is already ready"
+        elif check_system_command "python3" && check_python_venv_support; then
+            echo
+            ensure_test_venv
+        fi
+
+        echo
+        print_status_report
+    fi
+
+    echo
+    if [ "${INSTALL_FAILURES}" -gt 0 ]; then
+        echo "One or more test preparation steps failed; see the status checks above." >&2
+        exit 1
+    fi
+
+    if [ "${READINESS_FAILURES}" -gt 0 ]; then
+        if [ "${CHECK_ONLY}" -eq 1 ]; then
+            echo "The FFX test and docs environment is incomplete." >&2
+        else
+            echo "Required test or docs components are still missing after preparation." >&2
+        fi
+        exit 1
+    fi
+
+    if [ "${CHECK_ONLY}" -eq 1 ]; then
+        echo "The FFX test and docs environment is ready."
+    else
+        echo "The FFX test and docs environment is prepared."
+    fi
+}
+
+main "$@"