Add server version endpoint and bs version command

- GET /api/v1/version (unauthenticated) reports the server version
- bs version command shows both client and server versions as JSON
- Version is injected into server.Config from serve.go at startup
- Makefile derives version from git describe for local builds
- Document [skip ci] in releasing.md; clarify xattr note in README

Author: vector76

Makefile

@@ -1,7 +1,7 @@
 BINARY_NAME := bs
 BUILD_DIR := build
 SRC := ./cmd/bs
-VERSION ?= dev
+VERSION ?= $(patsubst v%,%,$(shell git describe --tags --always --dirty 2>/dev/null || echo "dev"))
 LDFLAGS := -X 'github.com/yourorg/beads_server/internal/cli.version=$(VERSION)'
 
 .PHONY: all build test clean linux windows darwin-arm64 darwin-amd64

README.md

@@ -38,7 +38,7 @@ xattr -d com.apple.quarantine bs   # clear Gatekeeper quarantine flag
 ./bs --version
 ```
 
-> The `xattr` step is required on macOS because the binary is not code-signed. Gatekeeper will block it otherwise.
+> The `xattr` step clears the Gatekeeper quarantine flag. It is needed if you downloaded via a browser; curl downloads typically don't set it, in which case the command does nothing.
 
 ### Build from source
 

docs/api-reference.md

@@ -2,7 +2,7 @@
 
 Base URL: `http://localhost:9999/api/v1` (configurable via `BS_PORT`)
 
-All endpoints except health require the header:
+All endpoints except health and version require the header:
 
 ```
 Authorization: Bearer <token>
@@ -28,6 +28,22 @@ No authentication required.
 
 ---
 
+## Version
+
+```
+GET /api/v1/version
+```
+
+No authentication required.
+
+**Response** `200`:
+
+```json
+{"version": "0.9.0"}
+```
+
+---
+
 ## Create Bead
 
 ```

docs/releasing.md

@@ -32,3 +32,13 @@ Use [semantic versioning](https://semver.org): `vMAJOR.MINOR.PATCH`
 ## Non-release commits
 
 Ordinary commits and PRs to `main` run CI (tests only) but do **not** produce a release. Only tagged commits trigger a release build.
+
+## Skipping CI entirely
+
+Add `[skip ci]` anywhere in the commit message to suppress all workflow runs for that push:
+
+```bash
+git commit -m "Fix typo in README [skip ci]"
+```
+
+Useful for trivial changes where you've already tested locally. Note: this only suppresses `push`-triggered runs — it does not affect PR workflow runs.

internal/cli/commands_query.go

@@ -1,13 +1,54 @@
 package cli
 
 import (
+	"encoding/json"
 	"fmt"
 	"net/url"
 	"strconv"
 
 	"github.com/spf13/cobra"
 )
 
+func newVersionCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "version",
+		Short: "Show client and server versions",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			c, err := NewClientFromEnv()
+			if err != nil {
+				return err
+			}
+
+			data, err := c.Do("GET", "/api/v1/version", nil)
+			if err != nil {
+				return err
+			}
+
+			var serverResp struct {
+				Version string `json:"version"`
+			}
+			if err := json.Unmarshal(data, &serverResp); err != nil {
+				return fmt.Errorf("parsing server response: %w", err)
+			}
+
+			combined := struct {
+				Client string `json:"client"`
+				Server string `json:"server"`
+			}{Client: version, Server: serverResp.Version}
+			b, err := json.Marshal(combined)
+			if err != nil {
+				return err
+			}
+			out, err := prettyJSON(b)
+			if err != nil {
+				return err
+			}
+			fmt.Fprintln(cmd.OutOrStdout(), out)
+			return nil
+		},
+	}
+}
+
 func newListCmd() *cobra.Command {
 	var all bool
 	var ready bool

internal/cli/commands_query_test.go

@@ -9,6 +9,24 @@ import (
 	"github.com/yourorg/beads_server/internal/store"
 )
 
+func TestVersionCmd(t *testing.T) {
+	ts := startTestServerWithVersion(t, "9.8.7")
+	setClientEnv(t, ts.URL)
+
+	out := runCmd(t, "version")
+
+	var result map[string]string
+	if err := json.Unmarshal([]byte(out), &result); err != nil {
+		t.Fatalf("parse output: %v\noutput: %s", err, out)
+	}
+	if result["server"] != "9.8.7" {
+		t.Errorf("server = %q, want 9.8.7", result["server"])
+	}
+	if result["client"] != version {
+		t.Errorf("client = %q, want %q", result["client"], version)
+	}
+}
+
 func TestList_Default(t *testing.T) {
 	ts := startTestServer(t)
 	setClientEnv(t, ts.URL)

internal/cli/commands_test.go

@@ -36,6 +36,24 @@ func startTestServer(t *testing.T) *httptest.Server {
 	return ts
 }
 
+// startTestServerWithVersion creates a test HTTP server reporting the given version string.
+func startTestServerWithVersion(t *testing.T, v string) *httptest.Server {
+	t.Helper()
+	dir := t.TempDir()
+	s, err := store.Load(filepath.Join(dir, "beads.json"))
+	if err != nil {
+		t.Fatalf("store.Load: %v", err)
+	}
+	p := server.NewSingleStoreProvider(testToken, s)
+	srv, err := server.New(server.Config{Port: 0, LogOutput: io.Discard, Version: v}, p)
+	if err != nil {
+		t.Fatalf("server.New: %v", err)
+	}
+	ts := httptest.NewServer(srv.Router)
+	t.Cleanup(ts.Close)
+	return ts
+}
+
 // setClientEnv sets BS_URL and BS_TOKEN env vars for a test, restoring them after.
 func setClientEnv(t *testing.T, url string) {
 	t.Helper()

internal/cli/root.go

@@ -26,6 +26,7 @@ func NewRootCmd() *cobra.Command {
 	root.AddCommand(serveCmd)
 
 	for _, cmd := range []*cobra.Command{
+		newVersionCmd(),
 		newWhoamiCmd(),
 		newAddCmd(),
 		newShowCmd(),

internal/cli/serve.go

@@ -91,7 +91,8 @@ func newServeCmd() *cobra.Command {
 			}
 
 			cfg := server.Config{
-				Port: port,
+				Port:    port,
+				Version: version,
 			}
 
 			srv, err := server.New(cfg, provider)

internal/server/server.go

@@ -26,6 +26,7 @@ type Config struct {
 	Port      int
 	DataFile  string
 	LogOutput io.Writer // destination for request logs; nil defaults to os.Stdout
+	Version   string    // reported by GET /api/v1/version
 }
 
 // Server is the HTTP server for the beads API.
@@ -62,6 +63,7 @@ func New(cfg Config, p StoreProvider) (*Server, error) {
 	srv.Router.Get("/", srv.handleDashboard)
 	srv.Router.Get("/bead/{project}/{id}", srv.handleBeadDetail)
 	srv.Router.Get("/api/v1/health", srv.handleHealth)
+	srv.Router.Get("/api/v1/version", srv.handleVersion)
 
 	// All other API routes require auth
 	srv.Router.Group(func(r chi.Router) {
@@ -126,6 +128,12 @@ func (s *Server) handleHealth(w http.ResponseWriter, r *http.Request) {
 	json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
 }
 
+// handleVersion returns the server version.
+func (s *Server) handleVersion(w http.ResponseWriter, r *http.Request) {
+	w.Header().Set("Content-Type", "application/json")
+	json.NewEncoder(w).Encode(map[string]string{"version": s.config.Version})
+}
+
 // requestLogger logs one line per request: method, path, status, and duration.
 func (s *Server) requestLogger(next http.Handler) http.Handler {
 	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {