From 08e36522075a84a05c22cd14fb039930f724367b Mon Sep 17 00:00:00 2001
From: Rionlyu <beniamin.kmiec@gmail.com>
Date: Fri, 10 Jul 2026 22:05:05 +0200
Subject: [PATCH] docs: improve installation and project status

---
 README.md                    | 39 +++++++++++++++++++++++++++---------
 internal/model/model.go      |  3 +--
 internal/model/validation.go |  2 +-
 3 files changed, 31 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 87eecad..9e53bf7 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,7 @@
 # TopoQueue
 
+[![CI](https://github.com/Rionlyu/topoqueue/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Rionlyu/topoqueue/actions/workflows/ci.yml)
+
 TopoQueue is a deterministic Go CLI for exploring how queue policy and
 topology constraints affect accelerator-job admission.
 
@@ -17,13 +19,30 @@ topology constraints affect accelerator-job admission.
 - Concurrent comparison of policies with isolated mutable scheduling state.
 - Strict YAML decoding that rejects unknown fields.
 
-## Module path
+## Installation
 
-The Go module path is `github.com/Rionlyu/topoqueue`.
+TopoQueue requires Go 1.25 or newer.
 
-## Quick start
+Install with Go:
 
-TopoQueue requires Go 1.25 or newer.
+```sh
+go install github.com/Rionlyu/topoqueue/cmd/topoqueue@latest
+topoqueue --help
+```
+
+`go install` writes the binary to `GOBIN`, or to `$(go env GOPATH)/bin` when
+`GOBIN` is unset. Ensure that directory is on `PATH`.
+
+To build from a repository checkout instead:
+
+```sh
+git clone https://github.com/Rionlyu/topoqueue.git
+cd topoqueue
+make build
+./bin/topoqueue --help
+```
+
+## Quick start
 
 Build the CLI and run the included comparison:
 
@@ -113,12 +132,12 @@ Policy comparison performs two independent runs with the same per-run bounds.
 ## Development
 
 ```sh
-make fmt-check   # verify gofmt output
-make vet         # run go vet ./...
-make test        # run tests with the race detector
-make build       # build bin/topoqueue
-make demo        # run the checked-in comparison
-make benchmark   # run the deterministic scheduler benchmark
+make fmt-check
+make vet
+make test
+make build
+make demo
+make benchmark
 ```
 
 ## Project structure
diff --git a/internal/model/model.go b/internal/model/model.go
index c5b7c95..b6fbd4c 100644
--- a/internal/model/model.go
+++ b/internal/model/model.go
@@ -1,8 +1,7 @@
 // Package model defines TopoQueue's input data model.
 package model
 
-// Resources is a CPU and GPU quantity. Both values are whole, non-negative
-// units in valid input.
+// Resources holds CPU and GPU quantities.
 type Resources struct {
 	CPU int64 `yaml:"cpu" json:"cpu"`
 	GPU int64 `yaml:"gpu" json:"gpu"`
diff --git a/internal/model/validation.go b/internal/model/validation.go
index b57db02..01eeece 100644
--- a/internal/model/validation.go
+++ b/internal/model/validation.go
@@ -73,7 +73,7 @@ func ValidateJobs(jobSet JobSet) error {
 }
 
 // ValidateTopologyRequirements verifies that every node has every topology key
-// required by the jobs. It should be called after loading both input files.
+// required by the jobs.
 func ValidateTopologyRequirements(cluster Cluster, jobSet JobSet) error {
 	requiredBy := make(map[string][]string)
 	for _, job := range jobSet.Jobs {