docs: update Alpine.js migration guide and project guidelines

- Fix incorrect function references in ALPINE_COMPLETION_GUIDE.md
  - header.changeThemeTo -> changeTheme
  - header.logout -> logout
  - woodPaneling.change -> changeWoodPaneling
- Add SSR-first principles section to PROJECT_GUIDELINES.md
- Add page type classifications (Type 1, 2, 3)
- Fix extra asterisks on line 43
- Update to reference TypeScript instead of JavaScript

PROJECT_GUIDELINES.md

@@ -4,7 +4,7 @@
 
 ### Backend & Database
 
-- ❌ **NEVER modify backend code when working on frontend-only tasks**
+- ❌ **NEVER modify backend code when working on frontend-only tasks*
 - ❌ **NEVER modify database schema** unless explicitly instructed for full-stack changes
 - ❌ **NEVER use Docker** - use Podman only
 - ❌ **NEVER build server binaries locally** - all builds through Dockerfile/docker-compose
@@ -16,7 +16,7 @@
 
 ### Testing
 
-- ✅ **ALWAYS use `setupTestServer()` helper from `cmd/server/tests/test_helpers_test.go`**
+- ✅ **ALWAYS use `setupTestServer()` helper from `cmd/server/tests/test_helpers_test.go`*
 - ✅ **Share one test setup across all subtests** - call `setupTestServer()` once at test function level, not per subtest
 - ✅ **Prefer table-driven tests** - use `t.Run()` with test cases instead of duplicate test functions
 - ✅ **Configure database pools efficiently** - use `max_conns=1` for test pools (via `pgxpool.ParseConfig()`) to prevent connection exhaustion
@@ -27,7 +27,7 @@
 
 ### Frontend & Styling
 
-- ❌ **NEVER modify backend/API for frontend features without user confirmation**
+- ❌ **NEVER modify backend/API for frontend features without user confirmation*
 - ❌ **NEVER use custom CSS** - TailwindCSS classes only
   - **⚠️ EXCEPTION**: `templates/error.templ` may have inline CSS because error pages must work when main app fails (404, server errors, CSS fails to load)
 - ❌ **NEVER use JavaScript** - convert all to TypeScript
@@ -36,11 +36,11 @@
 - ✅ **DO use procedural/imperative style** as your default
 - ✅ **DO borrow functional techniques** when they simplify code
 - ✅ **DO avoid ideological purity** - the best paradigm is the one that fits the problem
-- ❌ **NEVER add new Dockerfiles without user confirmation**
+- ❌ **NEVER add new Dockerfiles without user confirmation*
 - ❌ **NEVER fetch initial data via AJAX on page load** - use server-side rendering instead
 - ❌ **NEVER break progressive enhancement** - pages must work without JavaScript
 
-**Note:** Go methods in the backend are fine and encouraged. This guideline applies to TypeScript/JavaScript frontend code only.\*\*
+**Note:** Go methods in the backend are fine and encouraged. This guideline applies to TypeScript/JavaScript frontend code only.
 
 ### General
 
@@ -49,7 +49,7 @@
 - ❌ **NEVER commit files with secrets** (.env, credentials.json, etc.)
 - ❌ **NEVER make assumptions** - ask clarifying questions when uncertain
 - ❌ **NEVER delete code without reading full context first** (minimum 20 lines before/after)
-- ❌ **NEVER make cascading fix-up edits without git diff review**
+- ❌ **NEVER make cascading fix-up edits without git diff review*
   - After compilation error: STOP, review `git diff`, understand full impact
   - Use revert/reapply pattern instead of blind fixes
 - ❌ **NEVER skip post-edit verification** - must compile after each file edit
@@ -58,8 +58,8 @@
   - Run `git commit -m "<message>"` and wait for completion
   - Run `git push` and wait for completion
   - Never use `&&` to chain git commands together
-- ✅ **Make good organized git commits for the entire project (not just what you changed) and push - run git add, commit, push sequentially as separate commands, no need to repeatedly check status**
+- ✅ **Make good organized git commits for the entire project (not just what you changed) and push - run git add, commit, push sequentially as separate commands, no need to repeatedly check status*
-- ✅ **Indentation is always 2 spaces unless the language prohibits it**
+- ✅ **Indentation is always 2 spaces unless the language prohibits it*
 
 ### Cascading Fix-up Pattern (PROHIBITED)
 
@@ -111,7 +111,7 @@ VERIFY → Compile successfully
   1. Identify the required change
   2. Explain why you need it
   3. Provide impact analysis
-  4. **ASK FOR USER CONFIRMATION before proceeding**
+  4. **ASK FOR USER CONFIRMATION before proceeding*
 
 ### When Working on Full-Stack Tasks
 
@@ -129,7 +129,7 @@ VERIFY → Compile successfully
 
 - ✅ Follow **pgx v5 standards** for all database operations
 - ✅ Treat schema changes as **ATOMIC** - complete success or complete rejection
-- ✅ **⚠️ CRITICAL: This is a pre-production application (NO production deployments exist)**
+- ✅ **⚠️ CRITICAL: This is a pre-production application (NO production deployments exist)*
   - When `database/schema/schema.sql` is updated, local databases must be updated
   - **Option 1 (Recommended):** Recreate database with fresh schema:
     ```bash
@@ -144,7 +144,7 @@ VERIFY → Compile successfully
 ### Build & Deployment
 
 - ✅ Use **Podman** exclusively (not Docker)
-- ✅ All builds through existing **Dockerfile** and **docker-compose.yml**
+- ✅ All builds through existing **Dockerfile** and **docker-compose.yml*
 - ✅ Stop building server binaries - everything goes through containers
 
 ### API Changes (Full-Stack Tasks Only)
@@ -176,7 +176,7 @@ VERIFY → Compile successfully
 ### Code Organization
 
 - ✅ Minimize project structure changes
-- ✅ Place new files in **contextually appropriate directories**
+- ✅ Place new files in **contextually appropriate directories*
 - ✅ Follow **KISS**, **DRY**, and **YAGNI** principles
 - ✅ Use **multiple, logical git commits** with clear messages
 - ❌ **NEVER duplicate types between handlers and templates** - define data types in handlers, reuse directly in templates
@@ -252,7 +252,7 @@ VERIFY → Compile successfully
 
 ### Process & Continuity
 
-- ✅ If mid-task and receive "no response", **continue the task**
+- ✅ If mid-task and receive "no response", **continue the task*
 - ✅ Verify no regressions before modifying/removing code
 
 ---
@@ -268,11 +268,38 @@ VERIFY → Compile successfully
 
 ### Frontend Stack
 
+- **Rendering**: SSR-first - Go templates render initial page with all data
+- **Interactivity**: Alpine.js for UI state (modals, dropdowns, transitions)
+- **Dynamic Updates**: HTMX for CRUD operations (no full page reloads)
 - **Styling**: TailwindCSS (no custom CSS)
 - **Language**: TypeScript (no JavaScript)
-- **Templates**: HTMX with server-side rendering
 - **Patterns**: Procedural/imperative with functional techniques where helpful (no OOP)
 
+### SSR-First Principles
+
+- ❌ **NEVER fetch initial data via AJAX** - server renders complete page
+- ❌ **NEVER fetch data in Alpine x-init** - data already SSR'd
+- ✅ **Use Alpine.js only for UI state** - modal visibility, dropdown toggles
+- ✅ **Use HTMX for dynamic operations** - form submissions, partial page updates
+- ✅ **x-init is for setup only** - event listeners, not data fetching
+- ✅ **Data fetching happens after user actions** - not on page load
+
+### Page Type Classifications
+
+1. **Type 1: 80% SSR (most pages)**
+   - Backend provides all initial data
+   - Alpine handles modals/dropdowns only
+   - x-init NEVER fetches data
+
+2. **Type 2: SSR + Interactive (dashboard, bookshelf)**
+   - Backend provides initial data
+   - Alpine handles interactivity (drag-drop, filtering)
+   - x-init ONLY sets up event listeners
+
+3. **Type 3: 80% TypeScript (analytics, complex dashboards)**
+   - Some client-side data fetching acceptable
+   - Still prefer SSR when possible
+
 ### Containerization
 
 - **Runtime**: Podman (not Docker)
@@ -427,14 +454,27 @@ git checkout -- internal/handlers/auth.go
 
 ## 🏗 ARCHITECTURAL PATTERNS
 
-### Current: Hybrid SSR
+### Current: SSR-First with Alpine.js + HTMX
 
 ```
-Browser → Go template (with data) → Display instantly
+Browser → Go template (SSR with all data) → Display instantly
                       ↓
-          JavaScript for interactivity (CRUD)
+        Alpine.js for UI state (modals, dropdowns)
                       ↓
-               Shared service layer
+                 HTMX for CRUD (forms, updates)
+                      ↓
+           Shared service layer (Go)
 ```
 
+**Layer Responsibilities:**
+
+| Layer | Responsibility |
+|-------|---------------|
+| **Go Template** | SSR initial page with real data |
+| **Alpine.js** | UI state only (x-data, x-show, transitions) |
+| **HTMX** | Dynamic updates without page reload |
+| **TypeScript** | Pure business logic (API calls, data processing) |
+
+**See also:** `SSR_FIRST_ALPINE_GUIDE.md` and `ALPINE_COMPLETION_GUIDE.md`
+
 Ultimately, whenever you are unsure just ask for confirmation.