docs/chore: JOSS pre-submission sanity pass — fix stale paths, version drift

Reviewer-facing docs (GETTING_STARTED_REVIEWERS.md, CONTRIBUTING.md) still
referenced the pre-restructure flat src/ layout (src/pipelines/, src/api/,
etc.) instead of src/videoannotator/*, including a nonexistent pipeline name,
a nonexistent test file, and a removed requirements.txt/main.py. pyproject.toml
had the same staleness: the mypy exclude list and several override module
names still pointed at src/* paths that no longer exist, silently turning
those excludes into no-ops.

CHANGELOG.md was missing entries for v1.4.3 and v1.4.4 even though both are
already released per pyproject.toml/CITATION.cff (1.4.4) and git tags;
backfilled from commit history.

Also finalizes the docs/development -> docs/archive move of
JOSS_VIEWER_HANDOVER.md (content unchanged, no remaining references to the
old path).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: InfantLab

CHANGELOG.md

@@ -15,6 +15,50 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Benchmark results and performance validation
 - Additional contributor documentation improvements
 
+## [1.4.4] - 2026-07-08
+
+### Modularity, Viewer Integration, and JOSS Resubmission
+
+This release responds to JOSS pre-review feedback (openjournals/joss-reviews#10182, #10183) on install footprint and the relationship between VideoAnnotator and Video Annotation Viewer.
+
+#### Added
+
+- **Bundled viewer**: The FastAPI service now serves Video Annotation Viewer's static build at `/viewer`, same-origin and zero-config (`VIDEOANNOTATOR_ENABLE_VIEWER` to disable). VAV remains fully usable standalone.
+- **Contract test**: Added `tests/contract/test_viewer_contract.py`, which validates VideoAnnotator's exporter output against VAV's actual Zod schemas.
+- **Roadmap docs**: Added `docs/development/roadmap_v1.6.0.md` (plugin ecosystem, local LLM/Ollama backend) and rewrote `roadmap_v1.5.0.md` around the modularity spec (`specs/003-modular-pipeline-architecture`).
+
+#### Fixed
+
+- **Person-tracking contract gap**: COCO output was missing `person_id`/`person_label`/`label_confidence`/`labeling_method` when identity labeling was disabled, which VAV requires as non-optional; added sensible fallback defaults and corrected the pipeline's self-declared schema for `image_id`.
+- **`setup-db` DetachedInstanceError**: `create_admin_user()` returned a detached SQLAlchemy ORM object after closing its session, raising `DetachedInstanceError` on the first command in the README quickstart; fixed with an explicit `db.refresh()`.
+- **Hidden CLI commands**: The `if __name__ == "__main__"` guard sat before `validate-emotion`, `generate-token`, and `setup-db` were registered, hiding them from `python -m videoannotator.cli --help`; moved the guard to the end of the file.
+
+#### Documentation
+
+- Fixed several stale version pins (`INSTALLATION.md` still titled "v1.2.0", `Docker.md`, `output_naming_conventions.md`).
+- Added the interface figure to the combined JOSS paper and documented the `/viewer` integration and contract test as evidence of coordinated maintenance between VideoAnnotator and VAV.
+- Corrected `CITATION.cff`, which was still stale at 1.4.2.
+
+## [1.4.3] - 2026-05-27
+
+### Installability and CI Green (JOSS #10182)
+
+#### Fixed
+
+- **Missing storage modules**: An unanchored `storage/` rule in `.gitignore` silently excluded `manager.py` and the `providers/` subpackage from the published package, breaking fresh-clone installs with `No module named videoannotator.storage.manager`.
+- **CI matrix**: Restricted the CUDA torch index to Linux so `uv sync` succeeds on macOS/Windows; pinned torch/torchvision/torchaudio to the matched 2.6.0 release; fixed macOS storage-path test assertions (symlink resolution); marked the Windows CI leg non-blocking pending a known SQLite teardown locking issue.
+- **Security scan**: Repaired the CI security-scan job (updated Trivy action, added SARIF write permission).
+- **Tests**: Cleared pre-existing storage and audio-diarization test failures — `delete_job` now returns a bool found/not-found signal, and diarization tests updated to pyannote's current `token=` kwarg.
+
+#### Changed
+
+- Bumped `openai-whisper` to `>=20250625` (sdist-only).
+- Repointed reviewer docs from the removed `scripts/verify_installation.py` to `videoannotator diagnose`.
+
+#### Documentation
+
+- Fixed ORCID format (bare 16-digit IDs) and added ByteTrack/CLIP DOIs for JOSS metadata checks.
+
 ## [1.4.2] - 2026-03-04
 
 ### JOSS Review Version

CONTRIBUTING.md

@@ -430,7 +430,7 @@ Contributors are recognized in:
 
 ```bash
 # Run with debug logging
-python main.py --log-level DEBUG
+uv run videoannotator --log-level DEBUG
 
 # Debug specific pipeline
 python -m pdb examples/test_individual_pipelines.py
@@ -440,7 +440,7 @@ python -m pdb examples/test_individual_pipelines.py
 
 ```bash
 # Profile performance
-python -m cProfile -o profile.stats main.py
+python -m cProfile -o profile.stats -m videoannotator.cli
 
 # Analyze with snakeviz
 snakeviz profile.stats
@@ -450,7 +450,7 @@ snakeviz profile.stats
 
 ### Adding a New Pipeline
 
-1. Create pipeline class in `src/pipelines/`
+1. Create pipeline class in `src/videoannotator/pipelines/`
 2. Implement `BasePipeline` interface
 3. Add configuration schema
 4. Create unit tests
@@ -461,7 +461,7 @@ snakeviz profile.stats
 ### Adding Dependencies
 
 1. Add to `pyproject.toml`
-2. Update `requirements.txt`
+2. Run `uv lock` to update `uv.lock`
 3. Test installation
 4. Update documentation
 

docs/GETTING_STARTED_REVIEWERS.md

@@ -13,7 +13,7 @@ This guide helps JOSS reviewers quickly evaluate VideoAnnotator's functionality,
 - 🔌 Modular pipeline architecture
 - 🚀 REST API + CLI interfaces
 - 📊 Standard output formats (COCO, WebVTT, RTTM)
-- 🧪 Comprehensive test coverage (195+ tests, >80%)
+- 🧪 Comprehensive test coverage (1000+ tests, >80%)
 - 🔒 Secure by default (API key authentication)
 
 **Repository**: [github.com/InfantLab/VideoAnnotator](https://github.com/InfantLab/VideoAnnotator)
@@ -103,7 +103,7 @@ Submit job:
 curl -X POST "http://localhost:18011/api/v1/jobs/" \
   -H "X-API-Key: $API_KEY" \
   -F "video=@sample.mp4" \
-  -F "selected_pipelines=openface3_identity"
+  -F "selected_pipelines=person,face,scene,audio"
 ```
 
 **Expected output**: Job created with `job_id`
@@ -181,14 +181,14 @@ ls -l reports/$JOB_ID/
 
 | Component | Purpose | Location |
 |-----------|---------|----------|
-| **API** | REST endpoints, authentication, CORS | `src/api/` |
-| **Pipelines** | Video processing implementations | `src/pipelines/` |
-| **Registry** | Pipeline discovery and metadata | `src/registry/` |
-| **Worker** | Job execution, cancellation, retries | `src/worker/` |
-| **Database** | Job state, metadata persistence | `src/database/` |
-| **Storage** | File management, results organization | `src/storage/` |
-| **Validation** | Config and input validation | `src/validation/` |
-| **Exporters** | Output format converters | `src/exporters/` |
+| **API** | REST endpoints, authentication, CORS | `src/videoannotator/api/` |
+| **Pipelines** | Video processing implementations | `src/videoannotator/pipelines/` |
+| **Registry** | Pipeline discovery and metadata | `src/videoannotator/registry/` |
+| **Worker** | Job execution, cancellation, retries | `src/videoannotator/worker/` |
+| **Database** | Job state, metadata persistence | `src/videoannotator/database/` |
+| **Storage** | File management, results organization | `src/videoannotator/storage/` |
+| **Validation** | Config and input validation | `src/videoannotator/validation/` |
+| **Exporters** | Output format converters | `src/videoannotator/exporters/` |
 
 ### Data Flow
 
@@ -207,14 +207,17 @@ ls -l reports/$JOB_ID/
 Pipelines are discovered via YAML metadata:
 
 ```yaml
-# src/registry/metadata/openface3_identity.yaml
-name: openface3_identity
-display_name: "OpenFace 3 - Identity"
-tasks: [face_detection, face_tracking, face_recognition]
-modalities: [video]
+# src/videoannotator/registry/metadata/face_openface3_embedding.yaml
+name: face_openface3_embedding
+display_name: OpenFace3 Face Embedding
+tasks:
+  - face-embedding
+modalities:
+  - image
+  - video
 outputs:
-  - format: COCO
-    types: [detection, tracking, recognition]
+  - format: JSON
+    types: [embeddings]
 ```
 
 ---
@@ -223,22 +226,22 @@ outputs:
 
 ### Where to Start Reading
 
-**1. API Endpoints** (`src/api/v1/jobs.py`) - 5 min
+**1. API Endpoints** (`src/videoannotator/api/v1/jobs.py`) - 5 min
 - REST API implementation
 - Job submission, status, results retrieval
 - Well-documented with examples
 
-**2. Pipeline Interface** (`src/pipelines/base.py`) - 3 min
+**2. Pipeline Interface** (`src/videoannotator/pipelines/base_pipeline.py`) - 3 min
 - Abstract base class for all pipelines
 - `initialize()`, `process()`, `cleanup()` methods
 - Standard interface contract
 
-**3. Registry System** (`src/registry/pipeline_registry.py`) - 3 min
+**3. Registry System** (`src/videoannotator/registry/pipeline_registry.py`) - 3 min
 - Dynamic pipeline discovery
 - Metadata loading and validation
 - Singleton pattern
 
-**4. Worker Execution** (`src/worker/executor.py`) - 5 min
+**4. Worker Execution** (`src/videoannotator/worker/job_processor.py`) - 5 min
 - Job execution logic
 - Error handling and retries
 - Cancellation support
@@ -247,14 +250,14 @@ outputs:
 - Unit tests: `tests/unit/`
 - Integration tests: `tests/integration/`
 - Pipeline tests: `tests/pipelines/`
-- 195+ tests with >80% coverage
+- 1000+ tests across 74 test files
 
 ### Code Quality Indicators
 
 ✅ **Type Hints**: Comprehensive type annotations
 ✅ **Docstrings**: All public APIs documented
 ✅ **Error Handling**: Consistent error envelope
-✅ **Testing**: 195+ tests, >80% coverage
+✅ **Testing**: 1000+ tests across 74 test files
 ✅ **Logging**: Structured logging throughout
 ✅ **Configuration**: Environment-based config
 ✅ **Security**: Secure-by-default (API keys, CORS)
@@ -269,7 +272,7 @@ uv run pytest -q
 uv run python scripts/validate_coverage.py --html
 
 # Run specific test file
-uv run pytest tests/unit/test_api_jobs.py -v
+uv run pytest tests/api/test_api_server.py -v
 
 # Run integration tests
 uv run pytest tests/integration/ -v
@@ -297,7 +300,7 @@ uv run pytest tests/integration/ -v
 ✅ **Example usage**: Multiple examples with expected outputs
 ✅ **API documentation**: Interactive Swagger UI + docstrings
 ✅ **Community guidelines**: CODE_OF_CONDUCT.md, CONTRIBUTING.md
-✅ **Tests**: 195+ tests, automated CI
+✅ **Tests**: 1000+ tests, automated CI
 ✅ **License**: MIT (open source)
 ✅ **Repository**: Clean, organized, active
 
@@ -309,8 +312,8 @@ uv run pytest tests/integration/ -v
 
 **A**: Three steps:
 
-1. Implement `BasePipeline` in `src/pipelines/your_pipeline/`
-2. Create YAML metadata in `src/registry/metadata/`
+1. Implement `BasePipeline` in `src/videoannotator/pipelines/your_pipeline/`
+2. Create YAML metadata in `src/videoannotator/registry/metadata/`
 3. Add tests in `tests/pipelines/`
 
 See [Pipeline Specifications](usage/pipeline_specs.md)

docs/development/JOSS_VIEWER_HANDOVER.md docs/archive/JOSS_VIEWER_HANDOVER.mddocs/development/JOSS_VIEWER_HANDOVER.md renamed to docs/archive/JOSS_VIEWER_HANDOVER.md

@@ -195,7 +195,7 @@ target-version = "py312"
 [tool.ruff.lint.per-file-ignores]
 "src/videoannotator/api/**/*.py" = ["B008"]
 "src/videoannotator/cli.py" = ["B008", "B904"]
-"src/batch/batch_orchestrator.py" = ["RUF013"]
+"src/videoannotator/batch/batch_orchestrator.py" = ["RUF013"]
 
 [tool.mypy]
 python_version = "3.12"
@@ -212,16 +212,15 @@ no_implicit_optional = false
 
 # Exclude files/patterns from mypy checking (reduces noise from ML/storage modules)
 exclude = [
-    "src/pipelines/",
-    "src/storage/models.py",
-    "src/storage/file_backend.py",
-    "src/utils/person_identity.py",
-    "src/utils/automatic_labeling.py",
-    "src/utils/size_based_person_analysis.py",
-    "src/utils/logging_config.py",
-    "src/version.py",
-    "src/exporters/native_formats.py",
-    "src/schemas/",
+    "src/videoannotator/pipelines/",
+    "src/videoannotator/storage/models.py",
+    "src/videoannotator/storage/file_backend.py",
+    "src/videoannotator/utils/person_identity.py",
+    "src/videoannotator/utils/automatic_labeling.py",
+    "src/videoannotator/utils/size_based_person_analysis.py",
+    "src/videoannotator/utils/logging_config.py",
+    "src/videoannotator/exporters/native_formats.py",
+    "src/videoannotator/schemas/",
     "examples/",
     "scripts/",
 ]
@@ -360,27 +359,27 @@ ignore_missing_imports = true
 # speech pipeline interacts with heavy third-party speech libraries (whisper, torch) that
 # produce large, environment-dependent typing noise. Relax checks for this module while
 # keeping API modules strict.
-module = ["pipelines.audio_processing.speech_pipeline"]
+module = ["videoannotator.pipelines.audio_processing.speech_pipeline"]
 ignore_errors = true
 
 [[tool.mypy.overrides]]
 # Storage modules use SQLAlchemy models and runtime-mapped attributes
-module = "storage.*"
+module = "videoannotator.storage.*"
 ignore_errors = true
 
 [[tool.mypy.overrides]]
 # Pipeline modules interact with heavy ML libraries (incomplete/dynamic typing)
-module = "pipelines.*"
+module = "videoannotator.pipelines.*"
 ignore_errors = true
 
 [[tool.mypy.overrides]]
 # Utility modules with complex dynamic typing patterns
-module = "utils.*"
+module = "videoannotator.utils.*"
 ignore_errors = true
 
 [[tool.mypy.overrides]]
 # Version module has dynamic git-based logic
-module = "version"
+module = "videoannotator.version"
 ignore_errors = true
 
 [[tool.mypy.overrides]]
@@ -395,10 +394,10 @@ ignore_errors = true
 
 [[tool.mypy.overrides]]
 # Exporters work with dynamic data structures
-module = "exporters.*"
+module = "videoannotator.exporters.*"
 ignore_errors = true
 
 [[tool.mypy.overrides]]
 # Schemas module has placeholder types
-module = "schemas"
+module = "videoannotator.schemas"
 ignore_errors = true