docs: add simplest spritz deployment specification

api/auth_middleware_test.go

@@ -19,12 +19,12 @@ func TestAuthMiddlewareRequiresHeader(t *testing.T) {
 
 	handled := false
 	secured := e.Group("", s.authMiddleware())
-	secured.GET("/spritzes", func(c echo.Context) error {
+	secured.GET("/api/spritzes", func(c echo.Context) error {
 		handled = true
 		return c.JSON(http.StatusOK, map[string]string{"ok": "true"})
 	})
 
-	req := httptest.NewRequest(http.MethodGet, "/spritzes", nil)
+	req := httptest.NewRequest(http.MethodGet, "/api/spritzes", nil)
 	rec := httptest.NewRecorder()
 	e.ServeHTTP(rec, req)
 
@@ -48,7 +48,7 @@ func TestAuthMiddlewareSetsPrincipal(t *testing.T) {
 	e := echo.New()
 
 	secured := e.Group("", s.authMiddleware())
-	secured.GET("/spritzes", func(c echo.Context) error {
+	secured.GET("/api/spritzes", func(c echo.Context) error {
 		p, ok := principalFromContext(c)
 		if !ok {
 			return c.JSON(http.StatusInternalServerError, map[string]string{"error": "missing principal"})
@@ -59,7 +59,7 @@ func TestAuthMiddlewareSetsPrincipal(t *testing.T) {
 		})
 	})
 
-	req := httptest.NewRequest(http.MethodGet, "/spritzes", nil)
+	req := httptest.NewRequest(http.MethodGet, "/api/spritzes", nil)
 	req.Header.Set("X-Spritz-User-Id", "user-123")
 	req.Header.Set("X-Spritz-User-Email", "user@example.com")
 	rec := httptest.NewRecorder()

api/main.go

@@ -178,13 +178,14 @@ func main() {
 }
 
 func (s *server) registerRoutes(e *echo.Echo) {
-	e.GET("/healthz", s.handleHealthz)
-	internal := e.Group("/internal/v1", s.internalAuthMiddleware())
+	group := e.Group("/api")
+	group.GET("/healthz", s.handleHealthz)
+	internal := group.Group("/internal/v1", s.internalAuthMiddleware())
 	internal.GET("/shared-mounts/owner/:owner/:mount/latest", s.getSharedMountLatest)
 	internal.GET("/shared-mounts/owner/:owner/:mount/revisions/:revision", s.getSharedMountRevision)
 	internal.PUT("/shared-mounts/owner/:owner/:mount/revisions/:revision", s.putSharedMountRevision)
 	internal.PUT("/shared-mounts/owner/:owner/:mount/latest", s.putSharedMountLatest)
-	secured := e.Group("", s.authMiddleware())
+	secured := group.Group("", s.authMiddleware())
 	secured.GET("/spritzes", s.listSpritzes)
 	secured.POST("/spritzes", s.createSpritz)
 	secured.GET("/spritzes/:name", s.getSpritz)

api/main_routes_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/labstack/echo/v4"
+)
+
+func TestRegisterRoutesExposesHealthzUnderRootAndAPI(t *testing.T) {
+	s := &server{
+		auth:         authConfig{mode: authModeNone},
+		internalAuth: internalAuthConfig{enabled: false},
+		terminal:     terminalConfig{enabled: false},
+	}
+	e := echo.New()
+	s.registerRoutes(e)
+
+	apiReq := httptest.NewRequest(http.MethodGet, "/api/healthz", nil)
+	apiRec := httptest.NewRecorder()
+	e.ServeHTTP(apiRec, apiReq)
+	if apiRec.Code != http.StatusOK {
+		t.Fatalf("expected /api/healthz to return 200, got %d", apiRec.Code)
+	}
+
+	rootReq := httptest.NewRequest(http.MethodGet, "/healthz", nil)
+	rootRec := httptest.NewRecorder()
+	e.ServeHTTP(rootRec, rootReq)
+	if rootRec.Code != http.StatusNotFound {
+		t.Fatalf("expected /healthz to return 404, got %d", rootRec.Code)
+	}
+}
+
+func TestRegisterRoutesAppliesAuthToRootAndAPIPrefix(t *testing.T) {
+	s := &server{
+		auth: authConfig{
+			mode:     authModeHeader,
+			headerID: "X-Spritz-User-Id",
+		},
+		internalAuth: internalAuthConfig{enabled: false},
+		terminal:     terminalConfig{enabled: false},
+	}
+	e := echo.New()
+	s.registerRoutes(e)
+
+	apiReq := httptest.NewRequest(http.MethodGet, "/api/spritzes", nil)
+	apiRec := httptest.NewRecorder()
+	e.ServeHTTP(apiRec, apiReq)
+	if apiRec.Code != http.StatusUnauthorized {
+		t.Fatalf("expected /api/spritzes to return 401 without auth, got %d", apiRec.Code)
+	}
+	if !strings.Contains(apiRec.Body.String(), "unauthenticated") {
+		t.Fatalf("expected /api/spritzes response to mention unauthenticated, got %q", apiRec.Body.String())
+	}
+
+	rootReq := httptest.NewRequest(http.MethodGet, "/spritzes", nil)
+	rootRec := httptest.NewRecorder()
+	e.ServeHTTP(rootRec, rootReq)
+	if rootRec.Code != http.StatusNotFound {
+		t.Fatalf("expected /spritzes to return 404, got %d", rootRec.Code)
+	}
+}

cli/src/index.ts

@@ -34,7 +34,7 @@ type TtyContext = {
   ttyState: string | null;
 };
 
-const defaultApiBase = 'http://localhost:8080';
+const defaultApiBase = 'http://localhost:8080/api';
 const requestTimeoutMs = Number.parseInt(process.env.SPRITZ_REQUEST_TIMEOUT_MS || '10000', 10);
 const headerId = process.env.SPRITZ_API_HEADER_ID || 'X-Spritz-User-Id';
 const headerEmail = process.env.SPRITZ_API_HEADER_EMAIL || 'X-Spritz-User-Email';

docs/2026-02-09-user-config-subset.md

@@ -77,7 +77,7 @@ The server remains the only writer of sensitive spec fields.
 
 Recommended endpoints:
 
-- `POST /spritzes` accepts `userConfig` on create.
+- `POST /api/spritzes` accepts `userConfig` on create.
 
 ## UI Behavior