openc3 7.4.1 → 7.5.1

data/lib/openc3/utilities/target_file.rb

@@ -31,6 +31,15 @@ module OpenC3
       name.sub(/\*$/, '')
     end
 
+    # Reject names that could resolve outside the scope's targets_modified
+    # directory. The bucket normalizes '..' segments in keys just like the
+    # filesystem does, so this must be checked before any bucket call.
+    def self.validate_name(name)
+      unless OpenC3::LocalMode.safe_key?(name)
+        raise ArgumentError, "Invalid target file name: #{name.inspect}"
+      end
+    end
+
     def self.all(scope, path_matchers, target: nil)
       target = target.upcase if target
 
@@ -46,14 +55,26 @@ module OpenC3
         prefix = "#{scope}/targets/"
         modified_prefix = "#{scope}/targets_modified/"
       end
-      result, _ = remote_target_files(bucket_client: bucket, prefix: prefix, include_temp: false, path_matchers: path_matchers)
-      modified, temp = remote_target_files(bucket_client: bucket, prefix: modified_prefix, include_temp: include_temp, path_matchers: path_matchers)
+      if target and OpenC3::LocalMode.local_only_target?(target)
+        # Local only targets are never listed from the bucket
+        result = Set.new
+        modified = Set.new
+        temp = Set.new
+      else
+        result, _ = remote_target_files(bucket_client: bucket, prefix: prefix, include_temp: false, path_matchers: path_matchers)
+        modified, temp = remote_target_files(bucket_client: bucket, prefix: modified_prefix, include_temp: include_temp, path_matchers: path_matchers)
+      end
 
       # Add in local targets_modified if present
-      if ENV['OPENC3_LOCAL_MODE']
+      if ENV['OPENC3_LOCAL_MODE'] or !OpenC3::LocalMode.local_only_targets.empty?
         local_modified = OpenC3::LocalMode.local_target_files(scope: scope, target: target, path_matchers: path_matchers, include_temp: include_temp)
         local_modified.each do |filename|
-          if include_temp and filename.include?(TEMP_FOLDER)
+          if OpenC3::LocalMode.local_only_name?(filename)
+            # The local file is the only copy so it isn't marked as modified
+            result << filename
+          elsif !ENV['OPENC3_LOCAL_MODE']
+            next
+          elsif include_temp and filename.include?(TEMP_FOLDER)
             temp << filename
           else
             modified << filename unless modified.include?(filename)
@@ -100,16 +121,14 @@ module OpenC3
 
     def self.body(scope, name)
       name = strip_modified(name) # Remove '*' that indicates modified
+      # Local only targets are read from the local mode volume and never the bucket
+      if OpenC3::LocalMode.local_only_name?(name)
+        return local_body(scope, name)
+      end
       # First try opening a potentially modified version by looking for the modified target
       if ENV['OPENC3_LOCAL_MODE']
-        local_file = OpenC3::LocalMode.open_local_file(name, scope: scope)
-        if local_file
-          if File.extname(name) == ".bin"
-            return local_file.read
-          else
-            return local_file.read.force_encoding('UTF-8')
-          end
-        end
+        text = local_body(scope, name)
+        return text if text
       end
 
       bucket = Bucket.getClient()
@@ -136,6 +155,11 @@ module OpenC3
       # file listing, not a name any caller means to write. Remove it to avoid 
       # creating a file with a '*' in the name.
       name = strip_modified(name)
+      validate_name(name)
+      if OpenC3::LocalMode.local_only_name?(name)
+        OpenC3::LocalMode.put_target_file("#{scope}/targets_modified/#{name}", text, scope: scope)
+        return true
+      end
       if ENV['OPENC3_LOCAL_MODE']
         OpenC3::LocalMode.put_target_file("#{scope}/targets_modified/#{name}", text, scope: scope)
       end
@@ -163,6 +187,11 @@ module OpenC3
       # Match body/create so deleting a name taken straight from a listing
       # removes the file the user actually picked
       name = strip_modified(name)
+      validate_name(name)
+      if OpenC3::LocalMode.local_only_name?(name)
+        OpenC3::LocalMode.delete_local("#{scope}/targets_modified/#{name}")
+        return true
+      end
       if ENV['OPENC3_LOCAL_MODE']
         OpenC3::LocalMode.delete_local("#{scope}/targets_modified/#{name}")
       end
@@ -177,6 +206,20 @@ module OpenC3
 
     # protected
 
+    def self.local_body(scope, name)
+      local_file = OpenC3::LocalMode.open_local_file(name, scope: scope)
+      return nil unless local_file
+      begin
+        if File.extname(name) == ".bin"
+          local_file.read
+        else
+          local_file.read.force_encoding('UTF-8')
+        end
+      ensure
+        local_file.close
+      end
+    end
+
     def self.remote_target_files(bucket_client:, prefix:, include_temp: false, path_matchers: nil)
       result = Set.new
       temp = Set.new
@@ -191,6 +234,8 @@ module OpenC3
           temp << split_key[2..-1].join('/') if include_temp
           next
         end
+        # Local only targets are never read from the bucket
+        next if OpenC3::LocalMode.local_only_target?(split_key[2])
 
         if path_matchers
           found = false

data/lib/openc3/utilities/topic_lag_monitor.rb

@@ -0,0 +1,193 @@
+# encoding: ascii-8bit
+
+# Copyright 2026 OpenC3, Inc.
+# All Rights Reserved.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE.md for more details.
+#
+# This file may also be used under the terms of a commercial license
+# if purchased from OpenC3, Inc.
+
+require 'openc3/utilities/logger'
+
+module OpenC3
+  # Tracks how far a microservice is behind the Redis streams it consumes.
+  #
+  # Every processed message updates the lag gauge metric with the maximum lag
+  # seen over the last metric update interval. When the lag crosses the warning
+  # or critical threshold a user notification is published, and a recovery
+  # notification is published once the microservice has caught back up (with
+  # hysteresis so a lag hovering around a threshold doesn't flap).
+  #
+  # Streams are trimmed by time once their data is logged, so a consumer can
+  # only skip trimmed data after lagging far past the critical threshold.
+  #
+  # Recovery assumes each monitor is fed by a single reader that reads every
+  # stream with pending entries on each XREAD (COUNT limits how many entries
+  # but not which streams). A backlogged topic then reports its high lag every
+  # read cycle, so fresh messages on other topics can't clear the alert early.
+  class TopicLagMonitor
+    OK = 0
+    WARN = 1
+    CRITICAL = 2
+
+    # Lag must drop below threshold * CLEAR_RATIO to count as recovering
+    CLEAR_RATIO = 0.5
+    # Matches Metric::UPDATE_INTERVAL so every lag spike is published
+    GAUGE_WINDOW_SECONDS = 5.0
+
+    attr_reader :state
+
+    # Lag in seconds that triggers the warning and critical notifications.
+    # A warning <= 0 disables notifications. Also used by Data Flows so its
+    # indicators match the notifications.
+    def self.thresholds
+      {
+        'warning' => env_float('OPENC3_LAG_WARN_SECONDS', 5.0),
+        'critical' => env_float('OPENC3_LAG_CRITICAL_SECONDS', 30.0),
+      }
+    end
+
+    def self.env_float(name, default)
+      value = ENV.fetch(name, '').strip
+      return default if value.empty?
+      Float(value)
+    rescue ArgumentError
+      default
+    end
+
+    def initialize(name:, logger:, metric: nil)
+      @name = name
+      @logger = logger
+      @metric = metric
+      thresholds = self.class.thresholds
+      @warn_seconds = thresholds['warning']
+      @critical_seconds = thresholds['critical']
+      @clear_seconds = self.class.env_float('OPENC3_LAG_CLEAR_SECONDS', 10.0)
+      @renotify_seconds = self.class.env_float('OPENC3_LAG_RENOTIFY_SECONDS', 300.0)
+      @state = OK
+      @max_lag = 0.0
+      @max_lag_topic = nil
+      @below_since = nil
+      @below_ok_since = nil
+      @last_notify = nil
+      @last_notify_level = OK
+      @notified = false
+      @gauges = {}
+      @mutex = Mutex.new
+    end
+
+    # Record that a message was read from a topic
+    #
+    # @param topic [String] Redis stream the message was read from
+    # @param msg_id [String] Redis stream id of the message
+    # @param metric_name [String] Gauge metric to update with the lag
+    # @param help [String] Help text for the gauge metric
+    # @return [Float] The lag in seconds
+    def record(topic, msg_id, metric_name: nil, help: nil, now: Time.now.to_f)
+      lag = now - (id_ms(msg_id) / 1000.0)
+      update_gauge(metric_name, help, lag, now) if @metric and metric_name
+      return lag if @warn_seconds <= 0 # Notifications disabled
+
+      # Fast path for the common case of keeping up: skip the mutex and state machine
+      return lag if @state == OK and lag < @warn_seconds
+
+      @mutex.synchronize { update_state(topic, lag, now) }
+      return lag
+    end
+
+    protected
+
+    # Topics read by one microservice can lag by very different amounts, so
+    # publish the maximum lag rather than whichever topic was read last. The
+    # previous window's maximum is held through the current window so a spike
+    # just before a window boundary is still published.
+    def update_gauge(metric_name, help, lag, now)
+      window = (now / GAUGE_WINDOW_SECONDS).to_i
+      gauge = @gauges[metric_name]
+      if gauge.nil?
+        gauge = @gauges[metric_name] = { window: window, max: lag, previous_max: 0.0 }
+      elsif window != gauge[:window]
+        gauge[:previous_max] = (window == gauge[:window] + 1) ? gauge[:max] : 0.0
+        gauge[:window] = window
+        gauge[:max] = lag
+      elsif lag > gauge[:max]
+        gauge[:max] = lag
+      else
+        return # Published value is unchanged
+      end
+      value = (gauge[:max] > gauge[:previous_max]) ? gauge[:max] : gauge[:previous_max]
+      @metric.set(name: metric_name, value: value, type: 'gauge', unit: 'seconds', help: help)
+    end
+
+    def update_state(topic, lag, now)
+      if lag < @warn_seconds * CLEAR_RATIO
+        @below_ok_since ||= now
+      else
+        @below_ok_since = nil
+      end
+      if lag > @max_lag
+        @max_lag = lag
+        @max_lag_topic = topic
+      end
+      level = if lag >= @critical_seconds
+        CRITICAL
+      elsif lag >= @warn_seconds
+        WARN
+      else
+        OK
+      end
+
+      if level > @state
+        @state = level
+        @below_since = nil
+        # Bursty load can make a microservice recover and fall behind over and
+        # over, so falling back to an already announced level soon after the
+        # last notification continues that episode rather than notifying again
+        unless @last_notify and level <= @last_notify_level and (now - @last_notify) < @renotify_seconds
+          notify_lag(topic, lag, now)
+        end
+      elsif @state != OK
+        threshold = (@state == CRITICAL) ? @critical_seconds : @warn_seconds
+        if lag < threshold * CLEAR_RATIO
+          @below_since ||= now
+          if (now - @below_since) >= @clear_seconds
+            @below_since = nil
+            if @state == CRITICAL and (@below_ok_since.nil? or (now - @below_ok_since) < @clear_seconds)
+              @state = WARN
+              @below_since = @below_ok_since
+            else
+              @state = OK
+              @logger.info("#{@name} has caught up processing (max lag #{@max_lag.round(1)}s on #{@max_lag_topic})", type: Logger::NOTIFICATION) if @notified
+              @notified = false
+              @max_lag = 0.0
+              @max_lag_topic = nil
+            end
+          end
+        else
+          @below_since = nil
+          notify_lag(topic, lag, now) if (now - @last_notify) >= @renotify_seconds
+        end
+      end
+    end
+
+    def notify_lag(topic, lag, now)
+      message = "#{@name} is falling behind processing: #{lag.round(1)}s behind on #{topic} (max #{@max_lag.round(1)}s on #{@max_lag_topic})"
+      if @state == CRITICAL
+        @logger.error(message, type: Logger::NOTIFICATION)
+      else
+        @logger.warn(message, type: Logger::NOTIFICATION)
+      end
+      @last_notify = now
+      @last_notify_level = @state
+      @notified = true
+    end
+
+    def id_ms(id)
+      id.to_s.split('-')[0].to_i
+    end
+  end
+end

data/lib/openc3/version.rb

@@ -1,14 +1,14 @@
 # encoding: ascii-8bit
 
-OPENC3_VERSION = '7.4.1'
+OPENC3_VERSION = '7.5.1'
 module OpenC3
   module Version
     MAJOR = '7'
-    MINOR = '4'
+    MINOR = '5'
     PATCH = '1'
     OTHER = ''
-    BUILD = '2d4089e0687654512c2eb84722a5a4fa699dd5c3'
+    BUILD = 'e3c5693f00248aa4cb1833dad3aaeeaabb6fd581'
   end
-  VERSION = '7.4.1'
-  GEM_VERSION = '7.4.1'
+  VERSION = '7.5.1'
+  GEM_VERSION = '7.5.1'
 end

data/templates/conversion/conversion.py

@@ -1,6 +1,6 @@
 from openc3.conversions.conversion import Conversion
-# Using tlm() requires the following:
-# from openc3.api.tlm_api import tlm
+# Using System.telemetry.packet() requires the following:
+# from openc3.system.system import System
 
 # Custom conversion class
 # See https://docs.openc3.com/docs/configuration/conversions
@@ -20,4 +20,8 @@ class <%= conversion_class %>(Conversion):
         # Used when conversion is applied to a regular (not DERIVED) item
         # NOTE: You can also use packet.read("ITEM") to get additional values
         # return value / 2 * packet.read("OTHER_ITEM")
+        #
+        # In a READ_CONVERSION, read the latest value from a different packet in the same target
+        # other = System.telemetry.packet(packet.target_name, "OTHER_PACKET")
+        # return value * other.read("OTHER_ITEM")
         return value

data/templates/conversion/conversion.rb

@@ -20,6 +20,11 @@ module OpenC3
       # Used when conversion is applied to a regular (not DERIVED) item
       # NOTE: You can also use packet.read("ITEM") to get additional values
       # return value / 2 * packet.read("OTHER_ITEM")
+      #
+      # In a READ_CONVERSION, read the latest value from a different packet in the same target
+      # other = System.telemetry.packet(packet.target_name, "OTHER_PACKET")
+      # return value * other.read("OTHER_ITEM")
+      return value
     end
   end
 end

data/templates/plugin/.github/workflows/playwright.yml

@@ -0,0 +1,62 @@
+# Builds this plugin and installs it into a real COSMOS with Playwright.
+#
+# Runs the most recent COSMOS Core release in Docker, builds the plugin gem, and
+# drives the Admin tool the way an operator would: Install From File, submit the
+# variables dialog, and wait for the install to report Complete. That catches
+# what unit tests can't - a plugin.txt that doesn't parse, a target that doesn't
+# build, a microservice that won't start.
+#
+# Nothing here needs configuring as the plugin grows. Tool pages are discovered
+# from the COSMOS API after install and checked for browser console errors, and
+# a frontend is built with pnpm whenever the plugin has a package.json, so
+# `cli generate tool` and `cli generate widget` are covered with no edit here.
+#
+# Runs on every commit and once a week. The weekly run is what catches a new
+# COSMOS release breaking this plugin. Note that GitHub disables scheduled
+# workflows in a repo with no activity for 60 days.
+
+name: Playwright
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: ["**"]
+  # Off the hour because scheduled runs at :00 get queued behind everyone else's
+  schedule:
+    - cron: '27 7 * * 1'
+  workflow_dispatch:
+    inputs:
+      cosmos_version:
+        description: 'COSMOS version to run, or latest'
+        required: false
+        type: string
+        default: 'latest'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Superseding a pull request run is fine, but a scheduled run and a push to
+  # main share a ref, so cancelling on those would have them kill each other
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  playwright:
+    uses: OpenC3/.github/.github/workflows/plugin-playwright-reusable.yml@main
+    with:
+      plugin_directory: .
+      cosmos_version: ${{ inputs.cosmos_version || 'latest' }}
+      # Once you have added targets with `cli generate target`, list them here
+      # and the install is checked for them:
+      # expected_targets: MY_TARGET ANOTHER_TARGET
+      #
+      # install_demo: true  # Uncomment if this plugin references INST/INST2
+      # is_tool: true  # Uncomment to require that this plugin registers a tool
+      #
+      # Tool pages are checked for browser console errors automatically. Add
+      # regexes here for errors to allow:
+      # console_ignore: |
+      #   some third party gripe
+      #   another known message

data/templates/plugin/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+# Builds the gem, tags the commit, and creates a GitHub release. Run it by hand
+# from the Actions tab and give it a version number.
+#
+# Both publish steps are off by default so a first release works with no setup
+# at all. Tick the box in the run dialog when you are ready to publish, after
+# adding the matching secret to the repo:
+#
+#   Deploy to OpenC3 App Store  ->  OPENC3_API_TOKEN  (your store account token)
+#   Publish the gem to RubyGems ->  RUBYGEMS_API_KEY  (your RubyGems API key)
+#
+# A tool or widget frontend needs nothing set here: once the plugin has a
+# package.json it is built with pnpm before the gem is packaged.
+
+name: Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version number'
+        required: true
+        type: string
+      deploy_to_store:
+        description: 'Deploy to OpenC3 App Store'
+        required: false
+        type: boolean
+        default: false
+      deploy_to_rubygems:
+        description: 'Publish the gem to RubyGems'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  release:
+    uses: OpenC3/.github/.github/workflows/release-cosmos-plugin-reusable.yml@main
+    with:
+      version: ${{ inputs.version }}
+      deploy_to_store: ${{ inputs.deploy_to_store }}
+      deploy_to_rubygems: ${{ inputs.deploy_to_rubygems }}
+      plugin_directory: .
+      # is_tool: true  # Uncomment to fail the release if package.json is missing
+    secrets:
+      OPENC3_API_TOKEN: ${{ secrets.OPENC3_API_TOKEN }}
+      RUBYGEMS_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}

data/templates/plugin/.github/workflows/unit-tests.yml

@@ -0,0 +1,35 @@
+# Runs this plugin's unit tests on every push and pull request.
+#
+# Python tests are discovered in tests/ or test/, Ruby specs in spec/ or specs/.
+# Whichever this plugin doesn't have is skipped, so there is nothing to set up:
+# add a test file and it starts running. A plugin with no tests at all passes
+# with a warning until you set require_tests below.
+#
+# Dependencies are picked up automatically - requirements.txt for the code under
+# test, <test dir>/requirements.txt for test only ones, and a Gemfile for Ruby
+# when there is one.
+
+name: Unit Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: ["**"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit-tests:
+    uses: OpenC3/.github/.github/workflows/plugin-unit-tests-reusable.yml@main
+    with:
+      plugin_directory: .
+      # python_version: '3.12'  # Uncomment to pin a different Python
+      # ruby_version: '3.4'  # Uncomment to pin a different Ruby
+      # require_tests: true  # Uncomment to fail the build when there are no tests
+      # gemfile: Gemfile.dev  # Uncomment if the specs need a different Gemfile than the plugin's own

data/templates/plugin/.gitignore

@@ -1 +1,7 @@
 node_modules
+<% if @@language == 'py' -%>
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+<% end -%>

data/templates/plugin/README.md

@@ -8,6 +8,96 @@ Update this comment with your own description.
 
 1. Edit the .gemspec file fields: name, summary, description, authors, email, and homepage
 1. Update the LICENSE.md file with your company name
+<% if @@language == 'py' -%>
+1. Install [uv](https://docs.astral.sh/uv/getting-started/installation/) to manage the plugin's Python dependencies
+
+## Python dependencies with uv
+
+The plugin's Python dependencies are declared in `pyproject.toml` and locked in `uv.lock`.
+Both files are packaged into the gem automatically, and COSMOS reads them when the plugin is installed.
+
+### Adding dependencies
+
+```sh
+uv add requests                 # runtime dependency, installed into COSMOS with the plugin
+uv add --group dev pytest-mock  # development only, never installed into COSMOS
+```
+
+`uv add` updates both `pyproject.toml` and `uv.lock`. Commit both files.
+
+`uv lock` resolves `pyproject.toml` and writes `uv.lock` without installing anything. `uv sync` does the
+same when the lock is stale, then installs into `.venv`. Either works after editing `pyproject.toml` by hand;
+commit the updated `uv.lock`.
+
+COSMOS installs a locked plugin with `uv sync --frozen`, which installs exactly what `uv.lock` records and never
+relocks, so a stale lock ships stale dependencies. `uv lock --check` fails if the lock is out of date.
+
+### How COSMOS installs them
+
+- **With `uv.lock`** (recommended): COSMOS runs `uv sync --frozen --no-dev`. Every install gets the same
+  versions, downloaded from the URLs recorded in the lock.
+- **Without `uv.lock`**: COSMOS resolves the dependencies at install time against the PyPI URL set in
+  Admin Console -> Settings, so versions can change from one install to the next.
+
+The `dev` dependency group is never installed into COSMOS.
+
+### Developing locally
+
+```sh
+uv sync --group dev           # create .venv with runtime and dev dependencies
+uv run --group dev pytest     # run tests; lib/ is on the import path
+uv run --group dev ruff check # lint
+uv run --group dev ruff format
+uv run --group dev ty check   # type check
+```
+
+A plain `uv sync` installs only the runtime dependencies, matching what COSMOS installs.
+
+The plugin itself is not installed into `.venv`: COSMOS puts `lib/` on the Python path instead, and pytest and ty
+are configured to do the same. Anything else needs `lib/` on the path to import `<%= package_name %>`:
+
+```
+PYTHONPATH=lib uv run python my_script.py
+```
+
+`cli generate` writes a `.python-version` file pinning the Python version of the COSMOS image it ran in, so
+uv develops against the same Python COSMOS runs. If you upgrade to a COSMOS release with a newer Python, update
+it with `uv python pin <version>`. Without that file uv picks any installed Python that satisfies
+`requires-python`.
+
+The `openc3` dev dependency provides the COSMOS Python API for your editor, tests and `ty`. Pin it to the
+COSMOS version you deploy to so they see the same API, e.g. `uv add --group dev "openc3==X.Y.Z"`.
+
+### Where to put Python code
+
+Put Python code shared across the plugin in `lib/<%= package_name %>/`, never directly in `lib/`.
+
+COSMOS adds the `lib/` directory of every installed plugin to the Python path. If two plugins both ship
+`lib/helpers.py`, `import helpers` loads whichever one Python finds first, and the other can't be imported
+at all. A module directly in `lib/` can also hide an installed package of the same name, such as `requests`.
+The `<%= package_name %>` package is named after this plugin, so its modules can't collide.
+
+Import from the package:
+
+```python
+from <%= package_name %>.helpers import Helper
+```
+
+Reference its files by path in plugin configuration, e.g. `INTERFACE MY_INT <%= package_name %>/my_interface.py`.
+
+### Updating dependencies
+
+```
+uv lock --upgrade-package requests  # upgrade one package
+uv lock --upgrade                   # upgrade everything
+```
+
+### Private package indexes
+
+See the comments in the `[tool.uv]` section of `pyproject.toml`. If the COSMOS PyPI URL setting points at
+anything other than public PyPI, COSMOS ignores the plugin's own index settings when it resolves, so a
+package published only to your private index must also be served by that index, or be locked in `uv.lock`.
+<% end -%>
 
 ## Building non-tool / widget plugins
 
@@ -26,19 +116,41 @@ If you don’t have a local node environment, you can use our openc3-node contai
 
 Mac / Linux:
 
-```
+```sh
 docker run -it -v `pwd`:/openc3/local:z -w /openc3/local docker.io/openc3inc/openc3-node sh
 ```
 
 Windows:
 
-```
+```sh
 docker run -it -v %cd%:/openc3/local -w /openc3/local docker.io/openc3inc/openc3-node sh
 ```
 
 1. pnpm install --frozen-lockfile --ignore-scripts
 1. rake build VERSION=1.0.0
 
+## Continuous integration
+
+`.github/workflows/` ships three GitHub Actions workflows that work as soon as
+you push this plugin to GitHub. They call shared workflows from `OpenC3/.github`,
+so the steps stay current without you updating anything here.
+
+- **Unit Tests** - on every push and pull request. Runs Python tests in `tests/`
+  or `test/` and Ruby specs in `spec/` or `specs/`. Whichever you don't have is
+  skipped, so just add a test file.
+- **Playwright** - on every push and pull request, plus weekly. Builds the gem,
+  starts the latest COSMOS release in Docker, and installs the plugin through the
+  Admin tool, which catches a `plugin.txt` that doesn't parse, a target that
+  doesn't build, or a microservice that won't start. The weekly run is what tells
+  you a new COSMOS release broke this plugin. Once you add targets, list them in
+  `expected_targets` so the install is verified against them.
+- **Release** - manual, from the Actions tab. Builds the gem, tags the commit and
+  creates a GitHub release. Publishing to the OpenC3 App Store and to RubyGems is
+  off until you add the matching secret and tick the box.
+
+Adding a tool or a widget needs no change to any of these. All three build a
+frontend with pnpm as soon as the plugin has a `package.json`.
+
 ## Installing into OpenC3 COSMOS
 
 1. Go to the OpenC3 Admin Tool, Plugins Tab

data/templates/plugin/lib/PACKAGE/__init__.py

@@ -0,0 +1,4 @@
+# Python code shared across this plugin lives in this package. COSMOS puts
+# every installed plugin's lib/ on sys.path, so a module placed directly in
+# lib/ can collide with another plugin's module of the same name. Keeping it
+# under this uniquely named package avoids that. See README.md.