docs: consolidate and improve documentation across the repository

.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:

README.md

@@ -9,7 +9,9 @@
 
 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
 
@@ -19,6 +21,7 @@ and distributed environments.
 - 🌐 **Collaborative** - Share test hardware globally
 - ⚙️ **CI/CD Ready** - Works with cloud native developer environments and pipelines
 - 💻 **Cross-Platform** - Supports Linux and macOS
+- 🤖 **Agentic by Design** - Same APIs for humans, scripts, and AI agents
 
 ## Repository Structure
 
@@ -115,20 +118,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 +142,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

controller/README.md

@@ -1,119 +1,24 @@
-# jumpstarter-controller
+# Jumpstarter Controller
 
-[![Build and push container image](https://github.com/jumpstarter-dev/jumpstarter-controller/actions/workflows/build.yaml/badge.svg)](https://github.com/jumpstarter-dev/jumpstarter-controller/actions/workflows/build.yaml)
-![GitHub Release](https://img.shields.io/github/v/release/jumpstarter-dev/jumpstarter-controller)
-![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/jumpstarter-dev/jumpstarter-controller/total)
-[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/jumpstarter-dev/jumpstarter-controller)
+The Jumpstarter controller is the Kubernetes-native service component of
+[Jumpstarter](https://jumpstarter.dev). It implements the server-side gRPC
+services defined by the [Jumpstarter Protocol](../protocol/), running as a
+Kubernetes operator that manages Custom Resources for clients, exporters, and
+leases. The controller enables distributed hardware sharing by routing traffic
+between clients and exporters, handling lease negotiation, and enforcing access
+policies.
 
-// TODO(user): Add simple overview of use/purpose
-
-## Description
-// TODO(user): An in-depth paragraph about your project and overview of use
-
-## Getting Started
-
-### Prerequisites
-- go version v1.22.0+
-- kubectl version v1.11.3+.
-- Access to a Kubernetes v1.11.3+ cluster.
-
-### To Deploy on the cluster
-**Build and push your image to the location specified by `IMG`:**
+## Development
 
 ```sh
 make docker-push IMG=<some-registry>/jumpstarter-controller:tag
-```
-
-**NOTE:** This image ought to be published in the personal registry you specified.
-And it is required to have access to pull the image from the working environment.
-Make sure you have the proper permission to the registry if the above commands don’t work.
-
-**Install the CRDs into the cluster:**
-
-```sh
 make install
-```
-
-**Deploy the Manager to the cluster with the image specified by `IMG`:**
-
-```sh
-make deploy IMG=<some-registry>/jumpstarter-router:tag
-```
-
-> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
-privileges or be logged in as admin.
-
-**Create instances of your solution**
-You can apply the samples (examples) from the config/sample:
-
-```sh
-kubectl apply -k config/samples/
-```
-
->**NOTE**: Ensure that the samples has default values to test it out.
-
-### To Uninstall
-**Delete the instances (CRs) from the cluster:**
-
-```sh
-kubectl delete -k config/samples/
-```
-
-**Delete the APIs(CRDs) from the cluster:**
-
-```sh
-make uninstall
-```
-
-**UnDeploy the controller from the cluster:**
+make deploy IMG=<some-registry>/jumpstarter-controller:tag
 
-```sh
 make undeploy
+make uninstall
 ```
 
-## Project Distribution
-
-Following are the steps to build the installer and distribute this project to users.
-
-1. Build the installer for the image built and published in the registry:
-
-```sh
-make build-installer IMG=<some-registry>/jumpstarter-router:tag
-```
-
-NOTE: The makefile target mentioned above generates an 'install.yaml'
-file in the dist directory. This file contains all the resources built
-with Kustomize, which are necessary to install this project without
-its dependencies.
-
-2. Using the installer
-
-Users can just run kubectl apply -f <URL for YAML BUNDLE> to install the project, i.e.:
-
-```sh
-kubectl apply -f https://raw.githubusercontent.com/<org>/jumpstarter-router/<tag or branch>/dist/install.yaml
-```
-
-## Contributing
-// TODO(user): Add detailed information on how you would like others to contribute to this project
-
-**NOTE:** Run `make help` for more information on all potential `make` targets
-
-More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
-
-## License
-
-Copyright 2024.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
+For production deployment, see the
+[Service Installation](https://jumpstarter.dev/main/getting-started/installation/index.html)
+documentation.

controller/deploy/microshift-bootc/README.md

@@ -400,21 +400,3 @@ make bootc-rm bootc-build bootc-run
    - Console login will require password change from default `jumpstarter`
    - Access web UI at `http://<host-ip>:8880` and set new password
 
-## Resources
-
-### Jumpstarter Documentation
-- [Official Installation Guide](https://jumpstarter.dev/main/getting-started/installation/service/index.html) - **Recommended for production**
-- [Jumpstarter Project](https://github.com/jumpstarter-dev/jumpstarter)
-
-### Technology Stack
-- [MicroShift Documentation](https://microshift.io/)
-- [Bootc Documentation](https://containers.github.io/bootc/)
-- [TopoLVM Documentation](https://github.com/topolvm/topolvm)
-
-## Support
-
-For issues and questions:
-- File issues on the Jumpstarter GitHub repository
-- Check container logs: `sudo podman logs jumpstarter-microshift-okd`
-- Review systemd journals: `make bootc-sh` then `journalctl -xe`
-

controller/deploy/microshift-bootc/config-svc/README.md

@@ -165,13 +165,4 @@ mypy app.py auth.py system.py api.py routes.py
 - Hostname validation per RFC 1123
 - Default password change enforcement
 
-## License
-
-Apache License 2.0
-
-## Links
-
-- Homepage: https://jumpstarter.dev
-- Documentation: https://docs.jumpstarter.dev
-- Repository: https://github.com/jumpstarter-dev/jumpstarter-controller
 

controller/deploy/operator/README.md

@@ -1,117 +1,21 @@
-# jumpstarter-operator
-// TODO(user): Add simple overview of use/purpose
+# Jumpstarter Operator
 
-## Description
-// TODO(user): An in-depth paragraph about your project and overview of use
+The Jumpstarter operator manages the lifecycle of Jumpstarter controller
+components on Kubernetes using the Operator Lifecycle Manager (OLM). It
+packages the controller, router, and associated resources into a single
+installable unit.
 
-## Getting Started
-
-### Prerequisites
-- go version v1.24.0+
-- docker version 17.03+.
-- kubectl version v1.11.3+.
-- Access to a Kubernetes v1.11.3+ cluster.
-
-### To Deploy on the cluster
-**Build and push your image to the location specified by `IMG`:**
+## Development
 
 ```sh
 make docker-build docker-push IMG=<some-registry>/jumpstarter-operator:tag
-```
-
-**NOTE:** This image ought to be published in the personal registry you specified.
-And it is required to have access to pull the image from the working environment.
-Make sure you have the proper permission to the registry if the above commands don’t work.
-
-**Install the CRDs into the cluster:**
-
-```sh
 make install
-```
-
-**Deploy the Manager to the cluster with the image specified by `IMG`:**
-
-```sh
 make deploy IMG=<some-registry>/jumpstarter-operator:tag
-```
-
-> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
-privileges or be logged in as admin.
 
-**Create instances of your solution**
-You can apply the samples (examples) from the config/sample:
-
-```sh
-kubectl apply -k config/samples/
-```
-
->**NOTE**: Ensure that the samples has default values to test it out.
-
-### To Uninstall
-**Delete the instances (CRs) from the cluster:**
-
-```sh
-kubectl delete -k config/samples/
-```
-
-**Delete the APIs(CRDs) from the cluster:**
-
-```sh
-make uninstall
-```
-
-**UnDeploy the controller from the cluster:**
-
-```sh
 make undeploy
+make uninstall
 ```
 
-## Project Distribution
-
-Following the options to release and provide this solution to the users.
-
-### By providing a bundle with all YAML files
-
-1. Build the installer for the image built and published in the registry:
-
-```sh
-make build-installer IMG=<some-registry>/jumpstarter-operator:tag
-```
-
-**NOTE:** The makefile target mentioned above generates an 'install.yaml'
-file in the dist directory. This file contains all the resources built
-with Kustomize, which are necessary to install this project without its
-dependencies.
-
-2. Using the installer
-
-Users can just run 'kubectl apply -f <URL for YAML BUNDLE>' to install
-the project, i.e.:
-
-```sh
-kubectl apply -f https://raw.githubusercontent.com/<org>/jumpstarter-operator/<tag or branch>/dist/install.yaml
-```
-
-## Contributing
-// TODO(user): Add detailed information on how you would like others to contribute to this project
-
-**NOTE:** Run `make help` for more information on all potential `make` targets
-
-More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
-
-## License
-
-Copyright 2025.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-
+For production deployment, see the
+[Service Installation](https://jumpstarter.dev/main/getting-started/installation/index.html)
+documentation.