Decouple hardware components into standalone services (#1413)

.github/workflows/docs.yml

@@ -0,0 +1,34 @@
+name: Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - develop
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+      - name: Install dependencies
+        run: uv sync --group docs
+      - name: Deploy MkDocs
+        if: github.event_name == 'push'
+        run: uv run mkdocs gh-deploy --force
+      - name: Build MkDocs
+        if: github.event_name == 'pull_request'
+        run: uv run mkdocs build --strict

.gitignore

@@ -57,3 +57,6 @@ temp*
 src/panoptes/pocs/_version.py
 json_store
 .junie
+
+# AI Agent Plans
+plans/

AGENTS.md

@@ -208,10 +208,10 @@ manage configuration. The server provides centralized configuration access acros
 
 ```bash
 # For normal development
-panoptes-config-server --host 0.0.0.0 --port 6563 run --config-file conf_files/pocs.yaml
+panoptes-utils config run --host 0.0.0.0 --port 6563 --config-file conf_files/pocs.yaml
 
 # For testing (use testing config)
-panoptes-config-server --host 0.0.0.0 --port 6563 run --config-file tests/testing.yaml
+panoptes-utils config run --host 0.0.0.0 --port 6563 --config-file tests/testing.yaml
 ```
 
 **Notes:**
@@ -416,7 +416,7 @@ panoptes-config-server --host 0.0.0.0 --port 6563 run --config-file tests/testin
 - **Test failures:** Fix on the release branch before merging to `main`.
 - **Twine check failures:** Usually due to missing or malformed metadata in `pyproject.toml`.
 
-**Automation Notes for AI Agents:**
+**Automation Notes for AI Agents (During Release Process):**
 
 - Parse version from `git describe --tags --abbrev=0`
 - Calculate next version based on changelog entries or commit messages
@@ -556,7 +556,10 @@ When making changes, update:
 - Architecture docs for structural changes
 - CLI guide for new commands
 - Examples for new features
+- All documentation must be written in Markdown for MkDocs. Do not use reStructuredText (.rst) or Sphinx.
 - A Changelog (`CHANGELOG.md`) entry should exist for every feature or bug fix. Minor changes (e.g., documentation updates, internal refactoring) may not require an entry.
+- All new entries should be added under an `## [Unreleased]` section at the top of the file. If this section does not exist, create it.
+- Do NOT create a new version heading for individual PRs; new version headings should only be created when performing a release.
 - Changelog entries should be categorized under appropriate sections (Added, Changed, Fixed, Removed) and reference PR
   numbers.
 - Changelog entries should be clear and concise, describing the change and its impact, ideally less than one line.
@@ -613,7 +616,7 @@ When making changes, update:
 
 ## Getting Help
 
-- **Documentation:** https://pocs.readthedocs.io
+- **Documentation:** https://panoptes.github.io/POCS/
 - **Forum:** https://forum.projectpanoptes.org
 - **Issues:** https://github.com/panoptes/POCS/issues
 - **Code of Conduct:** `CODE_OF_CONDUCT.md`
@@ -677,10 +680,10 @@ When making changes, update:
 
 ```bash
 # Start config server (required before running POCS)
-panoptes-config-server --host 0.0.0.0 --port 6563 run --config-file conf_files/pocs.yaml
+panoptes-utils config run --host 0.0.0.0 --port 6563 --config-file conf_files/pocs.yaml
 
 # Start config server for testing
-panoptes-config-server --host 0.0.0.0 --port 6563 run --config-file tests/testing.yaml
+panoptes-utils config run --host 0.0.0.0 --port 6563 --config-file tests/testing.yaml
 
 # Install dependencies
 uv sync

CHANGELOG.md

@@ -1,6 +1,23 @@
 # Changelog
 
-# Unreleased
+## [Unreleased]
+
+### Added
+
+- Added `pocs version` command to display the current version of `panoptes-pocs` and `panoptes-utils`.
+- Improved `pocs camera take-bias` organization: each run now uses its own timestamped subfolder for both raw frames and the master bias.
+
+### Changed
+
+- **Documentation Migration:** Transitioned from Sphinx/reStructuredText to MkDocs/Markdown with the Material theme. #1414
+- Updated `AGENTS.md` and `GEMINI.md` to mandate the use of Markdown and MkDocs for all future documentation.
+- Added GitHub Actions workflow for automated documentation deployment to GitHub Pages.
+
+### Fixed
+
+- Fixed `zsh-autosuggestions` not working in the `install-zsh.sh` script by ensuring history is configured before plugins are loaded. #1416
+- Fixed `pocs camera take-bias` processing all files in the bias directory instead of just the current run.
+- Fixed `namespaces = false` in `pyproject.toml` that broke the `panoptes` namespace package shared with `panoptes-utils`.
 
 ## 0.8.1 - 2026-03-20
 
@@ -10,6 +27,7 @@
 
 ### Added
 
+- Added ability to decouple POCS hardware (Mount, Camera, Scheduler) into standalone FastAPI services. Hardware objects can now run as remote servers using `panoptes.pocs.services.*_api` and be accessed by the Observatory using remote proxies (`panoptes.pocs.mount.remote`, `panoptes.pocs.camera.remote`, `panoptes.pocs.scheduler.remote`) by specifying their endpoints in `pocs.yaml`.
 - Calibration frame commands for taking bias frames and flat fields
     - `pocs camera take-bias`: Takes bias frames (zero exposure), stacks them, and reports statistics (default: 10 frames)
     - `pocs run take-flats`: Takes flat field images with automatic exposure adjustment and mount positioning
@@ -19,6 +37,9 @@
 
 ### Changed
 
+- Updated `conf_files/pocs-supervisord.conf`, `GEMINI.md`, `AGENTS.md`, and `README.md` to use the new `panoptes-utils config` subcommand instead of the removed `panoptes-config-server`.
+- Updated `conftest.py` to use the default POCS config server port `6563` (previously `8765`) for test setup.
+- Upgraded `panoptes-utils` dependency to `0.3.2`.
 - Upgraded `fastapi` from `<0.106.0` to the latest stable release (v0.135.1). #1408
 - Observation exposure time defaults: when `exptime` is not specified in field files, observations now use the 
   `cameras.defaults.exptime` configuration value instead of a hardcoded 120 seconds. This allows setting 
@@ -422,7 +443,7 @@ There are a lot of changes included in this release, highlights below:
     - Two docker containers run from the `aag-weather` image and have
       a `docker/docker-compose-aag.yaml` file to start.
 - Config items related to the configuration system have been moved to
-  the [Config Server](https://panoptes-utils.readthedocs.io/en/latest/#config-server)
+  the [Config Server](https://panoptes.github.io/panoptes-utils//en/latest/#config-server)
   in `panoptes-utils` repo.
     - The main interface for POCS related items is through
       `self.get_config`, which can take a key and a default, e.g.

GEMINI.md

@@ -10,15 +10,15 @@ Gemini CLI must rigorously adhere to the standards, workflows, and architectural
 
 - **Code Style:** Use Ruff for linting and formatting. Use double quotes and 110-character line limits.
 - **Type Safety:** Python 3.12+ type hints are required for all function signatures.
-- **Documentation:** Use Google-style docstrings for all public classes and functions.
+- **Documentation:** Use Google-style docstrings for all public classes and functions. All documentation must be written in Markdown for MkDocs. Do not use reStructuredText (.rst) or Sphinx.
 - **Testing:** Every change MUST include corresponding `pytest` tests. Maintain high coverage.
 - **Package Management:** Use `uv` for all dependency and environment management.
 - **Logging:** Use `loguru` via `self.logger` (from `PanBase`) or direct import for standalone utilities.
-- **Configuration:** The `panoptes-config-server` MUST be running for POCS or its tests to function correctly.
+- **Configuration:** The `panoptes-utils config` server MUST be running for POCS or its tests to function correctly.
 
 ## Project-Specific Workflow Mandates
 
-- **Changelog Requirement:** A `CHANGELOG.md` entry is required for **every feature or bug fix**. Minor changes (e.g., documentation tweaks, internal refactoring) do not necessarily require a changelog entry.
+- **Changelog Requirement:** A `CHANGELOG.md` entry is required for **every feature or bug fix**. All entries must be added under an `## [Unreleased]` section at the top of the file. Minor changes (e.g., documentation tweaks, internal refactoring) do not necessarily require a changelog entry.
 - **Commit Message Format:** Use the format `Brief description (#issue-number)`.
 - **Utility Preference:** ALWAYS check the [`panoptes-utils`](https://github.com/panoptes/panoptes-utils) library for existing functionality before implementing new utilities or importing external libraries.
 - **Simulator-First Testing:** POCS controls physical hardware. Always prioritize safety and use simulators for verification. Never bypass state machine transitions. Use the `--simulator` flag or appropriate configuration to ensure no real hardware commands are sent during development and testing.

README.md

@@ -8,7 +8,7 @@ Welcome to POCS documentation!
 
 [![GHA Status](https://github.com/panoptes/POCS/actions/workflows/pythontest.yaml/badge.svg?branch=develop)](https://github.com/panoptes/POCS/actions/workflows/pythontest.yaml)
 [![codecov](https://codecov.io/gh/panoptes/POCS/graph/badge.svg?token=0FGBB0iVy6)](https://codecov.io/gh/panoptes/POCS)
-[![Documentation Status](https://readthedocs.org/projects/pocs/badge/?version=latest)](https://pocs.readthedocs.io/en/latest/?badge=latest) 
+[![Documentation Status](https://img.shields.io/github/actions/workflow/status/panoptes/POCS/docs.yml?branch=main&label=docs)](https://panoptes.github.io/POCS//en/latest/?badge=latest) 
 [![PyPI version](https://badge.fury.io/py/panoptes-pocs.svg)](https://badge.fury.io/py/panoptes-pocs)
 
 # Project PANOPTES
@@ -27,7 +27,7 @@ about the project, including the science case and resources for interested indiv
 POCS (PANOPTES Observatory Control System) is the main software driver for a
 PANOPTES unit, responsible for high-level control of the unit.
 
-For more information, see the full documentation at: https://pocs.readthedocs.io.
+For more information, see the full documentation at: https://panoptes.github.io/POCS/.
 
 ## Beginner Resources
 
@@ -103,9 +103,9 @@ from panoptes.pocs.core import POCS
 
 os.environ['PANDIR'] = '/var/panoptes'
 conf_server = config_server('conf_files/pocs.yaml')
-I 01-20 01:01:10.886 Starting panoptes-config-server with  config_file='conf_files/pocs.yaml'
-S 01-20 01:01:10.926 Config server Loaded 17 top-level items
-I 01-20 01:01:10.928 Config items saved to flask config-server
+I 01-20 01:01:10.886 Starting panoptes-utils config server with config_file='conf_files/pocs.yaml'
+S 01-20 01:01:10.926 Config server loaded 17 top-level items
+I 01-20 01:01:10.928 Config items saved to server state
 I 01-20 01:01:10.934 Starting panoptes config server with localhost:6563
 
 pocs = POCS.from_config(simulators=['all'])
@@ -126,7 +126,7 @@ S 01-20 01:01:28.390 Unit says: Looks like we're missing some required hardware.
 Out[10]: False
 ```
 
-For a more realistic usage, see the full documentation at: [https://pocs.readthedocs.io](https://pocs.readthedocs.io).
+For a more realistic usage, see the full documentation at: [https://panoptes.github.io/POCS/](https://panoptes.github.io/POCS/).
 
 For actually deploying a PANOPTES unit, refer to the [Operating Guide](https://projectpanoptes.gitbook.io/pocs-user-guide/operation/operating-guides).
 
@@ -260,7 +260,7 @@ Links
 
 - PANOPTES Homepage: https://www.projectpanoptes.org
 - Forum: https://forum.projectpanoptes.org
-- Documentation: https://pocs.readthedocs.io
+- Documentation: https://panoptes.github.io/POCS/
 - Source Code: https://github.com/panoptes/POCS
 
 [Testing]: #testing

conf_files/pocs-supervisord.conf

@@ -12,7 +12,7 @@ environment=
 priority=1
 user=panoptes
 directory=/home/panoptes
-command=panoptes-config-server --host 0.0.0.0 --port 6563 run --config-file conf_files/pocs.yaml
+command=panoptes-utils config run --host 0.0.0.0 --port 6563 --config-file conf_files/pocs.yaml
 redirect_stderr=true
 stdout_logfile=/home/panoptes/logs/config-server.log
 autorestart=true
@@ -72,3 +72,39 @@ stdout_logfile=/home/panoptes/logs/metadata-uploader.log
 autostart=true
 stopasgroup=true
 killasgroup=true
+
+[program:pocs-mount-service]
+priority=10
+user=panoptes
+directory=/home/panoptes
+command=uvicorn --host 0.0.0.0 --port 8001 panoptes.pocs.services.mount_api:app
+redirect_stderr=true
+stdout_logfile=/home/panoptes/logs/mount-service.log
+autostart=true
+startsecs=5
+stopasgroup=true
+killasgroup=true
+
+[program:pocs-camera-service]
+priority=11
+user=panoptes
+directory=/home/panoptes
+command=uvicorn --host 0.0.0.0 --port 8002 panoptes.pocs.services.camera_api:app
+redirect_stderr=true
+stdout_logfile=/home/panoptes/logs/camera-service.log
+autostart=true
+startsecs=5
+stopasgroup=true
+killasgroup=true
+
+[program:pocs-scheduler-service]
+priority=12
+user=panoptes
+directory=/home/panoptes
+command=uvicorn --host 0.0.0.0 --port 8003 panoptes.pocs.services.scheduler_api:app
+redirect_stderr=true
+stdout_logfile=/home/panoptes/logs/scheduler-service.log
+autostart=true
+startsecs=5
+stopasgroup=true
+killasgroup=true

conftest.py

@@ -56,12 +56,13 @@
 def pytest_configure(config):
     """Set up the testing."""
     from astropy.utils.iers import conf
+
     conf.auto_max_age = None
     logger.info("Setting up the config server.")
     config_file = "tests/testing.yaml"
 
     host = "localhost"
-    port = "8765"
+    port = "6563"
 
     os.environ["PANOPTES_CONFIG_HOST"] = host
     os.environ["PANOPTES_CONFIG_PORT"] = port

docs/api.md

@@ -0,0 +1,3 @@
+# API Reference
+
+::: panoptes.pocs

docs/architecture-for-beginners.md

@@ -320,7 +320,7 @@ pocs.initialize()
 ## Getting Help
 
 - **Forum:** https://forum.projectpanoptes.org
-- **Docs:** https://pocs.readthedocs.io
+- **Docs:** https://panoptes.github.io/POCS/
 - **Code questions:** GitHub issues
 - **Live chat:** Join our community chat
 

docs/cli-guide.md

@@ -428,9 +428,9 @@ pocs run alignment --help
 
 - **New to POCS?** Read [Conceptual Overview](conceptual-overview.md)
 - **Want to understand the architecture?** See [Architecture for Beginners](architecture-for-beginners.md)
-- **Ready for Python API?** Check [examples/README.md](../examples/README.md)
+- **Ready for Python API?** Check [https://github.com/panoptes/POCS/blob/main/examples/README.md](https://github.com/panoptes/POCS/blob/main/examples/README.md)
 - **Need term definitions?** Browse the [Glossary](glossary.md)
 
 ---
 
-**Questions?** Check the main [README](../README.md) or visit the PANOPTES forum.
+**Questions?** Check the main [README](https://github.com/panoptes/POCS/blob/main/README.md) or visit the PANOPTES forum.

docs/conceptual-overview.md

@@ -178,10 +178,10 @@ But POCS hides most complexity behind simple interfaces.
 ### "Where do I start?"
 
 1. Read this document (you're doing it!)
-2. Run [examples/beginner_simulation.py](../examples/beginner_simulation.py)
-3. Explore [notebooks/TestPOCS.ipynb](../notebooks/TestPOCS.ipynb)
-4. Read [docs/architecture-for-beginners.md](architecture-for-beginners.md)
-5. Look at [src/panoptes/pocs/core.py](../src/panoptes/pocs/core.py)
+2. Run [https://github.com/panoptes/POCS/blob/main/examples/beginner_simulation.py](https://github.com/panoptes/POCS/blob/main/examples/beginner_simulation.py)
+3. Explore [https://github.com/panoptes/POCS/tree/main/notebooks](https://github.com/panoptes/POCS/tree/main/notebooks)
+4. Read [architecture-for-beginners.md](architecture-for-beginners.md)
+5. Look at [https://github.com/panoptes/POCS/blob/main/src/panoptes/pocs/core.py](https://github.com/panoptes/POCS/blob/main/src/panoptes/pocs/core.py)
 
 ### "What if I break something?"
 
@@ -196,7 +196,7 @@ With real hardware: POCS has safety checks:
 ### "How do I get help?"
 
 - **Forum**: https://forum.projectpanoptes.org (friendly community!)
-- **Documentation**: https://pocs.readthedocs.io
+- **Documentation**: https://panoptes.github.io/POCS/
 - **Code issues**: https://github.com/panoptes/POCS/issues
 - **Live chat**: Join via the forum
 
@@ -241,7 +241,7 @@ The CLI guide includes:
 
 After understanding these concepts:
 
-1. **Install POCS** - [Follow installation instructions in README](../README.md#install)
+1. **Install POCS** - [Follow installation instructions in README](https://github.com/panoptes/POCS/blob/main/README.md#install)
 2. **Configure your unit** - Run `pocs config setup`
 3. **Test hardware** - Use `pocs mount` and `pocs camera` commands
 4. **Run simulations** - Try `pocs run auto` with simulators