jgordijn · jgordijn · May 10, 2026 · May 9, 2026 · May 9, 2026 · May 9, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -16,11 +16,12 @@ jobs:
 
       - uses: oven-sh/setup-bun@v2
 
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: just
+
       - name: Build frontend
-        run: |
-          cd ui && bun install && bun run build
-          mkdir -p ../cmd/knowledgehub/ui/build
-          cp -r build/* ../cmd/knowledgehub/ui/build/
+        run: just ui
 
       - name: Run tests
-        run: go test ./internal/... -count=1
+        run: just test
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -21,6 +21,10 @@ jobs:
 
       - uses: oven-sh/setup-bun@v2
 
+      - uses: taiki-e/install-action@v2
+        with:
+          tool: just
+
       - name: Determine version bump
         id: version
         run: |
@@ -50,25 +54,11 @@ jobs:
           echo "new_tag=$NEW_TAG" >> "$GITHUB_OUTPUT"
           echo "Bumping $LATEST -> $NEW_TAG"
 
-      - name: Build frontend
-        run: |
-          cd ui && bun install && bun run build
-          mkdir -p ../cmd/knowledgehub/ui/build
-          cp -r build/* ../cmd/knowledgehub/ui/build/
-
       - name: Run tests
-        run: go test ./internal/... -count=1
+        run: just test
 
-      - name: Build binary
-        run: |
-          CGO_ENABLED=1 GOOS=linux GOARCH=amd64 \
-            go build -ldflags="-s -w -X main.version=${{ steps.version.outputs.new_tag }}" -o build/knowledgehub ./cmd/knowledgehub
-
-      - name: Package tarball
-        run: |
-          tar czf build/knowledgehub-linux-amd64.tar.gz \
-            -C build knowledgehub \
-            -C .. knowledgehub.service knowledgehub-updater.sh knowledgehub-updater.service knowledgehub-updater.timer
+      - name: Build and package release
+        run: just release "${{ steps.version.outputs.new_tag }}"
 
       - name: Create tag and release
         env:

diff --git a/AGENTS.md b/AGENTS.md
@@ -51,7 +51,7 @@ ui/                    # SvelteKit frontend (static adapter, built with Bun)
 
 openspec/              # Design documents and task tracking
 knowledgehub.service   # systemd unit file
-Makefile               # Build, dev, test, release targets
+justfile               # Build, dev, test, release recipes
 ```
 
 ## Technology Stack
@@ -99,13 +99,13 @@ All collections require authentication (`@request.auth.id != ''`). Collections a
 cd ui && bun install && bun run dev
 
 # Backend dev (serves on :8090)
-make dev
+just dev
 
 # Full build (frontend + backend)
-make build
+just build
 
 # Run tests
-make test
+just test
 ```
 
 ### Running tests

diff --git a/Makefile b/Makefile
diff --git a/README.md b/README.md
@@ -18,6 +18,7 @@ A personal knowledge radar that monitors RSS feeds and blogs, summarizes article
 For **building** from source:
 - Go 1.24+
 - Bun (for building the frontend)
+- just (for running project recipes)
 
 For **running** the binary:
 - Linux amd64 (the release target)
@@ -30,7 +31,7 @@ For **running** the binary:
 ```bash
 git clone https://github.com/jgordijn/knowledgehub.git
 cd knowledgehub
-make build
+just build
 ```
 
 This builds the SvelteKit frontend, embeds it in the Go binary, and outputs `build/knowledgehub`.
@@ -97,7 +98,7 @@ sudo chown -R knowledgehub:knowledgehub /opt/knowledgehub
 ### Deploy
 
 ```bash
-# Download the latest release (or build with: make release)
+# Download the latest release (or build with: just release)
 curl -LO https://github.com/jgordijn/knowledgehub/releases/latest/download/knowledgehub-linux-amd64.tar.gz
 
 # Copy to the target machine (skip if downloading directly on the host)
@@ -156,10 +157,10 @@ The SQLite database in `/opt/knowledgehub/data` is preserved across updates. Poc
 
 ```bash
 # Run tests
-make test
+just test
 
 # Start the backend in dev mode (serves on :8090)
-make dev
+just dev
 
 # Frontend dev with hot reload (separate terminal)
 cd ui && bun run dev

diff --git a/docs/proofs/CAD-xxxx_replace-make-with-just/README.md b/docs/proofs/CAD-xxxx_replace-make-with-just/README.md
@@ -0,0 +1,84 @@
+# CAD-xxxx — Replace Make with Just Proof
+
+## Summary
+
+This proof shows that this worktree replaced the Makefile workflow with a root `justfile`, updated automation to use `just`, and preserved build/test/release behavior.
+
+Relevant changed files:
+
+- `justfile` added with `ui`, `build`, `dev`, `release`, `clean`, and `test` recipes.
+- `Makefile` removed.
+- `.github/workflows/ci.yml` and `.github/workflows/release.yml` install and invoke `just`.
+- `README.md` and `AGENTS.md` reference `just` commands.
+
+## UI / Operator Proof
+
+There is no product UI change in this feature. The user-visible interface for this change is the developer/operator CLI. Screenshots below show each observable CLI step.
+
+### 1. Recipe list exposes the replacement command surface
+
+![just recipe list](images/01-just-list.png)
+
+### 2. Test recipe runs Go tests and coverage
+
+![just test](images/02-just-test.png)
+
+### 3. Build recipe builds frontend assets, embeds them, and creates the local binary
+
+![just build](images/03-just-build.png)
+
+### 4. Release recipe accepts an explicit version and creates the expected tarball contents
+
+![just release](images/04-just-release.png)
+
+## API Proof
+
+The feature is build tooling, not an application API feature. To prove the `just build` artifact serves the embedded UI correctly, I started the locally built binary and recorded the HTTP request/response for `/`.
+
+### Request
+
+```http
+GET / HTTP/1.1
+Host: 127.0.0.1:18090
+```
+
+### Response excerpt
+
+```http
+HTTP/1.1 200 OK
+Content-Type: text/html; charset=utf-8
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    ...
+```
+
+Full captured request/response screenshot:
+
+![API root request response](images/05-api-root.png)
+
+## Verification Commands Run
+
+```bash
+just --list
+just test
+just build
+just release 1.2.3
+tar -tzf build/knowledgehub-linux-amd64.tar.gz
+KH_DATA_DIR=./proof_data ./build/knowledgehub serve --http=127.0.0.1:18090
+curl -i http://127.0.0.1:18090/
+```
+
+## Self-review
+
+This proof directly demonstrates the changes in this worktree:
+
+- The Makefile replacement is visible through `just --list`.
+- The new `test`, `build`, and `release` recipes execute successfully.
+- The release artifact path and contents match the expected deployment package.
+- The built application serves the embedded frontend over HTTP.
+
+Conclusion: proof is sufficient for a human or another agent to verify the functionality added by this worktree.
diff --git a/docs/proofs/CAD-xxxx_replace-make-with-just/images/01-just-list.png b/docs/proofs/CAD-xxxx_replace-make-with-just/images/01-just-list.png
diff --git a/docs/proofs/CAD-xxxx_replace-make-with-just/images/02-just-test.png b/docs/proofs/CAD-xxxx_replace-make-with-just/images/02-just-test.png
diff --git a/docs/proofs/CAD-xxxx_replace-make-with-just/images/03-just-build.png b/docs/proofs/CAD-xxxx_replace-make-with-just/images/03-just-build.png
diff --git a/docs/proofs/CAD-xxxx_replace-make-with-just/images/04-just-release.png b/docs/proofs/CAD-xxxx_replace-make-with-just/images/04-just-release.png
diff --git a/docs/proofs/CAD-xxxx_replace-make-with-just/images/05-api-root.png b/docs/proofs/CAD-xxxx_replace-make-with-just/images/05-api-root.png
diff --git a/justfile b/justfile
@@ -0,0 +1,41 @@
+app_name := "knowledgehub"
+build_dir := "./build"
+cmd_dir := "./cmd/knowledgehub"
+
+_default:
+    @just --list
+
+ui:
+    cd ui && bun install && bun run build
+    rm -rf {{cmd_dir}}/ui/build
+    mkdir -p {{cmd_dir}}/ui
+    cp -r ui/build {{cmd_dir}}/ui/build
+    touch {{cmd_dir}}/ui/build/.gitkeep
+
+build: ui
+    mkdir -p {{build_dir}}
+    CGO_ENABLED=1 go build -o {{build_dir}}/{{app_name}} {{cmd_dir}}
+
+dev:
+    go run {{cmd_dir}} serve
+
+release version="": ui
+    mkdir -p {{build_dir}}
+    if [ -n "{{version}}" ]; then \
+        ldflags="-s -w -X main.version={{version}}"; \
+    else \
+        ldflags="-s -w"; \
+    fi; \
+    CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="$ldflags" -o {{build_dir}}/{{app_name}} {{cmd_dir}}
+    tar czf {{build_dir}}/{{app_name}}-linux-amd64.tar.gz -C {{build_dir}} {{app_name}} -C .. knowledgehub.service knowledgehub-updater.sh knowledgehub-updater.service knowledgehub-updater.timer
+
+clean:
+    rm -rf {{build_dir}}
+    rm -rf ui/build
+    rm -rf {{cmd_dir}}/ui/build
+    mkdir -p {{cmd_dir}}/ui/build
+    touch {{cmd_dir}}/ui/build/.gitkeep
+
+test:
+    go test ./internal/... -count=1 -coverprofile=coverage.out -covermode=atomic
+    go tool cover -func=coverage.out | grep total
diff --git a/openspec/changes/archive/2026-05-09-replace-make-with-just/.openspec.yaml b/openspec/changes/archive/2026-05-09-replace-make-with-just/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-09
diff --git a/openspec/changes/archive/2026-05-09-replace-make-with-just/baseline.md b/openspec/changes/archive/2026-05-09-replace-make-with-just/baseline.md
@@ -0,0 +1,30 @@
+# Parity Baseline
+
+## Current Makefile targets
+
+- `ui`: `cd ui && bun install && bun run build`; replace `cmd/knowledgehub/ui/build` with `ui/build`.
+- `build`: depends on `ui`; `CGO_ENABLED=1 go build -o ./build/knowledgehub ./cmd/knowledgehub`.
+- `dev`: `go run ./cmd/knowledgehub serve`.
+- `release`: depends on `ui`; `CGO_ENABLED=1 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o ./build/knowledgehub ./cmd/knowledgehub`; creates `./build/knowledgehub-linux-amd64.tar.gz` containing `knowledgehub`, `knowledgehub.service`, `knowledgehub-updater.sh`, `knowledgehub-updater.service`, and `knowledgehub-updater.timer`.
+- `clean`: removes `./build`, `ui/build`, and `./cmd/knowledgehub/ui/build`.
+- `test`: runs `go test ./internal/... -coverprofile=coverage.out -covermode=atomic`; prints total coverage with `go tool cover -func=coverage.out | grep total`.
+
+## References inventory
+
+User-facing `make`/`Makefile` references requiring updates:
+- `README.md`: `make build`, `make release`, `make test`, `make dev`.
+- `AGENTS.md`: project tree and local command examples.
+- `openspec/specs/deployment/spec.md`: current accepted deployment spec will be updated when this change is archived; do not edit during implementation.
+
+Intentional/historical/code references not requiring user-facing command updates:
+- This change's OpenSpec artifacts mention the migration from Makefile to justfile.
+- Archived OpenSpec changes preserve historical Makefile references.
+- Go/Svelte source occurrences of `make` are language built-ins or prose unrelated to task runner usage.
+
+## Expected outputs to preserve
+
+- Build binary: `build/knowledgehub`.
+- Release tarball: `build/knowledgehub-linux-amd64.tar.gz`.
+- Release tarball members: `knowledgehub`, `knowledgehub.service`, `knowledgehub-updater.sh`, `knowledgehub-updater.service`, `knowledgehub-updater.timer`.
+- Embedded frontend output directory: `cmd/knowledgehub/ui/build` copied from `ui/build`.
+- Test coverage file: `coverage.out`, with total coverage printed.
diff --git a/openspec/changes/archive/2026-05-09-replace-make-with-just/design.md b/openspec/changes/archive/2026-05-09-replace-make-with-just/design.md
@@ -0,0 +1,45 @@
+## Context
+
+KnowledgeHub currently keeps local task automation in a root `Makefile` with targets for frontend build, backend build, dev server, release packaging, clean, and tests. GitHub Actions currently duplicate several of those commands inline rather than invoking the Makefile. The change should make `just` the single supported task runner while keeping the existing build, test, and release outputs equivalent.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Provide a root `justfile` with recipes equivalent to the current Makefile targets.
+- Update CI and release workflows so GitHub Actions install `just` and use the justfile for project build/test/release operations.
+- Preserve current release artifact contents, binary naming, embedded frontend behavior, and version injection in release builds.
+- Update project and agent-facing documentation that tells contributors to use `make`.
+- Remove the Makefile once parity is established.
+
+**Non-Goals:**
+- Changing application runtime behavior, ports, systemd units, updater behavior, or deployment topology.
+- Reworking frontend package management away from Bun.
+- Reworking Go test coverage thresholds beyond preserving current test commands.
+- Adding a second supported task-runner path; `make` compatibility is intentionally removed.
+
+## Decisions
+
+1. Use a root `justfile` as the canonical command surface.
+   - Recipes should map directly from existing targets: `ui`, `build`, `dev`, `release`, `clean`, and `test`.
+   - Variables such as app name, build directory, and command directory should be declared at the top of the justfile for readability.
+   - Alternative considered: keep Makefile as a shim that calls `just`. This was rejected because the goal is to remove make rather than maintain two entry points.
+
+2. Let workflows call justfile recipes instead of duplicating project build commands.
+   - CI should install `just`, run the frontend/embed recipe as needed, and run tests through `just` or dedicated CI recipe(s).
+   - Release should install `just` and use a release recipe that supports passing the computed version into Go linker flags.
+   - Alternative considered: keep inline workflow commands while only changing local development. This was rejected because the request explicitly includes GitHub workflows and because duplicated automation diverges over time.
+
+3. Add a version-aware release recipe rather than hard-coding release linker flags.
+   - The release workflow computes the tag, so the justfile should expose a way to pass that tag into the release binary build, for example via a `VERSION` environment variable or recipe argument.
+   - Local `just release` should still work with an empty/default version if no version is provided.
+
+4. Keep installation of `just` workflow-local.
+   - GitHub Actions should install `just` using a maintained action or package manager before invoking recipes.
+   - The repository does not need to vendor `just` or add it to the built application.
+
+## Risks / Trade-offs
+
+- [Risk] GitHub hosted runners do not include `just` by default → Mitigation: add an explicit setup/install step in every workflow job that invokes the justfile.
+- [Risk] Release artifacts may change if the tar command or build paths differ → Mitigation: preserve the current tarball contents and binary output paths exactly and verify with tests or a local release command.
+- [Risk] Workflow version injection may be lost when moving build commands into `just` → Mitigation: design the release recipe to accept `VERSION` and have the workflow pass `${{ steps.version.outputs.new_tag }}`.
+- [Risk] Documentation references to `make` may remain stale → Mitigation: search the repository for `make ` and `Makefile` references during implementation and update intentional user-facing references.
diff --git a/openspec/changes/archive/2026-05-09-replace-make-with-just/proposal.md b/openspec/changes/archive/2026-05-09-replace-make-with-just/proposal.md
@@ -0,0 +1,24 @@
+## Why
+
+The project currently exposes common developer and release commands through `make`, while the desired workflow is to standardize on `just` for clearer command definitions, argument handling, and cross-platform developer ergonomics. Replacing the Makefile with a justfile also requires aligning CI and release automation so local and GitHub workflows invoke the same task runner.
+
+## What Changes
+
+- Remove the root `Makefile` as the supported task runner entry point.
+- Add a root `justfile` that provides equivalent commands for development, testing, building, release packaging, cleaning, and any documented helper tasks currently exposed by `make`.
+- Update project documentation to use `just` commands instead of `make` commands.
+- Update GitHub Actions workflows to install/use `just` and call the justfile recipes for CI and release build steps where project task-runner commands are needed.
+- **BREAKING**: Developers and automation must use `just <recipe>` instead of `make <target>` after this change.
+
+## Capabilities
+
+### New Capabilities
+
+### Modified Capabilities
+- `deployment`: Build and release task-runner requirements change from Makefile targets to justfile recipes, including GitHub workflow compatibility.
+
+## Impact
+
+- Affected files include `Makefile`, new `justfile`, `.github/workflows/*.yml`, `README.md`, `AGENTS.md`, and any other documentation or scripts that mention `make` commands.
+- CI and release workflows must remain functionally equivalent after switching to `just`.
+- No runtime application APIs or database schemas are expected to change.