BrianJKoopman · Sep 28, 2026 · Sep 22, 2026 · Sep 22, 2026 · Sep 23, 2026 · Sep 23, 2026
@@ -12,15 +12,24 @@
 <!--- Include details of your testing environment, tests ran to see how -->
 <!--- your change affects other areas of the code, etc. -->
 
-## Types of changes
-<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+## Labels for Types of changes
+<!--- What types of changes does your code introduce? --->
+<!--- Please select the appropriate label(s) in the sidebar from the list below. --->
+<!--- Remove this section when done. --->
+- "ai assisted" - code was developed with AI assistance
+- "breaking" - fix or feature that would cause existing functionality to not work as expected
+- "bug fix" - non-breaking change which fixes an issue
+- "cleanup" - refactoring or other cleanup, no new features
+- "documentation" - documentation only changes, no functionality changes
+- "enhancement" - non-breaking change which adds functionality
+- "new agent" - introduce a new agent to the repo
 
 ## Checklist:
 <!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
 <!--- If you're unsure about any of these, don't hesitate to ask. We're here to help! -->
 - [ ] My code follows the code style of this project.
-- [ ] My change requires a change to the documentation.
-- [ ] I have updated the documentation accordingly.
+- [ ] I have updated related documentation _or_ an update to the documentation is not required.
+
+## AI Usage Disclosure
+<!--- Please state whether or not AI tools were used during development. --->
+<!--- Include details about what tools were used and how. --->
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -5,32 +5,8 @@ Contributing to SOCS
 Branches
 --------
 
-Following release v0.4.1, socs now has a single ``main`` branch, which replaces
-the old ``master`` and ``develop`` branch model, described below. ``main``
-functions like ``develop`` used to, and is the new default branch. Feature
-branches should be based off of the latest ``main``, and pull requests should
-be made into ``main``.
-
-Users that want a "stable" installation of socs should install from PyPI and/or
-use tagged Docker images corresponding to the targeted release, i.e. v0.4.1.
-Installing from source (i.e. from the ``main`` branch) comes with the usual
-caveats of potential instability.
-
-Old Branching Model
-```````````````````
-    **Note:** This branching model is no longer used, but the description is
-    left here while we transition to the new one.
-
-There are two long-lived branches in SOCS, ``master`` and ``develop``.
-``master`` should be considered stable, and will only move forward on official
-releases. ``develop`` may be unstable, and is where all development should take
-place. This branching model follows the one in the OCS_ repository.
-
-What this means for you, the contributor, is that you should base your feature
-branches off of the latest ``develop`` branch, and pull request them into
-``develop``. Detailed steps below.
-
-.. _OCS: https://github.com/simonsobs/ocs
+socs has a single ``main`` branch Feature branches should be based off of the
+latest ``main``, and pull requests should be made into ``main``.
 
 Pull Requests
 -------------
@@ -46,31 +22,60 @@ submit a PR from there. See the `GitHub documentation
 <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_
 for details on how to do so.
 
-Releases
---------
+PR Template
+```````````
+When you open a PR, a template will automatically populate the text field. Please
+fill out all sections of the template.
 
-    **Note:** Releases will be issued by core maintainers of SOCS.
+Force Pushes
+````````````
+Please refrain from force pushing a rebase onto a branch after marking your PR
+ready for review, unless requested to do so by a maintainer. Doing so makes it
+difficult for the reviewers to follow changes you have made in response to the
+review.
 
-If you are trying to issue a release of SOCS you should follow these steps:
+AI Usage
+````````
+Use of AI tools is allowed under the Simons Observatory `AI Governance
+Policy`_, provided the usage is disclosed. Before submitting a PR with AI
+generated code, please make sure to read the AI policy and follow the
+guidelines within.
 
-1. Test the release properly builds and publishes with a pre-release. You can
-   do so by pushing a tag matching ``v0.*.*a*``, ``v0.*.*b*``, or
-   ``v0.*.*rc*``.
-2. If no new commits are made following a pre-release, remove the pre-release
-   tag. Multiple tags may prevent the official release from publishing properly.
-3. Use the GitHub releases interface to draft a new release, creating a new tag
-   targeting the ``main`` branch.
-4. Write the release notes. Make use of the "Generate release notes" feature.
-   It is helpful to organize these into sections as done in past releases. Be
-   sure to highlight any breaking changes and include instructions for any
-   actions users must take when updating.
+As a way of marking which Agents were developed with and without AI assistance,
+the Agent reference pages should contain one of two badges:
+
+.. image:: https://img.shields.io/badge/AI-assisted-orange
+   :alt: Agent written with AI assistance
+
+::
+
+    .. image:: https://img.shields.io/badge/AI-assisted-orange
+       :alt: Agent written with AI assistance
+
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
+::
+
+    .. image:: https://img.shields.io/badge/AI-free-green
+       :alt: Agent written without AI assistance
+
+You must also include the following comment at the top of every source file
+that was generated using AI::
+
+    # Code developed with AI assistance.
+
+Most agents in this repo pre-date AI tools, and so contain AI free code, to the
+best of the maintainer's knowledge.
+
+.. _AI Governance Policy: https://simonsobservatory.org/wp-content/uploads/2026/08/Digital_Assets_Policy_20260811.pdf
 
 Development Guide
 -----------------
 
 Contributors should follow the recommendations made in the `SO Developer Guide`_.
 
-.. _SO Developer Guide: https://simons1.princeton.edu/docs/so_dev_guide/
+.. _SO Developer Guide: https://simonsobs-dev-guide.readthedocs.io/en/latest/
 
 pre-commit
 ``````````
@@ -82,7 +87,7 @@ when submitting pull requests.
 You should set this up before making and committing your changes. To do so make
 sure the ``pre-commit`` package is installed (it is in ``requirements.txt``)::
 
-    $ pip install -r requirements.txt
+    $ python -m pip install -r requirements.txt
 
 Then run::
 
@@ -91,8 +96,8 @@ Then run::
 This will install the configured git hooks and any dependencies. Now, whenever
 you commit the hooks will run. If there are issues you will see them in the
 output. This may automatically make changes to your staged files.  These
-changes will be unstaged and need to be reviewed (typically with a ``git
-diff``), restaged, and recommitted. For example, if you have trailing
+changes will be unstaged and need to be reviewed (typically with a ``git diff``),
+restaged, and recommitted. For example, if you have trailing
 whitespace on a line, pre-commit will prevent the commit and remove the
 whitespace. You will then stage the new changes with another ``git add <file>``
 and then re-run the commit. Here is the expected git output for this example:
@@ -133,3 +138,27 @@ and then re-run the commit. Here is the expected git output for this example:
     $ git commit
 
 .. _pre-commit: https://pre-commit.com/
+
+For Repo Maintainers
+--------------------
+
+The following sections are only relevant for repo maintainers.
+
+Releases
+````````
+
+    **Note:** Releases will be issued by core maintainers of SOCS.
+
+If you are trying to issue a release of SOCS you should follow these steps:
+
+1. Test the release properly builds and publishes with a pre-release. You can
+   do so by pushing a tag matching ``v0.*.*a*``, ``v0.*.*b*``, or
+   ``v0.*.*rc*``.
+2. If no new commits are made following a pre-release, remove the pre-release
+   tag. Multiple tags may prevent the official release from publishing properly.
+3. Use the GitHub releases interface to draft a new release, creating a new tag
+   targeting the ``main`` branch.
+4. Write the release notes. Make use of the "Generate release notes" feature.
+   It is helpful to organize these into sections as done in past releases. Be
+   sure to highlight any breaking changes and include instructions for any
+   actions users must take when updating.
diff --git a/README.rst b/README.rst
@@ -20,19 +20,19 @@ Installation
 
 Install and update with pip::
 
-    $ pip3 install -U socs
+    $ python -m pip install -U socs
 
 You may install optional dependencies by including one or more agent group
 names on installation, for example::
 
-    $ pip3 install -U socs[labjack,synacc]
+    $ python -m pip install -U socs[labjack,synacc]
 
 For a complete list of agent groups see the `Installation Documentation`_.
 
 If you would like to install all optional dependencies use the special varient
 "all"::
 
-    $ pip3 install -U socs[all]
+    $ python -m pip install -U socs[all]
 
 **Note:** Not all optional dependencies can be installed this way. See the
 `Installation Documentation`_ for more info on specific agent dependencies.
@@ -48,10 +48,10 @@ and install using pip:
 
 .. code-block:: bash
 
-    git clone https://github.com/simonsobs/socs.git
-    cd socs/
-    pip3 install -r requirements.txt
-    pip3 install .
+    $ git clone https://github.com/simonsobs/socs.git
+    $ cd socs/
+    $ python -m pip install -r requirements.txt
+    $ python -m pip install .
 
 Docker Images
 -------------
@@ -74,9 +74,9 @@ The SOCS documentation can be built using Sphinx. There is a separate
 ``requirements.txt`` file in the ``docs/`` directory to install Sphinx and any
 additional documentation dependencies::
 
-  cd docs/
-  pip3 install -r requirements.txt
-  make html
+    $ cd docs/
+    $ python -m pip install -r requirements.txt
+    $ make html
 
 You can then open ``docs/_build/html/index.html`` in your preferred web
 browser. You can also find a copy hosted on `Read the Docs`_.
@@ -88,16 +88,16 @@ Tests
 The tests for SOCS are run using pytest, and should be run from the
 ``tests/`` directory::
 
-  $ cd tests/
-  $ python3 -m pytest --cov
+    $ cd tests/
+    $ python -m pytest --cov
 
 For more details see `tests/README.rst <tests_>`_.
 
 .. _tests: https://github.com/simonsobs/socs/blob/main/tests/README.rst
 
 Contributing
 ------------
-For guidelines on how to contribute to OCS see `CONTRIBUTING.rst`_.
+For guidelines on how to contribute to SOCS see `CONTRIBUTING.rst`_.
 
 .. _CONTRIBUTING.rst: https://github.com/simonsobs/socs/blob/main/CONTRIBUTING.rst
 

diff --git a/docs/agents/acu_agent.rst b/docs/agents/acu_agent.rst
@@ -6,6 +6,9 @@
 ACU Agent
 =========
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 The Antenna Control Unit (ACU) is an industrial PC with VxWorks installed.
 It is used for readout of encoder measurements and control of telescope
 platforms.

diff --git a/docs/agents/bluefors_agent.rst b/docs/agents/bluefors_agent.rst
@@ -6,6 +6,9 @@
 Bluefors Agent
 ==============
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 The Bluefors Agent is an OCS Agent which tracks the contents of the Bluefors
 logs and passes them to the live monitor and to the OCS housekeeping data
 aggregator.

diff --git a/docs/agents/cryomech_cpa.rst b/docs/agents/cryomech_cpa.rst
@@ -6,6 +6,9 @@
 Cryomech CPA Agent
 ==================
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 The Cryomech CPA compressor is a commonly used compressor model for the
 pulse tubes within SO. The CPA Agent interfaces with the compressor over
 ethernet to monitor the health of the unit, including stats such as Helium

diff --git a/docs/agents/devantech_dS378.rst b/docs/agents/devantech_dS378.rst
@@ -6,6 +6,9 @@
 Devantech dS378 Agent
 ========================
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 This agent is designed to interface with devantech's dS378 ethernet relay.
 
 

diff --git a/docs/agents/fls.rst b/docs/agents/fls.rst
@@ -6,6 +6,9 @@
 FLS Agent
 =========
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 The Frequency-selectable Laser Source (FLS) is a calibrator that uses the
 Toptica TeraScan 1550 laser system, installed in a setup with attenuating
 prisms and mirrors. The calibrator is used for passband measurements with

diff --git a/docs/agents/fts_agent.rst b/docs/agents/fts_agent.rst
@@ -6,6 +6,9 @@
 FTS Aerotech Agent
 ==================
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 This agent is used to communicate with the FTS mirror stage for two FTSs with
 Aerotech motion controllers.
 

diff --git a/docs/agents/galil_axis.rst b/docs/agents/galil_axis.rst
@@ -6,6 +6,9 @@
 Galil Axis Agent
 ================
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 The Galil Axis Agent provides motion control and telemetry readout for
 the Galil DMC motor controller. When used in the Simons Observatory SAT Coupling
 Optics system, the agent controls four axes—two linear and two angular—that move

diff --git a/docs/agents/generator.rst b/docs/agents/generator.rst
@@ -6,6 +6,9 @@
 Generator Agent
 ====================
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 The Generator Agent is an OCS Agent which monitors on-site generators via Modbus.
 
 .. argparse::

diff --git a/docs/agents/hi6200.rst b/docs/agents/hi6200.rst
@@ -6,6 +6,9 @@
 Hi6200 Agent
 ==============
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 This agent uses Modbus TCP to communicate with the Hi6200 Weight Sensor.
 This agent uses ModbusClient from pyModbusTCP to facilitate the communication.
 The agent is able to communicate over ethernet to read and monitor the net and

diff --git a/docs/agents/holo_fpga.rst b/docs/agents/holo_fpga.rst
@@ -6,6 +6,9 @@
 Holography FPGA Agent
 ========================
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 The Holography FPGA Agent is provided with OCS to help demonstrate and debug
 issues with the holography ROACH2 FPGA. It will connect the computer to the
 ROACH via an ethernet port, take data, and pass it to the OCS feed.

diff --git a/docs/agents/holo_synth.rst b/docs/agents/holo_synth.rst
@@ -6,6 +6,9 @@
 Holography Synthesizer Agent
 =============================
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 The Holography Synthesizer Agent is provided with OCS to help demonstrate and
 debug issues with the holography synthesizers. The synthesizers provide a
 signal at a desired frequency for holography measurements. This agent will

diff --git a/docs/agents/http_camera.rst b/docs/agents/http_camera.rst
@@ -6,6 +6,9 @@
 HTTP Camera Agent
 ====================
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 The HTTP Camera Agent is an OCS Agent which grabs screenshots from cameras
 using HTTP requests and saves files to a directory.
 

diff --git a/docs/agents/hwp_encoder.rst b/docs/agents/hwp_encoder.rst
@@ -6,6 +6,9 @@
 HWP Encoder BBB Agent
 =====================
 
+.. image:: https://img.shields.io/badge/AI-free-green
+   :alt: Agent written without AI assistance
+
 The optical encoder signals of the CHWP are captured by Beaglebone Black (BBB)
 boards with the IRIG-B timing reference.
 This agent receives and decodes UDP packets from BBB and publishes the data