jumpstarter-dev · raballew · May 19, 2026 · May 19, 2026 · May 19, 2026 · May 19, 2026
diff --git a/.cursor/rules/jep-process.mdc b/.cursor/rules/jep-process.mdc
@@ -12,9 +12,9 @@ This rule helps with creating Jumpstarter Enhancement Proposals (JEPs).
 
 ## Creating a JEP
 
-1. **Choose the next JEP number**: Look at existing files in `python/docs/source/internal/jeps/` and pick the next available incrementing integer. JEP-0000 through JEP-0009 are reserved for process/meta-JEPs, so start from JEP-0010 for regular proposals.
+1. **Choose the next JEP number**: Look at existing files in `python/docs/source/contributing/jeps/` and pick the next available incrementing integer. JEP-0000 through JEP-0009 are reserved for process/meta-JEPs, so start from JEP-0010 for regular proposals.
 
-2. **Create the file**: Copy the template from `python/docs/source/internal/jeps/JEP-NNNN-template.md` to `python/docs/source/internal/jeps/JEP-NNNN-short-title.md`, replacing `NNNN` with the zero-padded number and `short-title` with a descriptive slug.
+2. **Create the file**: Copy the template from `python/docs/source/contributing/jeps/JEP-NNNN-template.md` to `python/docs/source/contributing/jeps/JEP-NNNN-short-title.md`, replacing `NNNN` with the zero-padded number and `short-title` with a descriptive slug.
 
 3. **Fill in the metadata table**:
    - Set the JEP number (incrementing integer, NOT the PR number)
@@ -45,8 +45,8 @@ JEPs use this format for individual decisions:
 
 **Alternatives considered:**
 
-1. **Option A** — Brief description.
-2. **Option B** — Brief description.
+1. **Option A** - Brief description.
+2. **Option B** - Brief description.
 
 **Decision:** Option A.
 
@@ -56,7 +56,7 @@ JEPs use this format for individual decisions:
 ## Key Rules
 
 - JEP numbers are incrementing integers, NOT derived from PR numbers
-- JEPs live in `python/docs/source/internal/jeps/`
+- JEPs live in `python/docs/source/contributing/jeps/`
 - All JEPs should be merged as PRs so the documentation is part of the Jumpstarter docs/source
 - Rejected JEPs are normally not merged, but can be merged with "Rejected" status if there is an architectural reason to preserve them
 - The license for all documents is Apache-2.0
diff --git a/.cursor/rules/releasing-operator.mdc b/.cursor/rules/releasing-operator.mdc
@@ -18,7 +18,7 @@ The operator bundle version is driven by variables in `controller/deploy/operato
 - **`IMAGE_TAG_BASE`**: Registry prefix (`quay.io/jumpstarter-dev/jumpstarter-operator`).
 - **`BUNDLE_IMG`** / **`CATALOG_IMG`**: Also derived from `IMAGE_TAG_BASE` and `VERSION` automatically.
 
-The `config/manifests/bases/jumpstarter-operator.clusterserviceversion.yaml` uses placeholder version `0.0.0` -- the real version is injected by `make bundle`.
+The `config/manifests/bases/jumpstarter-operator.clusterserviceversion.yaml` uses placeholder version `0.0.0` - the real version is injected by `make bundle`.
 
 ## Image Tag Convention
 
@@ -34,7 +34,7 @@ When preparing a new release version X.Y.Z, update these files together:
 
 ### 1. `controller/deploy/operator/Makefile`
 - `VERSION ?= X.Y.Z`
-- `REPLACES ?= jumpstarter-operator.vPREVIOUS` (the most recent version published to the OLM channel -- including RCs. E.g. if `v0.8.1-rc.1` was published, REPLACES must be `jumpstarter-operator.v0.8.1-rc.1`, not `v0.8.0`)
+- `REPLACES ?= jumpstarter-operator.vPREVIOUS` (the most recent version published to the OLM channel - including RCs. E.g. if `v0.8.1-rc.1` was published, REPLACES must be `jumpstarter-operator.v0.8.1-rc.1`, not `v0.8.0`)
 - Optionally update `OPENSHIFT_VERSIONS` if the supported range changes
 
 ### 2. `controller/deploy/operator/api/v1alpha1/jumpstarter_types.go`

diff --git a/.cursor/skills/propose-jep/SKILL.md b/.cursor/skills/propose-jep/SKILL.md
@@ -10,30 +10,30 @@ You are helping the user create a new Jumpstarter Enhancement Proposal (JEP).
 
 ## Context
 
-JEPs are design documents for substantial changes to the Jumpstarter project — changes that affect multiple components, alter public APIs or protocols, or require community consensus. Read `.cursor/rules/jep-process.mdc` for the full process definition.
+JEPs are design documents for substantial changes to the Jumpstarter project - changes that affect multiple components, alter public APIs or protocols, or require community consensus. Read `.cursor/rules/jep-process.mdc` for the full process definition.
 
 JEP topic: $ARGUMENTS
 
 ## Steps
 
 ### 1. Determine the next JEP number
 
-List existing files in `python/docs/source/internal/jeps/` and pick the next available incrementing integer. JEP-0000 through JEP-0009 are reserved for process/meta-JEPs, so start from JEP-0010 for regular proposals.
+List existing files in `python/docs/source/contributing/jeps/` and pick the next available incrementing integer. JEP-0000 through JEP-0009 are reserved for process/meta-JEPs, so start from JEP-0010 for regular proposals.
 
 ### 2. Gather information
 
 Before writing the JEP, ask the user clarifying questions to understand:
 
-- **What problem does this solve?** — The motivation section needs a concrete problem description.
-- **Who is affected?** — Which components, drivers, or user workflows are impacted?
-- **What are the alternatives?** — Each design decision needs at least two alternatives considered.
-- **What are the compatibility implications?** — Does this break existing APIs, protocols, or workflows?
+- **What problem does this solve?** - The motivation section needs a concrete problem description.
+- **Who is affected?** - Which components, drivers, or user workflows are impacted?
+- **What are the alternatives?** - Each design decision needs at least two alternatives considered.
+- **What are the compatibility implications?** - Does this break existing APIs, protocols, or workflows?
 
 If the user provided a description in `$ARGUMENTS`, use it as a starting point but still ask about gaps.
 
 ### 3. Create the JEP file
 
-Copy the template from `python/docs/source/internal/jeps/JEP-NNNN-template.md` and create a new file at `python/docs/source/internal/jeps/JEP-NNNN-short-title.md` where:
+Copy the template from `python/docs/source/contributing/jeps/JEP-NNNN-template.md` and create a new file at `python/docs/source/contributing/jeps/JEP-NNNN-short-title.md` where:
 
 - `NNNN` is the zero-padded next number
 - `short-title` is a descriptive slug derived from the proposal title
@@ -46,9 +46,9 @@ Fill in:
 
 ### 4. Update the JEP index
 
-Add the new JEP to the appropriate table in `python/docs/source/internal/jeps/README.md` (Process, Standards Track, or Informational).
+Add the new JEP to the appropriate table in `python/docs/source/contributing/jeps/index.md` (Process, Standards Track, or Informational).
 
-Add the new JEP file to the `{toctree}` directive at the bottom of `python/docs/source/internal/jeps/README.md`.
+Add the new JEP file to the `{toctree}` directive at the bottom of `python/docs/source/contributing/jeps/index.md`.
 
 ### 5. Present the result
 

diff --git a/python/.devcontainer/Dockerfile → .devcontainer/Dockerfile b/python/.devcontainer/Dockerfile → .devcontainer/Dockerfile
@@ -7,7 +7,7 @@ WORKDIR /opt
 
 COPY --from=ghcr.io/astral-sh/uv:latest /uv  /bin/uv
 COPY --from=ghcr.io/astral-sh/uv:latest /uvx /bin/uvx
-COPY ./.python-version ./
+COPY ./python/.python-version ./
 
 # Install required tools for development
 RUN apt-get update && apt-get install -y iperf3 libusb-dev
diff --git a/python/.devcontainer/devcontainer.json → .devcontainer/devcontainer.json b/python/.devcontainer/devcontainer.json → .devcontainer/devcontainer.json
@@ -4,8 +4,8 @@
 		"context": "..",
 		"dockerfile": "Dockerfile"
 	},
-	"postCreateCommand": "make sync",
-	"postStartCommand": "uv python pin 3.12 && uv run pre-commit install",
+	"postCreateCommand": "cd python && make sync",
+	"postStartCommand": "cd python && uv python pin 3.12 && uv run pre-commit install",
 	"remoteUser": "vscode",
 	// Mount USB devices to devcontainer for tests
 	"mounts": [

diff --git a/python/.devfile.yaml → .devfile.yaml b/python/.devfile.yaml → .devfile.yaml
@@ -22,17 +22,21 @@ commands:
   - id: serve-docs
     exec:
       component: runtime
+      workingDir: ${PROJECT_SOURCE}/python
       commandLine: make docs-serve DOC_LISTEN="--host 0.0.0.0"
   - id: sync
     exec:
       component: runtime
+      workingDir: ${PROJECT_SOURCE}/python
       commandLine: make sync
   - id: clean
     exec:
       component: runtime
+      workingDir: ${PROJECT_SOURCE}/python
       commandLine: make clean
   - id: test
     exec:
       component: runtime
+      workingDir: ${PROJECT_SOURCE}/python
       commandLine: make test
 
diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml
@@ -96,6 +96,28 @@ jobs:
       - name: Build the documentation for the current version (no warnings allowed)
         run: make sync && make docs
 
+  linkcheck:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
+        with:
+          version: "latest"
+
+      - name: Install Python
+        run: |
+          uv python pin 3.12
+          uv python install
+
+      - name: Check documentation links
+        run: make sync && make docs-linkcheck
+
   # Deployment job
   deploy:
     environment:

diff --git a/.github/workflows/e2e.yaml b/.github/workflows/e2e.yaml
@@ -61,7 +61,7 @@ jobs:
       - name: Install Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.24"
 
       - name: Cache controller image
         id: cache
@@ -104,7 +104,7 @@ jobs:
       - name: Install Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.24"
 
       - name: Cache operator artifacts
         id: cache
@@ -189,7 +189,7 @@ jobs:
       - name: Install Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.24"
 
       - name: Download controller image
         uses: actions/download-artifact@v4
@@ -259,7 +259,7 @@ jobs:
       - name: Install Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.24"
 
       - name: Setup compat environment (old controller v0.8.1)
         run: make e2e-compat-setup COMPAT_SCENARIO=old-controller
@@ -287,7 +287,7 @@ jobs:
       - name: Install Go
         uses: actions/setup-go@v5
         with:
-          go-version: "1.22"
+          go-version: "1.24"
 
       - name: Download controller image
         uses: actions/download-artifact@v4

diff --git a/e2e/LICENSE → LICENSE b/e2e/LICENSE → LICENSE
diff --git a/README.md b/README.md
@@ -9,15 +9,17 @@
 
 A free, open source tool for automated testing on real and virtual hardware with
 CI/CD integration. Simplify device automation with consistent rules across local
-and distributed environments.
+and distributed environments. Every interface is programmatic - there is no GUI
+wall - so human developers, test scripts, CI pipelines, and AI agents interact
+with hardware through the same APIs.
 
 ## Highlights
 
 - 🧪 **Unified Testing** - One tool for local, virtual, and remote hardware
 - 🐍 **Python-Powered** - Leverage Python's testing ecosystem
 - 🔌 **Hardware Abstraction** - Simplify complex hardware interfaces with drivers
 - 🌐 **Collaborative** - Share test hardware globally
-- ⚙️ **CI/CD Ready** - Works with cloud native developer environments and pipelines
+- ⚙️ **Automation Ready** - Same APIs for humans, test scripts, CI pipelines, and AI agents
 - 💻 **Cross-Platform** - Supports Linux and macOS
 
 ## Repository Structure
@@ -115,20 +117,20 @@ make e2e-clean
 ### Prerequisites
 
 - Python 3.11+ (for Python components)
-- Go 1.22+ (for controller)
+- Go 1.24+ (for controller)
 - Docker/Podman (for container builds)
 - kubectl (for Kubernetes deployment)
 
 ### Building
 
 ```shell
 # Build all components
-make all
+make build
 
 # Build specific components
-make python      # Python packages
-make controller  # Controller binary
-make protocol    # Generate protocol code
+make build-python      # Python packages
+make build-controller  # Controller binary
+make build-protocol    # Generate protocol code
 
 # Run tests
 make test
@@ -139,20 +141,13 @@ make e2e        # Run tests
 make e2e-clean  # Clean up
 ```
 
-### Running Locally
-
-```shell
-# Start a local development environment
-make dev
-```
-
 ## Documentation
 
 Jumpstarter's documentation is available at [jumpstarter.dev](https://jumpstarter.dev).
 
 - [Getting Started](https://jumpstarter.dev/main/getting-started/)
 - [User Guide](https://jumpstarter.dev/main/introduction/)
-- [API Reference](https://jumpstarter.dev/main/api/)
+- [API Reference](https://jumpstarter.dev/main/reference/)
 - [Contributing Guide](https://jumpstarter.dev/main/contributing.html)
 
 ## Contributing