KumarLabJax · gbeane · Jun 19, 2026 · Jun 17, 2026 · Jun 19, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -13,7 +13,7 @@ CatBoost), and generates predictions. Supports Python 3.10-3.14.
 
 For comprehensive developer documentation, see `docs/development/development.md`
 (architecture deep-dives, detailed feature extraction guide, GUI architecture, release
-process) and `docs/development/contributing.md` (contribution guidelines, copyright
+process) and `CONTRIBUTING.md` (contribution guidelines, copyright
 assignment, PR process).
 
 ## File Protection Rules

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -73,9 +73,15 @@ Pre-commit hooks will automatically run these checks before each commit. If your
 ### Running Tests
 
 ```bash
-pytest              # Run all tests
+pytest              # Run the main (application) test suite
 pytest -v           # Verbose output
-pytest tests/path/  # Run specific tests
+pytest tests/path/  # Run a specific test directory or file
+
+# The reusable library packages have their own test suites; run them separately:
+pytest packages/jabs-core/tests
+pytest packages/jabs-io/tests
+pytest packages/jabs-behavior/tests
+pytest packages/jabs-vision/tests
 ```
 
 ## Types of Contributions Welcome
@@ -92,8 +98,8 @@ We welcome various types of contributions:
 
 For detailed information about JABS architecture, development setup, and implementation guides, see:
 
-- **[Development Guide](docs/DEVELOPMENT.md)** - Comprehensive guide to JABS architecture, feature extraction system, building, and deployment
-- **[User Guide](docs/user-guide.md)** - End-user documentation
+- **[Development Guide](https://kumarlabjax.github.io/JABS-behavior-classifier/development/development/)** - Comprehensive guide to JABS architecture, feature extraction system, building, and deployment
+- **[User Guide](https://kumarlabjax.github.io/JABS-behavior-classifier/user-guide/overview/)** - End-user documentation
 
 ## Pull Request Process
 
@@ -109,7 +115,7 @@ For detailed information about JABS architecture, development setup, and impleme
 
 - **General questions**: Open an issue on GitHub
 - **Security issues**: Email jabs@jax.org (do not open public issues)
-- **Development questions**: See [DEVELOPMENT.md](docs/development/DEVELOPMENT.md) or contact jabs@jax.org
+- **Development questions**: See the [Development Guide](https://kumarlabjax.github.io/JABS-behavior-classifier/development/development/) or contact jabs@jax.org
 
 ## Code of Conduct
 

diff --git a/docs/development/contributing.md b/docs/development/contributing.md
@@ -1,121 +1,6 @@
-# Contributing to JABS
-
-Thank you for your interest in contributing to JABS (JAX Animal Behavior System)! This document provides guidelines for contributing to the project.
-
-## Copyright and License
-
-**Important:** By contributing source code to JABS, you agree that your contributions will have their copyright assigned to The Jackson Laboratory.
-
-All code contributions become part of the JABS project and are subject to the project's license terms (see the LICENSE file in the repository root). JABS is released under the MIT License.
-
-## Quick Start for Contributors
-
-```bash
-# 1. Fork and clone the repository
-git clone https://github.com/YOUR_USERNAME/JABS-behavior-classifier.git
-cd JABS-behavior-classifier
-
-# 2. Install uv (Python package manager)
-curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS/Linux
-# OR: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows
-
-# 3. Set up development environment
-uv sync
-source .venv/bin/activate  # macOS/Linux (or .venv\Scripts\activate on Windows)
-pre-commit install
-
-# 4. Create a feature branch
-git checkout -b feature/my-feature
-
-# 5. Make your changes and commit
-git add .
-git commit -m "Description of changes"
-
-# 6. Run tests
-pytest
-
-# 7. Push and create a pull request
-git push origin feature/my-feature
-```
-
-## Contribution Guidelines
-
-Before submitting a contribution:
-
-1. **Follow the code style guidelines** - JABS uses Ruff for linting and formatting, and follows the Google docstring style.
-2. **Add tests** for new functionality
-3. **Update documentation** as needed (docstrings, user guide, developer guide)
-4. **Run the test suite** to ensure nothing is broken: `pytest`
-5. **Ensure pre-commit hooks pass** - They will run automatically when you commit
-6. **Submit a pull request** with a clear description of your changes
-
-### Code Style
-
-JABS uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting:
-
-```bash
-# Check for issues
-ruff check .
-
-# Auto-fix issues
-ruff check --fix .
-
-# Format code
-ruff format .
-```
-
-Pre-commit hooks will automatically run these checks before each commit. If your commit is blocked:
-
-1. Fix issues: `ruff check --fix . && ruff format .`
-2. Stage fixes: `git add -u`
-3. Try committing again
-
-### Running Tests
-
-```bash
-pytest              # Run all tests
-pytest -v           # Verbose output
-pytest tests/path/  # Run specific tests
-```
-
-## Types of Contributions Welcome
-
-We welcome various types of contributions:
-
-- **Bug fixes**: Help identify and fix issues
-- **New features**: Add new behavioral features, classifiers, or GUI improvements
-- **Documentation**: Improve user guides, developer documentation, or code comments
-- **Testing**: Add test coverage or improve existing tests
-- **Performance improvements**: Optimize code for better performance
-
-## Developer Documentation
-
-For detailed information about JABS architecture, development setup, and implementation guides, see:
-
-- **[Development Guide](development.md)** - Comprehensive guide to JABS architecture, feature extraction system, building, and deployment
-- **[User Guide](../user-guide/overview.md)** - End-user documentation
-
-## Pull Request Process
-
-1. **Create a feature branch** from `main`
-2. **Make your changes** with clear, focused commits
-3. **Update tests** and documentation
-4. **Ensure all tests pass** locally
-5. **Create a pull request** against the `main` branch
-6. **Wait for review** - Maintainers will review and may request changes
-7. **CI/CD checks must pass** - Automated checks will run on your PR
-
-## Questions?
-
-- **General questions**: Open an issue on GitHub
-- **Security issues**: Email jabs@jax.org (do not open public issues)
-- **Development questions**: See [DEVELOPMENT.md](docs/DEVELOPMENT.md) or contact jabs@jax.org
-
-## Code of Conduct
-
-Be respectful and professional in all interactions. We aim to foster an inclusive and welcoming community.
-
----
-
-**Thank you for contributing to JABS!**
+<!--
+This page intentionally transcludes the canonical contributing guide at the
+repository root. Edit /CONTRIBUTING.md, not this file.
+-->
 
+--8<-- "CONTRIBUTING.md"
diff --git a/docs/development/development.md b/docs/development/development.md
@@ -2,7 +2,7 @@
 
 Welcome to the JABS (JAX Animal Behavior System) development guide. This document provides detailed technical information about the software architecture, development setup, code organization, and implementation details.
 
-**📝 Looking to contribute?** See [CONTRIBUTING.md](../CONTRIBUTING.md) for contribution guidelines, copyright information, and how to submit pull requests.
+**📝 Looking to contribute?** See the [Contributing Guide](https://kumarlabjax.github.io/JABS-behavior-classifier/development/contributing/) for contribution guidelines, copyright information, and how to submit pull requests.
 
 **👤 End user?** See the [User Guide](user-guide.md) for instructions on using JABS.
 
@@ -57,7 +57,7 @@ pytest
 11. [Tips for Developers](#tips-for-developers)
 12. [Getting Help](#getting-help)
 
-**Note:** For contribution guidelines, copyright information, and how to submit pull requests, see [CONTRIBUTING.md](../CONTRIBUTING.md).
+**Note:** For contribution guidelines, copyright information, and how to submit pull requests, see the [Contributing Guide](https://kumarlabjax.github.io/JABS-behavior-classifier/development/contributing/).
 
 ---
 
@@ -75,9 +75,10 @@ pytest
 
 **Run tests**
 ```bash
-pytest                    # Run all tests
+pytest                    # Run the main (application) test suite
 pytest -v                 # Verbose output
-pytest tests/specific/    # Run specific tests
+pytest tests/specific/    # Run a specific test directory or file
+# Library packages have separate suites, e.g.: pytest packages/jabs-core/tests
 ```
 
 **Fix code style issues**
@@ -1025,7 +1026,7 @@ For most utilities, adding to `jabs-cli` is the better choice.
 ### Running Tests
 
 ```bash
-# Run all tests
+# Run the main (application) test suite
 pytest
 
 # Run with verbose output
@@ -1039,6 +1040,12 @@ pytest tests/test_pose_file.py::test_function_name
 
 # Run with coverage
 pytest --cov=src/jabs --cov-report=html
+
+# The reusable library packages have their own test suites; run them separately:
+pytest packages/jabs-core/tests
+pytest packages/jabs-io/tests
+pytest packages/jabs-behavior/tests
+pytest packages/jabs-vision/tests
 ```
 
 ### Writing Tests

diff --git a/pyproject.toml b/pyproject.toml
@@ -92,3 +92,11 @@ build-backend = "uv_build"
 [tool.uv.build-backend]
 namespace = true
 module-name = "jabs"
+
+[tool.pytest.ini_options]
+# Default to the application test suite under tests/. The reusable library packages
+# under packages/* have their own test suites and are run separately (e.g.
+# `pytest packages/jabs-core/tests`); collecting them together from the repo root
+# fails on cross-package test-module name collisions, which is why CI runs each
+# suite separately. Explicit path arguments override this default.
+testpaths = ["tests"]