server and web app

2026-05-31 23:08:53 -04:00
parent 438b3b29a2
commit b3364447a1
24 changed files with 2318 additions and 153 deletions
--- a/apps/server/internal/httpserver/api_handlers_test.go
+++ b/apps/server/internal/httpserver/api_handlers_test.go
@@ -0,0 +1,390 @@
+package httpserver
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"log/slog"
+	"mime/multipart"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/tim/cairnquire/apps/server/internal/auth"
+	"github.com/tim/cairnquire/apps/server/internal/config"
+	"github.com/tim/cairnquire/apps/server/internal/database"
+	"github.com/tim/cairnquire/apps/server/internal/docs"
+	"github.com/tim/cairnquire/apps/server/internal/markdown"
+	"github.com/tim/cairnquire/apps/server/internal/realtime"
+	"github.com/tim/cairnquire/apps/server/internal/store"
+	"github.com/tim/cairnquire/apps/server/internal/sync"
+)
+
+type apiTestServer struct {
+	handler http.Handler
+	auth    *auth.Service
+	docs    *docs.Service
+	userID  string
+	root    string
+}
+
+func newAPITestServer(t *testing.T) *apiTestServer {
+	t.Helper()
+
+	ctx := context.Background()
+	root := t.TempDir()
+	sourceDir := filepath.Join(root, "content")
+	storeDir := filepath.Join(root, "files")
+	if err := os.MkdirAll(sourceDir, 0o755); err != nil {
+		t.Fatalf("create source dir: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(sourceDir, "hello.md"), []byte("# Hello\n\nInitial"), 0o644); err != nil {
+		t.Fatalf("write source fixture: %v", err)
+	}
+
+	db, err := database.Open(ctx, config.DatabaseConfig{Path: filepath.Join(root, "db.sqlite")})
+	if err != nil {
+		t.Fatalf("open test database: %v", err)
+	}
+	t.Cleanup(func() { _ = db.Close() })
+	if err := database.ApplyMigrations(ctx, db.SQL()); err != nil {
+		t.Fatalf("apply migrations: %v", err)
+	}
+
+	logger := slog.New(slog.NewTextHandler(io.Discard, nil))
+	contentStore, err := store.New(storeDir)
+	if err != nil {
+		t.Fatalf("create content store: %v", err)
+	}
+	docRepo := docs.NewRepository(db.SQL())
+	docService := docs.NewService(sourceDir, contentStore, markdown.NewRenderer(), docRepo, logger)
+	if _, err := docService.SyncSourceDir(ctx); err != nil {
+		t.Fatalf("sync source fixture: %v", err)
+	}
+
+	authService, err := auth.NewService(auth.NewRepository(db.SQL()), "http://localhost:8080")
+	if err != nil {
+		t.Fatalf("create auth service: %v", err)
+	}
+	user, err := authService.RegisterPasswordUser(ctx, "editor@example.com", "Editor", "very secure password", string(auth.RoleEditor))
+	if err != nil {
+		t.Fatalf("create test user: %v", err)
+	}
+
+	syncRepo := sync.NewRepository(db.SQL())
+	handler, err := New(Dependencies{
+		Config: config.Config{
+			Content: config.ContentConfig{
+				SourceDir: sourceDir,
+				StoreDir:  storeDir,
+			},
+			Web:  config.WebConfig{DistDir: filepath.Join(root, "web-dist")},
+			Auth: config.AuthConfig{PublicOrigin: "http://localhost:8080"},
+		},
+		Logger:       logger,
+		Documents:    docService,
+		Repository:   docRepo,
+		ContentStore: contentStore,
+		Hub:          realtime.NewHub(logger),
+		SyncService:  sync.NewService(syncRepo, docService, contentStore, sourceDir, logger),
+		SyncRepo:     syncRepo,
+		Auth:         authService,
+	})
+	if err != nil {
+		t.Fatalf("create http server: %v", err)
+	}
+
+	return &apiTestServer{
+		handler: handler,
+		auth:    authService,
+		docs:    docService,
+		userID:  user.ID,
+		root:    root,
+	}
+}
+
+func (s *apiTestServer) token(t *testing.T, scopes ...auth.Scope) string {
+	t.Helper()
+
+	created, err := s.auth.CreateAPIKey(context.Background(), s.userID, "test token", scopes, nil)
+	if err != nil {
+		t.Fatalf("create api token: %v", err)
+	}
+	return created.Token
+}
+
+func TestAPIUploadStoresAndServesAttachment(t *testing.T) {
+	server := newAPITestServer(t)
+	token := server.token(t, auth.ScopeDocsWrite)
+
+	body, contentType := multipartBody(t, "file", `unsafe"name.txt`, []byte("plain attachment\n"))
+	request := httptest.NewRequest(http.MethodPost, "/api/uploads", body)
+	request.Header.Set("Content-Type", contentType)
+	request.Header.Set("Authorization", "Bearer "+token)
+	recorder := httptest.NewRecorder()
+
+	server.handler.ServeHTTP(recorder, request)
+
+	response := recorder.Result()
+	if response.StatusCode != http.StatusCreated {
+		t.Fatalf("upload status = %d, want %d; body=%s", response.StatusCode, http.StatusCreated, recorder.Body.String())
+	}
+
+	var payload struct {
+		Hash          string `json:"hash"`
+		ContentType   string `json:"contentType"`
+		AttachmentURL string `json:"attachmentUrl"`
+	}
+	if err := json.NewDecoder(response.Body).Decode(&payload); err != nil {
+		t.Fatalf("decode upload response: %v", err)
+	}
+	if payload.Hash == "" {
+		t.Fatal("expected upload response hash")
+	}
+	if payload.ContentType != "text/plain; charset=utf-8" {
+		t.Fatalf("contentType = %q, want text/plain; charset=utf-8", payload.ContentType)
+	}
+	if payload.AttachmentURL != "/attachments/"+payload.Hash {
+		t.Fatalf("attachmentUrl = %q, want /attachments/%s", payload.AttachmentURL, payload.Hash)
+	}
+
+	download := httptest.NewRequest(http.MethodGet, payload.AttachmentURL, nil)
+	downloadRecorder := httptest.NewRecorder()
+	server.handler.ServeHTTP(downloadRecorder, download)
+
+	downloadResponse := downloadRecorder.Result()
+	if downloadResponse.StatusCode != http.StatusOK {
+		t.Fatalf("download status = %d, want %d", downloadResponse.StatusCode, http.StatusOK)
+	}
+	if got := downloadResponse.Header.Get("Content-Type"); got != payload.ContentType {
+		t.Fatalf("download content-type = %q, want %q", got, payload.ContentType)
+	}
+	if got := downloadResponse.Header.Get("Content-Disposition"); got != `inline; filename="unsafename.txt"` {
+		t.Fatalf("content-disposition = %q, want sanitized filename", got)
+	}
+	if downloadRecorder.Body.String() != "plain attachment\n" {
+		t.Fatalf("download body = %q", downloadRecorder.Body.String())
+	}
+}
+
+func TestAPIUploadRejectsTokenWithoutDocsWriteScope(t *testing.T) {
+	server := newAPITestServer(t)
+	token := server.token(t, auth.ScopeSyncRead, auth.ScopeSyncWrite)
+
+	body, contentType := multipartBody(t, "file", "note.txt", []byte("plain attachment\n"))
+	request := httptest.NewRequest(http.MethodPost, "/api/uploads", body)
+	request.Header.Set("Content-Type", contentType)
+	request.Header.Set("Authorization", "Bearer "+token)
+	recorder := httptest.NewRecorder()
+
+	server.handler.ServeHTTP(recorder, request)
+
+	if recorder.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d", recorder.Code, http.StatusForbidden)
+	}
+}
+
+func TestAPISyncInitAndContentFetchUseBearerScopes(t *testing.T) {
+	server := newAPITestServer(t)
+	token := server.token(t, auth.ScopeSyncRead, auth.ScopeSyncWrite)
+
+	request := jsonRequest(http.MethodPost, "/api/sync/init", map[string]string{"deviceId": "device-1"})
+	request.Header.Set("Authorization", "Bearer "+token)
+	recorder := httptest.NewRecorder()
+
+	server.handler.ServeHTTP(recorder, request)
+
+	if recorder.Code != http.StatusOK {
+		t.Fatalf("sync init status = %d, want %d; body=%s", recorder.Code, http.StatusOK, recorder.Body.String())
+	}
+
+	var payload struct {
+		SnapshotID     string           `json:"snapshotId"`
+		ServerSnapshot []sync.FileEntry `json:"serverSnapshot"`
+	}
+	if err := json.Unmarshal(recorder.Body.Bytes(), &payload); err != nil {
+		t.Fatalf("decode sync init response: %v", err)
+	}
+	if payload.SnapshotID == "" {
+		t.Fatal("expected snapshot id")
+	}
+	if len(payload.ServerSnapshot) != 1 || payload.ServerSnapshot[0].Path != "hello.md" {
+		t.Fatalf("server snapshot = %#v, want hello.md entry", payload.ServerSnapshot)
+	}
+
+	fetch := httptest.NewRequest(http.MethodGet, "/api/content/"+payload.ServerSnapshot[0].Hash, nil)
+	fetch.Header.Set("Authorization", "Bearer "+token)
+	fetchRecorder := httptest.NewRecorder()
+	server.handler.ServeHTTP(fetchRecorder, fetch)
+
+	if fetchRecorder.Code != http.StatusOK {
+		t.Fatalf("content fetch status = %d, want %d", fetchRecorder.Code, http.StatusOK)
+	}
+	if fetchRecorder.Body.String() != "# Hello\n\nInitial" {
+		t.Fatalf("content fetch body = %q", fetchRecorder.Body.String())
+	}
+}
+
+func TestAPISyncInitRejectsTokenWithoutSyncWriteScope(t *testing.T) {
+	server := newAPITestServer(t)
+	token := server.token(t, auth.ScopeDocsRead, auth.ScopeDocsWrite)
+
+	request := jsonRequest(http.MethodPost, "/api/sync/init", map[string]string{"deviceId": "device-1"})
+	request.Header.Set("Authorization", "Bearer "+token)
+	recorder := httptest.NewRecorder()
+
+	server.handler.ServeHTTP(recorder, request)
+
+	if recorder.Code != http.StatusForbidden {
+		t.Fatalf("status = %d, want %d", recorder.Code, http.StatusForbidden)
+	}
+}
+
+func TestAPISyncDeltaReturnsServerChanges(t *testing.T) {
+	server := newAPITestServer(t)
+	token := server.token(t, auth.ScopeSyncRead, auth.ScopeSyncWrite)
+
+	initRequest := jsonRequest(http.MethodPost, "/api/sync/init", map[string]string{"deviceId": "device-1"})
+	initRequest.Header.Set("Authorization", "Bearer "+token)
+	initRecorder := httptest.NewRecorder()
+	server.handler.ServeHTTP(initRecorder, initRequest)
+	if initRecorder.Code != http.StatusOK {
+		t.Fatalf("sync init status = %d, want %d; body=%s", initRecorder.Code, http.StatusOK, initRecorder.Body.String())
+	}
+
+	var initPayload struct {
+		SnapshotID string `json:"snapshotId"`
+	}
+	if err := json.Unmarshal(initRecorder.Body.Bytes(), &initPayload); err != nil {
+		t.Fatalf("decode sync init response: %v", err)
+	}
+
+	if err := os.WriteFile(filepath.Join(server.root, "content", "hello.md"), []byte("# Hello\n\nServer update"), 0o644); err != nil {
+		t.Fatalf("write server update: %v", err)
+	}
+
+	deltaRequest := jsonRequest(http.MethodPost, "/api/sync/delta", map[string]any{
+		"snapshotId":  initPayload.SnapshotID,
+		"clientDelta": []sync.Change{},
+	})
+	deltaRequest.Header.Set("Authorization", "Bearer "+token)
+	deltaRecorder := httptest.NewRecorder()
+	server.handler.ServeHTTP(deltaRecorder, deltaRequest)
+
+	if deltaRecorder.Code != http.StatusOK {
+		t.Fatalf("sync delta status = %d, want %d; body=%s", deltaRecorder.Code, http.StatusOK, deltaRecorder.Body.String())
+	}
+
+	var deltaPayload struct {
+		ServerDelta []sync.Change   `json:"serverDelta"`
+		Conflicts   []sync.Conflict `json:"conflicts"`
+	}
+	if err := json.Unmarshal(deltaRecorder.Body.Bytes(), &deltaPayload); err != nil {
+		t.Fatalf("decode sync delta response: %v", err)
+	}
+	if len(deltaPayload.ServerDelta) != 1 {
+		t.Fatalf("serverDelta = %#v, want one update", deltaPayload.ServerDelta)
+	}
+	change := deltaPayload.ServerDelta[0]
+	if change.Type != sync.ChangeUpdate || change.Path != "hello.md" || change.Hash == "" {
+		t.Fatalf("server delta change = %#v, want update for hello.md with hash", change)
+	}
+	if len(deltaPayload.Conflicts) != 0 {
+		t.Fatalf("conflicts = %#v, want none", deltaPayload.Conflicts)
+	}
+}
+
+func TestAPIDocumentSaveReturnsConflictForStaleBaseHash(t *testing.T) {
+	server := newAPITestServer(t)
+	token := server.token(t, auth.ScopeDocsWrite)
+
+	documents := httptest.NewRecorder()
+	server.handler.ServeHTTP(documents, httptest.NewRequest(http.MethodGet, "/api/documents", nil))
+	if documents.Code != http.StatusOK {
+		t.Fatalf("documents status = %d, want %d", documents.Code, http.StatusOK)
+	}
+
+	var list struct {
+		Documents []struct {
+			Path string `json:"path"`
+			Hash string `json:"hash"`
+		} `json:"documents"`
+	}
+	if err := json.Unmarshal(documents.Body.Bytes(), &list); err != nil {
+		t.Fatalf("decode documents: %v", err)
+	}
+	if len(list.Documents) != 1 {
+		t.Fatalf("documents = %#v, want one document", list.Documents)
+	}
+
+	if err := os.WriteFile(filepath.Join(server.root, "content", "hello.md"), []byte("# Hello\n\nServer edit"), 0o644); err != nil {
+		t.Fatalf("write server edit: %v", err)
+	}
+
+	save := jsonRequest(http.MethodPost, "/api/documents/hello", map[string]string{
+		"content":  "# Hello\n\nClient edit",
+		"baseHash": list.Documents[0].Hash,
+	})
+	save.Header.Set("Authorization", "Bearer "+token)
+	saveRecorder := httptest.NewRecorder()
+
+	server.handler.ServeHTTP(saveRecorder, save)
+
+	if saveRecorder.Code != http.StatusConflict {
+		t.Fatalf("save status = %d, want %d; body=%s", saveRecorder.Code, http.StatusConflict, saveRecorder.Body.String())
+	}
+
+	var conflict struct {
+		Status         string `json:"status"`
+		Path           string `json:"path"`
+		BaseHash       string `json:"baseHash"`
+		CurrentHash    string `json:"currentHash"`
+		CurrentContent string `json:"currentContent"`
+	}
+	if err := json.Unmarshal(saveRecorder.Body.Bytes(), &conflict); err != nil {
+		t.Fatalf("decode conflict response: %v", err)
+	}
+	if conflict.Status != "conflict" || conflict.Path != "hello.md" {
+		t.Fatalf("conflict payload = %#v, want conflict for hello.md", conflict)
+	}
+	if conflict.BaseHash != list.Documents[0].Hash {
+		t.Fatalf("baseHash = %q, want %q", conflict.BaseHash, list.Documents[0].Hash)
+	}
+	if conflict.CurrentHash == "" || conflict.CurrentHash == conflict.BaseHash {
+		t.Fatalf("currentHash = %q, baseHash = %q", conflict.CurrentHash, conflict.BaseHash)
+	}
+	if conflict.CurrentContent != "# Hello\n\nServer edit" {
+		t.Fatalf("currentContent = %q", conflict.CurrentContent)
+	}
+}
+
+func multipartBody(t *testing.T, fieldName, filename string, content []byte) (*bytes.Buffer, string) {
+	t.Helper()
+
+	body := &bytes.Buffer{}
+	writer := multipart.NewWriter(body)
+	part, err := writer.CreateFormFile(fieldName, filename)
+	if err != nil {
+		t.Fatalf("create multipart file: %v", err)
+	}
+	if _, err := part.Write(content); err != nil {
+		t.Fatalf("write multipart file: %v", err)
+	}
+	if err := writer.Close(); err != nil {
+		t.Fatalf("close multipart writer: %v", err)
+	}
+	return body, writer.FormDataContentType()
+}
+
+func jsonRequest(method, path string, payload any) *http.Request {
+	body, err := json.Marshal(payload)
+	if err != nil {
+		panic(err)
+	}
+	request := httptest.NewRequest(method, path, bytes.NewReader(body))
+	request.Header.Set("Content-Type", "application/json")
+	return request
+}
--- a/apps/server/internal/httpserver/collab_handlers.go
+++ b/apps/server/internal/httpserver/collab_handlers.go
@@ -0,0 +1,262 @@
+package httpserver
+
+import (
+	"encoding/json"
+	"net/http"
+
+	"github.com/go-chi/chi/v5"
+	"github.com/tim/cairnquire/apps/server/internal/collaboration"
+)
+
+// Comments
+
+func (s *Server) handleListComments(w http.ResponseWriter, r *http.Request) {
+	documentID := r.URL.Query().Get("document_id")
+	if documentID == "" {
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": "document_id is required"})
+		return
+	}
+
+	anchorHash := r.URL.Query().Get("anchor_hash")
+	var comments []collaboration.Comment
+	var err error
+	if anchorHash != "" {
+		comments, err = s.collaboration.ListCommentsByAnchor(r.Context(), documentID, anchorHash)
+	} else {
+		comments, err = s.collaboration.ListComments(r.Context(), documentID)
+	}
+	if err != nil {
+		s.logger.Warn("list comments", "error", err)
+		writeJSONWithStatus(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"comments": comments})
+}
+
+func (s *Server) handleCreateComment(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSONWithStatus(w, http.StatusUnauthorized, map[string]string{"error": "authentication required"})
+		return
+	}
+
+	var input collaboration.CreateCommentInput
+	if err := json.NewDecoder(r.Body).Decode(&input); err != nil {
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
+		return
+	}
+
+	comment, err := s.collaboration.CreateComment(r.Context(), principal, input)
+	if err != nil {
+		s.logger.Warn("create comment", "error", err)
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSONWithStatus(w, http.StatusCreated, comment)
+}
+
+func (s *Server) handleResolveComment(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSONWithStatus(w, http.StatusUnauthorized, map[string]string{"error": "authentication required"})
+		return
+	}
+
+	commentID := chi.URLParam(r, "id")
+	if err := s.collaboration.ResolveComment(r.Context(), principal, commentID); err != nil {
+		s.logger.Warn("resolve comment", "error", err)
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "resolved"})
+}
+
+// Notifications
+
+func (s *Server) handleListNotifications(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSONWithStatus(w, http.StatusUnauthorized, map[string]string{"error": "authentication required"})
+		return
+	}
+
+	unreadOnly := r.URL.Query().Get("unread") == "true"
+	limit := 50
+	if r.URL.Query().Get("limit") != "" {
+		// Parse limit if needed, but for now just use default
+	}
+
+	notifications, err := s.collaboration.ListNotifications(r.Context(), principal, unreadOnly, limit)
+	if err != nil {
+		s.logger.Warn("list notifications", "error", err)
+		writeJSONWithStatus(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]any{"notifications": notifications})
+}
+
+func (s *Server) handleMarkNotificationRead(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSONWithStatus(w, http.StatusUnauthorized, map[string]string{"error": "authentication required"})
+		return
+	}
+
+	notificationID := chi.URLParam(r, "id")
+	if err := s.collaboration.MarkNotificationRead(r.Context(), principal, notificationID); err != nil {
+		s.logger.Warn("mark notification read", "error", err)
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
+}
+
+func (s *Server) handleMarkAllNotificationsRead(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSONWithStatus(w, http.StatusUnauthorized, map[string]string{"error": "authentication required"})
+		return
+	}
+
+	if err := s.collaboration.MarkAllNotificationsRead(r.Context(), principal); err != nil {
+		s.logger.Warn("mark all notifications read", "error", err)
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "ok"})
+}
+
+func (s *Server) handleNotificationBell(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSON(w, http.StatusOK, collaboration.NotificationBell{UnreadCount: 0, Items: []collaboration.Notification{}})
+		return
+	}
+
+	bell, err := s.collaboration.GetBellStatus(r.Context(), principal)
+	if err != nil {
+		s.logger.Warn("notification bell", "error", err)
+		writeJSONWithStatus(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, bell)
+}
+
+// Watchers
+
+func (s *Server) handleWatchDocument(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSONWithStatus(w, http.StatusUnauthorized, map[string]string{"error": "authentication required"})
+		return
+	}
+
+	var req struct {
+		DocumentID string `json:"documentId"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
+		return
+	}
+
+	if err := s.collaboration.WatchDocument(r.Context(), principal, req.DocumentID); err != nil {
+		s.logger.Warn("watch document", "error", err)
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "watching"})
+}
+
+func (s *Server) handleUnwatchDocument(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSONWithStatus(w, http.StatusUnauthorized, map[string]string{"error": "authentication required"})
+		return
+	}
+
+	var req struct {
+		DocumentID string `json:"documentId"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
+		return
+	}
+
+	if err := s.collaboration.UnwatchDocument(r.Context(), principal, req.DocumentID); err != nil {
+		s.logger.Warn("unwatch document", "error", err)
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "unwatched"})
+}
+
+func (s *Server) handleWatchFolder(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSONWithStatus(w, http.StatusUnauthorized, map[string]string{"error": "authentication required"})
+		return
+	}
+
+	var req struct {
+		FolderPath string `json:"folderPath"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
+		return
+	}
+
+	if err := s.collaboration.WatchFolder(r.Context(), principal, req.FolderPath); err != nil {
+		s.logger.Warn("watch folder", "error", err)
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "watching"})
+}
+
+func (s *Server) handleUnwatchFolder(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSONWithStatus(w, http.StatusUnauthorized, map[string]string{"error": "authentication required"})
+		return
+	}
+
+	var req struct {
+		FolderPath string `json:"folderPath"`
+	}
+	if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": "invalid request body"})
+		return
+	}
+
+	if err := s.collaboration.UnwatchFolder(r.Context(), principal, req.FolderPath); err != nil {
+		s.logger.Warn("unwatch folder", "error", err)
+		writeJSONWithStatus(w, http.StatusBadRequest, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]string{"status": "unwatched"})
+}
+
+func (s *Server) handleIsWatching(w http.ResponseWriter, r *http.Request) {
+	principal, ok := requirePrincipal(r)
+	if !ok {
+		writeJSON(w, http.StatusOK, map[string]bool{"watching": false})
+		return
+	}
+
+	documentID := r.URL.Query().Get("document_id")
+	watching, err := s.collaboration.IsWatching(r.Context(), principal, documentID)
+	if err != nil {
+		s.logger.Warn("is watching", "error", err)
+		writeJSONWithStatus(w, http.StatusInternalServerError, map[string]string{"error": err.Error()})
+		return
+	}
+	writeJSON(w, http.StatusOK, map[string]bool{"watching": watching})
+}
+
+// Document page with comments
+
+func (s *Server) renderDocumentPageWithComments(w http.ResponseWriter, r *http.Request, pagePath string) {
+	// This is a helper that could be used to inject comments into the template
+	// For now, comments are fetched client-side via JS
+	s.renderDocumentPage(w, r, pagePath)
+}
--- a/apps/server/internal/httpserver/middleware.go
+++ b/apps/server/internal/httpserver/middleware.go
@@ -127,6 +127,12 @@ func requiredScopeForPath(r *http.Request) (auth.Scope, bool) {
 		return auth.ScopeSyncRead, true
 	case strings.HasPrefix(path, "/api/content/"):
 		return auth.ScopeSyncRead, true
+	case strings.HasPrefix(path, "/api/comments"):
+		return auth.ScopeDocsRead, true
+	case strings.HasPrefix(path, "/api/notifications"):
+		return auth.ScopeDocsRead, true
+	case strings.HasPrefix(path, "/api/watch"):
+		return auth.ScopeDocsRead, true
 	case strings.HasSuffix(path, "/edit"):
 		return auth.ScopeDocsWrite, true
 	default:
--- a/apps/server/internal/httpserver/server.go
+++ b/apps/server/internal/httpserver/server.go
@@ -13,6 +13,7 @@ import (
 	"github.com/go-chi/chi/v5/middleware"

 	"github.com/tim/cairnquire/apps/server/internal/auth"
+	"github.com/tim/cairnquire/apps/server/internal/collaboration"
 	"github.com/tim/cairnquire/apps/server/internal/config"
 	"github.com/tim/cairnquire/apps/server/internal/docs"
 	"github.com/tim/cairnquire/apps/server/internal/realtime"
@@ -24,30 +25,32 @@ import (
 var assets embed.FS

 type Dependencies struct {
-	Config       config.Config
-	Logger       *slog.Logger
-	Documents    *docs.Service
-	Repository   *docs.Repository
-	ContentStore *store.ContentStore
-	Hub          *realtime.Hub
-	SyncService  *sync.Service
-	SyncRepo     *sync.Repository
-	Auth         *auth.Service
+	Config        config.Config
+	Logger        *slog.Logger
+	Documents     *docs.Service
+	Repository    *docs.Repository
+	ContentStore  *store.ContentStore
+	Hub           *realtime.Hub
+	SyncService   *sync.Service
+	SyncRepo      *sync.Repository
+	Auth          *auth.Service
+	Collaboration *collaboration.Service
 }

 type Server struct {
-	config       config.Config
-	logger       *slog.Logger
-	documents    *docs.Service
-	repository   *docs.Repository
-	contentStore *store.ContentStore
-	hub          *realtime.Hub
-	syncService  *sync.Service
-	syncRepo     *sync.Repository
-	auth         *auth.Service
-	authLimiter  *rateLimiter
-	templates    *template.Template
-	webEnabled   bool
+	config        config.Config
+	logger        *slog.Logger
+	documents     *docs.Service
+	repository    *docs.Repository
+	contentStore  *store.ContentStore
+	hub           *realtime.Hub
+	syncService   *sync.Service
+	syncRepo      *sync.Repository
+	auth          *auth.Service
+	collaboration *collaboration.Service
+	authLimiter   *rateLimiter
+	templates     *template.Template
+	webEnabled    bool
 }

 func New(deps Dependencies) (http.Handler, error) {
@@ -64,17 +67,18 @@ func New(deps Dependencies) (http.Handler, error) {
 	}

 	server := &Server{
-		config:       deps.Config,
-		logger:       deps.Logger,
-		documents:    deps.Documents,
-		repository:   deps.Repository,
-		contentStore: deps.ContentStore,
-		hub:          deps.Hub,
-		syncService:  deps.SyncService,
-		syncRepo:     deps.SyncRepo,
-		auth:         deps.Auth,
-		authLimiter:  newRateLimiter(5, time.Minute),
-		templates:    templates,
+		config:        deps.Config,
+		logger:        deps.Logger,
+		documents:     deps.Documents,
+		repository:    deps.Repository,
+		contentStore:  deps.ContentStore,
+		hub:           deps.Hub,
+		syncService:   deps.SyncService,
+		syncRepo:      deps.SyncRepo,
+		auth:          deps.Auth,
+		collaboration: deps.Collaboration,
+		authLimiter:   newRateLimiter(5, time.Minute),
+		templates:     templates,
 	}

 	if _, err := os.Stat(deps.Config.Web.DistDir); err == nil {
@@ -129,6 +133,20 @@ func New(deps Dependencies) (http.Handler, error) {
 	router.Post("/api/uploads", server.handleUpload)
 	router.Get("/attachments/{hash}", server.handleAttachment)

+	// Collaboration endpoints
+	router.Get("/api/comments", server.handleListComments)
+	router.Post("/api/comments", server.handleCreateComment)
+	router.Post("/api/comments/{id}/resolve", server.handleResolveComment)
+	router.Get("/api/notifications", server.handleListNotifications)
+	router.Post("/api/notifications/{id}/read", server.handleMarkNotificationRead)
+	router.Post("/api/notifications/read-all", server.handleMarkAllNotificationsRead)
+	router.Get("/api/notifications/bell", server.handleNotificationBell)
+	router.Post("/api/watch/document", server.handleWatchDocument)
+	router.Post("/api/watch/folder", server.handleWatchFolder)
+	router.Delete("/api/watch/document", server.handleUnwatchDocument)
+	router.Delete("/api/watch/folder", server.handleUnwatchFolder)
+	router.Get("/api/watch/status", server.handleIsWatching)
+
 	// Sync protocol endpoints
 	router.Post("/api/sync/init", server.handleSyncInit)
 	router.Post("/api/sync/delta", server.handleSyncDelta)
--- a/apps/server/internal/httpserver/static/auth.js
+++ b/apps/server/internal/httpserver/static/auth.js
@@ -1,4 +1,56 @@
 (() => {
+  // Tab switching
+  document.querySelectorAll('.auth-tab-list').forEach(tabList => {
+    const tabs = tabList.querySelectorAll('[data-tab]');
+    const panels = tabList.closest('.auth-tabs').querySelectorAll('[data-tab-panel]');
+    
+    tabs.forEach(tab => {
+      tab.addEventListener('click', () => {
+        const target = tab.dataset.tab;
+        
+        tabs.forEach(t => {
+          t.classList.remove('is-active');
+          t.setAttribute('aria-selected', 'false');
+        });
+        tab.classList.add('is-active');
+        tab.setAttribute('aria-selected', 'true');
+        
+        panels.forEach(p => {
+          if (p.dataset.tabPanel === target) {
+            p.classList.add('is-active');
+            p.hidden = false;
+          } else {
+            p.classList.remove('is-active');
+            p.hidden = true;
+          }
+        });
+      });
+    });
+  });
+
+  // Register toggle
+  const registerToggle = document.querySelector('[data-register-toggle]');
+  const registerPanel = document.querySelector('[data-register-panel]');
+  const loginSection = document.querySelector('[data-login-section]');
+  const registerCancel = document.querySelector('[data-register-cancel]');
+
+  if (registerToggle && registerPanel && loginSection) {
+    registerToggle.addEventListener('click', () => {
+      loginSection.hidden = true;
+      registerPanel.hidden = false;
+    });
+  }
+
+  if (registerCancel && registerPanel && loginSection) {
+    registerCancel.addEventListener('click', () => {
+      registerPanel.hidden = true;
+      loginSection.hidden = false;
+      // Clear any registration form status messages
+      document.querySelector('[data-passkey-register-status]').textContent = '';
+      document.querySelector('[data-register-status]').textContent = '';
+    });
+  }
+
  const jsonHeaders = { "Content-Type": "application/json" };

  const postJSON = async (url, body, options = {}) => {
@@ -95,35 +147,76 @@
    }
  });

+  const webAuthnErrorMessage = (error) => {
+    console.error("WebAuthn error:", error.name, error.message, error);
+    switch (error.name) {
+      case "NotAllowedError":
+        return "Passkey creation was cancelled or no authenticator is available. If you dismissed a prompt, try again. If no prompt appeared, your device may not support passkeys.";
+      case "NotSupportedError":
+        return "This browser or device does not support passkeys.";
+      case "SecurityError":
+        return "Passkeys require a secure context. Use https:// or localhost.";
+      case "InvalidStateError":
+        return "A passkey may already exist for this account.";
+      default:
+        return error.message || "Passkey failed. Check the console for details.";
+    }
+  };
+
+  const checkPasskeySupport = async () => {
+    if (!window.PublicKeyCredential) {
+      return { supported: false, reason: "Passkeys are not available in this browser." };
+    }
+    try {
+      if (PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable) {
+        const available = await PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable();
+        if (!available) {
+          return { supported: true, reason: "No platform authenticator found (e.g., Touch ID, Windows Hello). You can still use a security key if you have one." };
+        }
+      }
+      return { supported: true };
+    } catch {
+      return { supported: true };
+    }
+  };
+
  document.querySelector("[data-passkey-register]")?.addEventListener("submit", async (event) => {
    event.preventDefault();
-    if (!window.PublicKeyCredential) {
-      setStatus("[data-passkey-register-status]", "Passkeys are not available in this browser.", true);
+    const support = await checkPasskeySupport();
+    if (!support.supported) {
+      setStatus("[data-passkey-register-status]", support.reason, true);
      return;
    }
+    if (support.reason) {
+      console.warn("Passkey support:", support.reason);
+    }
    try {
      const begin = await postJSON("/api/auth/passkeys/register/begin", formJSON(event.currentTarget));
      const credential = await navigator.credentials.create(normalizeCreateOptions(begin.options));
      await postJSON(`/api/auth/passkeys/register/finish?challengeId=${encodeURIComponent(begin.challengeId)}`, credentialToJSON(credential));
      setStatus("[data-passkey-register-status]", "Passkey created. Sign in with your passkey.");
    } catch (error) {
-      setStatus("[data-passkey-register-status]", error.message, true);
+      setStatus("[data-passkey-register-status]", webAuthnErrorMessage(error), true);
    }
  });

  document.querySelector("[data-passkey-login]")?.addEventListener("submit", async (event) => {
    event.preventDefault();
-    if (!window.PublicKeyCredential) {
-      setStatus("[data-passkey-login-status]", "Passkeys are not available in this browser.", true);
+    const support = await checkPasskeySupport();
+    if (!support.supported) {
+      setStatus("[data-passkey-login-status]", support.reason, true);
      return;
    }
+    if (support.reason) {
+      console.warn("Passkey support:", support.reason);
+    }
    try {
      const begin = await postJSON("/api/auth/passkeys/login/begin", formJSON(event.currentTarget));
      const credential = await navigator.credentials.get(normalizeRequestOptions(begin.options));
      await postJSON(`/api/auth/passkeys/login/finish?challengeId=${encodeURIComponent(begin.challengeId)}`, credentialToJSON(credential));
      window.location.href = authNext();
    } catch (error) {
-      setStatus("[data-passkey-login-status]", error.message, true);
+      setStatus("[data-passkey-login-status]", webAuthnErrorMessage(error), true);
    }
  });

--- a/apps/server/internal/httpserver/static/comments.js
+++ b/apps/server/internal/httpserver/static/comments.js
@@ -0,0 +1,123 @@
+(function () {
+  'use strict';
+
+  const documentPath = document.querySelector('[data-document-path]')?.dataset.documentPath;
+  const documentHash = document.querySelector('[data-document-hash]')?.dataset.documentHash;
+  const documentId = documentPath ? 'doc:' + documentPath.replace(/\.md$/, '') : null;
+
+  if (!documentId) return;
+
+  // Hash a paragraph's text content for anchoring
+  function hashParagraph(el) {
+    const text = (el.textContent || '').trim();
+    if (!text) return null;
+    // Simple hash: first 16 chars of base64 of char codes (deterministic)
+    let hash = 0;
+    for (let i = 0; i < text.length; i++) {
+      const char = text.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash = hash & hash;
+    }
+    return 'h' + Math.abs(hash).toString(36);
+  }
+
+  function addCommentButton(el, hash) {
+    const btn = document.createElement('button');
+    btn.className = 'comment-anchor-btn';
+    btn.title = 'Add comment';
+    btn.innerHTML = '+';
+    btn.addEventListener('click', () => promptComment(el, hash));
+    el.appendChild(btn);
+  }
+
+  async function promptComment(el, anchorHash) {
+    const text = window.prompt('Comment on this paragraph:');
+    if (!text || !text.trim()) return;
+
+    try {
+      const res = await fetch('/api/comments', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          documentId,
+          versionHash: documentHash,
+          content: text.trim(),
+          anchorHash,
+        }),
+      });
+      if (!res.ok) throw new Error(await res.text());
+      // Refresh comments display
+      await loadCommentsForAnchor(el, anchorHash);
+    } catch (err) {
+      window.alert('Failed to post comment: ' + err.message);
+    }
+  }
+
+  async function loadCommentsForAnchor(el, anchorHash) {
+    try {
+      const res = await fetch(`/api/comments?document_id=${encodeURIComponent(documentId)}&anchor_hash=${encodeURIComponent(anchorHash)}`);
+      if (!res.ok) return;
+      const data = await res.json();
+      renderComments(el, data.comments || []);
+    } catch (err) {
+      console.error('load comments', err);
+    }
+  }
+
+  function renderComments(el, comments) {
+    // Remove existing comment list
+    const existing = el.querySelector('.comment-list');
+    if (existing) existing.remove();
+
+    if (!comments.length) return;
+
+    const list = document.createElement('div');
+    list.className = 'comment-list';
+    comments.forEach(c => {
+      const item = document.createElement('div');
+      item.className = 'comment-item';
+      item.innerHTML = `
+        <div class="comment-meta">
+          <strong>${escapeHtml(c.authorName || 'Anonymous')}</strong>
+          <time>${formatDate(c.createdAt)}</time>
+        </div>
+        <div class="comment-body">${escapeHtml(c.content)}</div>
+      `;
+      list.appendChild(item);
+    });
+    el.appendChild(list);
+  }
+
+  function escapeHtml(str) {
+    const div = document.createElement('div');
+    div.textContent = str;
+    return div.innerHTML;
+  }
+
+  function formatDate(iso) {
+    const d = new Date(iso);
+    return d.toLocaleString();
+  }
+
+  // Initialize: hash all paragraphs in markdown body
+  function init() {
+    const body = document.querySelector('.markdown-body');
+    if (!body) return;
+
+    const paragraphs = body.querySelectorAll('p, h1, h2, h3, h4, h5, h6, li, blockquote, pre');
+    paragraphs.forEach(el => {
+      const hash = hashParagraph(el);
+      if (!hash) return;
+      el.dataset.anchorHash = hash;
+      el.classList.add('commentable');
+      addCommentButton(el, hash);
+      loadCommentsForAnchor(el, hash);
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+})();
--- a/apps/server/internal/httpserver/static/notification-bell.js
+++ b/apps/server/internal/httpserver/static/notification-bell.js
@@ -0,0 +1,123 @@
+(function () {
+  'use strict';
+
+  const bell = document.querySelector('[data-notification-bell]');
+  if (!bell) return;
+
+  const countEl = bell.querySelector('[data-unread-count]');
+  const dropdown = bell.querySelector('[data-notification-dropdown]');
+  let isOpen = false;
+
+  bell.addEventListener('click', () => {
+    isOpen = !isOpen;
+    dropdown.hidden = !isOpen;
+    if (isOpen) loadNotifications();
+  });
+
+  document.addEventListener('click', (e) => {
+    if (!bell.contains(e.target)) {
+      isOpen = false;
+      dropdown.hidden = true;
+    }
+  });
+
+  async function updateBell() {
+    try {
+      const res = await fetch('/api/notifications/bell');
+      if (!res.ok) return;
+      const data = await res.json();
+      const count = data.unreadCount || 0;
+      countEl.textContent = count > 99 ? '99+' : String(count);
+      countEl.hidden = count === 0;
+      bell.classList.toggle('has-unread', count > 0);
+    } catch (err) {
+      console.error('bell update', err);
+    }
+  }
+
+  async function loadNotifications() {
+    try {
+      const res = await fetch('/api/notifications?limit=20');
+      if (!res.ok) return;
+      const data = await res.json();
+      renderNotifications(data.notifications || []);
+    } catch (err) {
+      console.error('load notifications', err);
+    }
+  }
+
+  function renderNotifications(notifications) {
+    const list = dropdown.querySelector('ul');
+    if (!list) return;
+    list.innerHTML = '';
+
+    if (!notifications.length) {
+      list.innerHTML = '<li class="notification-empty">No notifications</li>';
+      return;
+    }
+
+    notifications.forEach(n => {
+      const li = document.createElement('li');
+      li.className = n.readAt ? 'notification-item is-read' : 'notification-item';
+      li.innerHTML = `
+        <div class="notification-message">${escapeHtml(n.message)}</div>
+        <time class="notification-time">${formatDate(n.createdAt)}</time>
+      `;
+      if (!n.readAt) {
+        li.addEventListener('click', () => markRead(n.id));
+      }
+      list.appendChild(li);
+    });
+
+    // Add "Mark all read" button
+    const footer = document.createElement('li');
+    footer.className = 'notification-footer';
+    const btn = document.createElement('button');
+    btn.textContent = 'Mark all read';
+    btn.addEventListener('click', markAllRead);
+    footer.appendChild(btn);
+    list.appendChild(footer);
+  }
+
+  async function markRead(id) {
+    try {
+      await fetch(`/api/notifications/${id}/read`, { method: 'POST' });
+      updateBell();
+      loadNotifications();
+    } catch (err) {
+      console.error('mark read', err);
+    }
+  }
+
+  async function markAllRead() {
+    try {
+      await fetch('/api/notifications/read-all', { method: 'POST' });
+      updateBell();
+      loadNotifications();
+    } catch (err) {
+      console.error('mark all read', err);
+    }
+  }
+
+  function escapeHtml(str) {
+    const div = document.createElement('div');
+    div.textContent = str;
+    return div.innerHTML;
+  }
+
+  function formatDate(iso) {
+    const d = new Date(iso);
+    return d.toLocaleString();
+  }
+
+  // Listen for WebSocket notification events
+  if (window.__cairnquireRealtime) {
+    window.__cairnquireRealtime.on('notification', () => {
+      updateBell();
+    });
+  }
+
+  // Poll every 60s as fallback
+  setInterval(updateBell, 60000);
+  updateBell();
+})();
--- a/apps/server/internal/httpserver/static/realtime.js
+++ b/apps/server/internal/httpserver/static/realtime.js
@@ -1,4 +1,23 @@
 (function () {
+  const realtimeCallbacks = {
+    notification: [],
+  };
+
+  window.__cairnquireRealtime = {
+    on: function (event, cb) {
+      if (realtimeCallbacks[event]) {
+        realtimeCallbacks[event].push(cb);
+      }
+    },
+    off: function (event, cb) {
+      if (realtimeCallbacks[event]) {
+        realtimeCallbacks[event] = realtimeCallbacks[event].filter(function (c) {
+          return c !== cb;
+        });
+      }
+    },
+  };
+
  const notice = document.querySelector("[data-version-notice]");
  const reload = document.querySelector("[data-version-reload]");
  const offlineNotice = document.querySelector("[data-offline-notice]");
@@ -300,6 +319,13 @@
        return;
      }

+      if (payload.type === "notification") {
+        realtimeCallbacks.notification.forEach(function (cb) {
+          cb(payload.data);
+        });
+        return;
+      }
+
      if (payload.type !== "document_version" || !payload.data) {
        return;
      }
--- a/apps/server/internal/httpserver/static/site.css
+++ b/apps/server/internal/httpserver/static/site.css
@@ -106,45 +106,61 @@ code {

 .site-nav {
  display: flex;
-  gap: 1.25rem;
+  gap: 0.5rem;
 }

 .site-nav a {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 36px;
+  height: 36px;
+  border-radius: 50%;
+  color: inherit;
  text-decoration: none;
-  font-size: 0.95rem;
+  transition: background 0.15s;
+}
+
+.site-nav a:hover {
+  background: rgba(0, 0, 0, 0.06);
+}
+
+.site-nav a svg {
+  display: block;
 }

 .site-search {
+  position: relative;
  display: flex;
  align-items: center;
-  gap: 0.5rem;
  flex: 1;
  max-width: 320px;
  margin: 0 1rem;
 }

+.site-search__icon {
+  position: absolute;
+  left: 0.6rem;
+  z-index: 1;
+  color: var(--muted);
+  pointer-events: none;
+}
+
 .site-search input {
  width: 100%;
-  padding: 0.45rem 0.75rem;
+  padding: 0.4rem 0.75rem 0.4rem 2rem;
  border: 1px solid var(--border);
-  border-radius: 0;
-  background: var(--panel-strong);
+  border-radius: 999px;
+  background: rgba(255, 255, 255, 0.6);
  font: inherit;
-  font-size: 0.9rem;
+  font-size: 0.825rem;
+  transition: border-color 0.15s, background 0.15s;
 }

 .site-search input:focus {
-  outline: 2px solid var(--accent-soft);
+  outline: none;
  border-color: var(--accent);
-}
-
-.site-search button {
-  padding: 0.45rem 0.6rem;
-  border: 1px solid var(--border);
-  border-radius: var(--radius-sm);
  background: var(--panel-strong);
-  cursor: pointer;
-  font-size: 0.9rem;
 }

 .site-main {
@@ -250,11 +266,30 @@ code {
  cursor: pointer;
 }

+.btn-primary,
 .auth-form button[type="submit"],
 .account-header button {
  border-color: color-mix(in srgb, var(--accent) 50%, var(--border));
  background: var(--accent);
  color: white;
+  padding: 0.85rem 1.75rem;
+  min-height: 3rem;
+  font-size: 1.05rem;
+  font-weight: 600;
+  box-shadow: 0 4px 12px color-mix(in srgb, var(--accent) 30%, transparent);
+  transition: background 0.15s ease, box-shadow 0.15s ease, transform 0.1s ease;
+}
+
+.btn-primary:hover,
+.auth-form button[type="submit"]:hover {
+  background: color-mix(in srgb, var(--accent) 85%, black);
+  box-shadow: 0 6px 16px color-mix(in srgb, var(--accent) 40%, transparent);
+}
+
+.btn-primary:active,
+.auth-form button[type="submit"]:active {
+  transform: translateY(1px);
+  box-shadow: 0 2px 6px color-mix(in srgb, var(--accent) 30%, transparent);
 }

 .auth-details {
@@ -289,6 +324,123 @@ code {
  color: var(--muted);
 }

+/* Auth tabs */
+.auth-tabs {
+  margin-bottom: 1.5rem;
+}
+
+.auth-tab-list {
+  display: flex;
+  gap: 0;
+  border-bottom: 1px solid var(--border);
+  margin-bottom: 1rem;
+}
+
+.auth-tab {
+  padding: 0.5rem 1rem;
+  border: 0;
+  border-bottom: 2px solid transparent;
+  background: transparent;
+  color: var(--muted);
+  font: inherit;
+  font-size: 0.9rem;
+  cursor: pointer;
+  transition: color 0.15s ease, border-color 0.15s ease;
+}
+
+.auth-tab:hover {
+  color: var(--text);
+}
+
+.auth-tab.is-active {
+  color: var(--accent);
+  border-bottom-color: var(--accent);
+  font-weight: 600;
+}
+
+.auth-tab-panel {
+  display: none;
+}
+
+.auth-tab-panel.is-active {
+  display: block;
+}
+
+/* Register CTA */
+.auth-register-cta {
+  margin-top: 1.5rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--border);
+  text-align: center;
+}
+
+.btn-cta {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  width: 100%;
+  padding: 1rem 2rem;
+  min-height: 3.5rem;
+  border: 2px solid var(--accent);
+  border-radius: var(--radius-sm);
+  background: var(--accent);
+  color: white;
+  font: inherit;
+  font-size: 1.15rem;
+  font-weight: 700;
+  letter-spacing: 0.01em;
+  cursor: pointer;
+  box-shadow: 0 6px 20px color-mix(in srgb, var(--accent) 35%, transparent);
+  transition: background 0.15s ease, box-shadow 0.15s ease, transform 0.1s ease;
+}
+
+.btn-cta:hover {
+  background: color-mix(in srgb, var(--accent) 85%, black);
+  box-shadow: 0 8px 24px color-mix(in srgb, var(--accent) 45%, transparent);
+}
+
+.btn-cta:active {
+  transform: translateY(2px);
+  box-shadow: 0 3px 10px color-mix(in srgb, var(--accent) 35%, transparent);
+}
+
+.auth-register-panel {
+  padding: 0;
+  border: none;
+  background: transparent;
+}
+
+.auth-register-cancel {
+  margin-top: 1.5rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--border);
+  text-align: center;
+}
+
+.btn-secondary {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 0.5rem;
+  padding: 0.65rem 1.25rem;
+  min-height: 2.6rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--muted);
+  font: inherit;
+  font-size: 0.95rem;
+  cursor: pointer;
+  transition: color 0.15s ease, border-color 0.15s ease, background 0.15s ease;
+}
+
+.btn-secondary:hover {
+  color: var(--text);
+  border-color: var(--muted);
+  background: var(--panel);
+}
+
 .account-header {
  display: flex;
  align-items: center;
@@ -1595,3 +1747,74 @@ code {
    background: oklch(0.705 0.165 55 / 0.07);
  }
 }
+
+/* Comments */
+.commentable {
+  position: relative;
+}
+
+.commentable:hover {
+  background: var(--accent-soft);
+}
+
+.comment-anchor-btn {
+  position: absolute;
+  right: -1.5rem;
+  top: 0.25rem;
+  width: 1.2rem;
+  height: 1.2rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 1px solid var(--border);
+  border-radius: 50%;
+  background: var(--panel-strong);
+  color: var(--accent);
+  font-size: 0.8rem;
+  font-weight: 700;
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.15s ease;
+}
+
+.commentable:hover .comment-anchor-btn {
+  opacity: 1;
+}
+
+.comment-list {
+  margin-top: 0.5rem;
+  padding: 0.5rem;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--panel);
+}
+
+.comment-item {
+  padding: 0.5rem 0;
+  border-bottom: 1px solid var(--border);
+}
+
+.comment-item:last-child {
+  border-bottom: 0;
+}
+
+.comment-meta {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  margin-bottom: 0.25rem;
+  font-size: 0.8rem;
+  color: var(--muted);
+}
+
+.comment-meta strong {
+  color: var(--text);
+}
+
+.comment-body {
+  font-size: 0.9rem;
+  line-height: 1.5;
+}
+
+
--- a/apps/server/internal/httpserver/templates/base.gohtml
+++ b/apps/server/internal/httpserver/templates/base.gohtml
@@ -22,14 +22,20 @@
        <img src="/static/favicon.png" alt="" width="64" height="64" decoding="async" />
        <span class="sr-only">Cairnquire</span>
      </a>
-      <form class="site-search" action="/" method="get">
-        <input type="search" name="q" placeholder="Search..." aria-label="Search documents" />
-        <button type="submit" aria-label="Search">🔍</button>
+      <form class="site-search" action="/" method="get" role="search">
+        <svg class="site-search__icon" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="11" cy="11" r="8"/><line x1="21" y1="21" x2="16.65" y2="16.65"/></svg>
+        <input type="search" name="q" placeholder="Search documents…" aria-label="Search documents" />
      </form>
      <nav class="site-nav">
-        <a href="/">Docs</a>
-        <a href="/account">Account</a>
-        {{ if .WebEnabled }}<a href="/app/">Admin</a>{{ end }}
+        <a href="/help" aria-label="Help" title="Help">
+          <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>
+        </a>
+        <a href="/settings" aria-label="Settings" title="Settings">
+          <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z"/><circle cx="12" cy="12" r="3"/></svg>
+        </a>
+        <a href="/account" aria-label="Account" title="Account">
+          <svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M19 21v-2a4 4 0 0 0-4-4H9a4 4 0 0 0-4 4v2"/><circle cx="12" cy="7" r="4"/></svg>
+        </a>
      </nav>
    </div>
  </header>
@@ -80,6 +86,7 @@
  <script src="/static/editor.js" defer></script>
  <script src="/static/auth.js" defer></script>
  <script src="/static/render.js" defer></script>
+  <script src="/static/comments.js" defer></script>
 </body>

 </html>
--- a/apps/server/internal/httpserver/templates/login.gohtml
+++ b/apps/server/internal/httpserver/templates/login.gohtml
@@ -6,71 +6,94 @@
  <div class="auth-panel">
    <div class="auth-panel__header">
      <p class="eyebrow">Cairnquire</p>
-      <h1>Sign in</h1>
+      <h1>Log In</h1>
    </div>

-    <div class="auth-grid">
-      <form class="auth-form" data-auth-login>
-        <h2>Password</h2>
-        <label>
-          Email
-          <input type="email" name="email" autocomplete="email" required />
-        </label>
-        <label>
-          Password
-          <input type="password" name="password" autocomplete="current-password" required />
-        </label>
-        <button type="submit">Sign in</button>
-        <p class="form-status" data-login-status></p>
-      </form>
+    <div class="auth-login-section" data-login-section>
+      <div class="auth-tabs">
+        <div class="auth-tab-list" role="tablist">
+          <button type="button" class="auth-tab is-active" role="tab" aria-selected="true" data-tab="passkey">Passkey</button>
+          <button type="button" class="auth-tab" role="tab" aria-selected="false" data-tab="password">Password</button>
+        </div>

-      <form class="auth-form" data-passkey-login>
-        <h2>Passkey</h2>
-        <label>
-          Email
-          <input type="email" name="email" autocomplete="username webauthn" required />
-        </label>
-        <button type="submit">Use passkey</button>
-        <p class="form-status" data-passkey-login-status></p>
-      </form>
-    </div>
+        <div class="auth-tab-panel is-active" role="tabpanel" data-tab-panel="passkey">
+          <form class="auth-form" data-passkey-login>
+            <label>
+              Email
+              <input type="email" name="email" autocomplete="username webauthn" required />
+            </label>
+            <button type="submit" class="btn-primary">Use passkey</button>
+            <p class="form-status" data-passkey-login-status></p>
+          </form>
+        </div>

-    <details class="auth-details">
-      <summary>Create an account</summary>
-      <div class="auth-grid">
-        <form class="auth-form" data-auth-register>
-          <h2>Password account</h2>
-          <label>
-            Email
-            <input type="email" name="email" autocomplete="email" required />
-          </label>
-          <label>
-            Display name
-            <input type="text" name="displayName" autocomplete="name" />
-          </label>
-          <label>
-            Password
-            <input type="password" name="password" autocomplete="new-password" minlength="12" required />
-          </label>
-          <button type="submit">Register</button>
-          <p class="form-status" data-register-status></p>
-        </form>
-
-        <form class="auth-form" data-passkey-register>
-          <h2>Passkey account</h2>
-          <label>
-            Email
-            <input type="email" name="email" autocomplete="email" required />
-          </label>
-          <label>
-            Display name
-            <input type="text" name="displayName" autocomplete="name" />
-          </label>
-          <button type="submit">Create passkey</button>
-          <p class="form-status" data-passkey-register-status></p>
-        </form>
+        <div class="auth-tab-panel" role="tabpanel" data-tab-panel="password" hidden>
+          <form class="auth-form" data-auth-login>
+            <label>
+              Email
+              <input type="email" name="email" autocomplete="email" required />
+            </label>
+            <label>
+              Password
+              <input type="password" name="password" autocomplete="current-password" required />
+            </label>
+            <button type="submit" class="btn-primary">Sign in</button>
+            <p class="form-status" data-login-status></p>
+          </form>
+        </div>
      </div>
-    </details>
+
+      <div class="auth-register-cta">
+        <button type="button" class="btn-cta" data-register-toggle>Create an Account</button>
+      </div>
+    </div>
+
+    <div class="auth-register-panel" data-register-panel hidden>
+      <div class="auth-tabs">
+        <div class="auth-tab-list" role="tablist">
+          <button type="button" class="auth-tab is-active" role="tab" aria-selected="true" data-tab="passkey-register">Passkey</button>
+          <button type="button" class="auth-tab" role="tab" aria-selected="false" data-tab="password-register">Password</button>
+        </div>
+
+        <div class="auth-tab-panel is-active" role="tabpanel" data-tab-panel="passkey-register">
+          <form class="auth-form" data-passkey-register>
+            <label>
+              Email
+              <input type="email" name="email" autocomplete="email" required />
+            </label>
+            <label>
+              Display name
+              <input type="text" name="displayName" autocomplete="name" />
+            </label>
+            <button type="submit" class="btn-primary">Create passkey</button>
+            <p class="form-status" data-passkey-register-status></p>
+          </form>
+        </div>
+
+        <div class="auth-tab-panel" role="tabpanel" data-tab-panel="password-register" hidden>
+          <form class="auth-form" data-auth-register>
+            <label>
+              Email
+              <input type="email" name="email" autocomplete="email" required />
+            </label>
+            <label>
+              Display name
+              <input type="text" name="displayName" autocomplete="name" />
+            </label>
+            <label>
+              Password
+              <input type="password" name="password" autocomplete="new-password" minlength="12" required />
+            </label>
+            <button type="submit" class="btn-primary">Register</button>
+            <p class="form-status" data-register-status></p>
+          </form>
+        </div>
+      </div>
+
+      <div class="auth-register-cancel">
+        <button type="button" class="btn-secondary" data-register-cancel>Cancel — Back to Log In</button>
+      </div>
+    </div>
  </div>
 </section>
 {{ end }}