OpenPhysics Baton

Orchestration repository for the OpenPhysics organization. Baton owns the operational side of the org: the reusable CI/CD workflows every simulation calls, the cross-repo automation scripts, the Dependabot templates, the machine-readable repository catalog, and the GitHub Pages simulation landing page.

Community-health defaults (license, contributing, code of conduct, security policy, issue/PR templates, org profile) live in OpenPhysics/.github — GitHub requires those in the special .github repo so they are inherited org-wide.

Contents

Path	Purpose
.github/workflows/ci.yml	Reusable CI workflow (audit, lint, type-check, test, build)
.github/workflows/deploy.yml	Reusable GitHub Pages deploy workflow
.github/workflows/shared-codeql.yml	Reusable CodeQL analysis
.github/workflows/shared-dependency-review.yml	Reusable dependency review
.github/workflows/shared-compliance-check.yml	README and repo-structure compliance audit
.github/workflows/pages.yml	Build and deploy the org simulation index to GitHub Pages
.github/workflows/optimize-assets.yml	Regenerate WebP card thumbnails from screenshots and commit them back
.github/workflows/fleet-exec.yml	Fan a command across many repos and open one PR each (manual dispatch)
.github/workflows/fleet-health.yml	Weekly lint / type-check / build / test of every simulation, reported as a table
.github/workflows/sync-dependabot.yml	Validate the Dependabot templates
.github/workflows/baton-selfcheck.yml	Validate Baton's own invariants (skills collection + index, Node-version sync, script syntax)
scripts/	Repo catalog tools, compliance checks, Dependabot/metadata sync, screenshots
config/	Canonical Dependabot + Claude-settings templates synced to member repos
structure/repos.json	Machine-readable catalog of org repositories
CONVENTIONS.md	Shared codebase structure every SceneryStack sim must follow
ACCESSIBILITY.md	Shared accessibility pattern for SceneryStack sims
skills/	SceneryStack development reference docs for AI assistants
.claude-plugin/	Marketplace + plugin manifests that package skills/ as the scenerystack@openphysics Claude Code plugin
docs/	Generated landing page (openphysics.github.io/Baton)

Claude Code plugin

This repo doubles as a Claude Code marketplace. It publishes one plugin, scenerystack, that bundles the skills/ reference docs so any sim repo can load them as a unit instead of vendoring copies. The repo root is the plugin (.claude-plugin/plugin.json); its skills/ are auto-discovered.

Member repos enable it from their .claude/settings.json (the canonical keys live in config/claude-settings.json):

{
  "extraKnownMarketplaces": {
    "openphysics": { "source": { "source": "github", "repo": "OpenPhysics/Baton" } }
  },
  "enabledPlugins": { "scenerystack@openphysics": true }
}

Or interactively: claude plugin marketplace add OpenPhysics/Baton then claude plugin install scenerystack@openphysics. Validate manifest changes with claude plugin validate .claude-plugin/marketplace.json.

Roll it out across the fleet with scripts/sync-claude-settings.sh, which merges those keys into every SceneryStack repo's settings without clobbering existing config.

Shared CI

Each simulation's .github/workflows/ci.yml calls the reusable workflows from this repo:

jobs:
  ci:
    uses: OpenPhysics/Baton/.github/workflows/ci.yml@main
  dependency-review:
    if: github.event_name == 'pull_request'
    uses: OpenPhysics/Baton/.github/workflows/shared-dependency-review.yml@main
  codeql:
    uses: OpenPhysics/Baton/.github/workflows/shared-codeql.yml@main

Optional compliance checking:

  compliance:
    uses: OpenPhysics/Baton/.github/workflows/shared-compliance-check.yml@main
    with:
      repo-name: ${{ github.event.repository.name }}

ci.yml runs the test step automatically when the caller defines a test npm script — no per-repo flag needed. Pass run-tests: "true" to force it on (e.g. before a test script exists) or run-tests: "false" to opt out.

Pages deploy (sims that publish to GitHub Pages):

jobs:
  deploy:
    uses: OpenPhysics/Baton/.github/workflows/deploy.yml@main
    permissions:
      contents: read
      pages: write
      id-token: write

Compliance workflow

shared-compliance-check.yml runs weekly (Mondays 06:00 UTC) and on manual dispatch. It reads structure/repos.json, clones each simulation repo, and checks:

• FAIL if CONTRIBUTING.md or LICENSE exists at repo root (use the org defaults from OpenPhysics/.github)
• FAIL if README.md is missing ## Features, ## Quick Start, ## Scripts, ## Tech Stack, ## License, or ## Contributing
• FAIL if README.md sections are out of order or include extra top-level sections (only the six standard sections allowed)
• FAIL if .github/workflows/ci.yml does not call this repo's shared reusable CI workflow

Simulation READMEs use a fixed six-section outline (in order): Features → Quick Start → Scripts → Tech Stack → License → Contributing.

Run locally against a checkout:

scripts/check-repo-compliance.sh /path/to/sim-repo

Repository catalog

structure/repos.json lists all OpenPhysics repositories with metadata (simulation type, framework, deployed URL, physics topics, etc.). The compliance workflow, Pages landing page, and the catalog scripts consume this file. See scripts/README.md for the tooling:

scripts/parse-repos.sh names --simulation
scripts/list-repos.sh --json
scripts/sync-github-metadata.sh --dry-run

Scripts assume the Baton repo lives beside member repos in a shared workspace; set OPENPHYSICS_WORKSPACE or pass --catalog /path/to/repos.json if your checkout differs.

Fleet operations

Cross-repo automation, all driven from the catalog:

• Batch changes — scripts/fleet-exec.sh clones each selected repo, runs a command, and (with --apply) opens one PR per repo. Dry-run by default. The fleet-exec.yml workflow exposes it as a manual dispatch (e.g. bump a shared dependency, run npm run fix, apply a codemod). Opening PRs in other repos needs a FLEET_PAT secret with write access — the default GITHUB_TOKEN is scoped to Baton only. Setup steps (fine-grained PAT or GitHub App): doc/fleet-auth.md.
• Health report — fleet-health.yml runs weekly, fanning out one matrix job per active simulation (npm download cache reused across runs) to run lint, type-check, build, and test, then publishing a pass/fail table to the job summary. Read-only; surfaces sims broken by a shared-workflow or dependency change.
• Compliance audit — shared-compliance-check.yml audits README structure and CI wiring across the org. The dispatch/schedule run fans out one matrix job per sim and aggregates a single pass/fail table (see above).
• Everyday git fan-out — doc/fleet-git.md is a cheat sheet for running git across your local checkouts (pull all, push all, status all), built on parse-repos.sh paths. Use it for ad-hoc local work; use fleet-exec.sh to land the same change as PRs.

Node version

The default Node version for the fleet is "24", declared in three places that must stay in sync — bump them together:

• .github/workflows/ci.yml — node-version input default
• .github/workflows/deploy.yml — node-version input default
• .github/workflows/fleet-health.yml — setup-node step

scripts/check-node-version.sh enforces that the three stay in sync (run in CI by baton-selfcheck.yml), so a half-done bump fails fast instead of drifting silently.

When bumping, also update @types/node across member repos (Dependabot ignores its major bumps so the runtime and types stay aligned — see the note in the Dependabot templates under config/).