Update CLAUDE.md with Phase 2.5 progress

- Document completed Issues #3, #5, #6, #7
- Add Step Categories and Step Library API docs
- Add userPreferencesStore and SettingsPage to structure
- Add step_category.py and step_library.py models
- Document ALLOW_RAILWAY_ORIGINS env var for PR CORS
- Note VITE_API_URL must include https:// prefix
- Add /debug/cors endpoint documentation
- Update roadmap with Phase 2.5 progress

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -1,7 +1,7 @@
 # CLAUDE.md - Patherly Project Context
 
 > **Purpose:** This file provides Claude Code with essential context for working on the Patherly project.
-> **Last Updated:** February 2, 2026
+> **Last Updated:** February 3, 2026
 
 ---
 
@@ -19,9 +19,9 @@
 
 ## Current State
 
-- **Phase:** Phase 2 - Tree Editor (In Progress)
+- **Phase:** Phase 2.5 - Step Library Foundation (In Progress)
-- **Backend:** Complete (18 API endpoints, 40+ integration tests, all passing)
+- **Backend:** Complete (20+ API endpoints, 40+ integration tests, all passing)
-- **Frontend:** Core features complete, Tree Editor functional
+- **Frontend:** Core features complete, Tree Editor functional, Settings page added
 - **Database:** PostgreSQL with Docker (container name: `patherly_postgres`)
 
 ### What's Complete
@@ -42,9 +42,28 @@
     - Cascade delete for subfolders
   - Team admin role with scoped permissions
   - Filter trees by category, tags, and folders
+- **User Preferences (Issue #3):**
+  - Settings page at `/settings`
+  - Default export format preference (persisted in localStorage)
+  - Theme toggle integrated in Settings
+- **Step Categories (Issue #5):**
+  - Database table with 10 seeded global categories
+  - Full CRUD API at `/api/v1/step-categories`
+  - Team scoping support (global + team-specific)
+- **Step Library Schema (Issue #6):**
+  - `step_library` table for reusable troubleshooting steps
+  - `step_ratings` table for user ratings/reviews
+  - `step_usage_log` table for tracking verified use
+  - Support for decision/action/solution step types
+  - Visibility levels: private, team, public
+- **Step Library API (Issue #7):**
+  - Full CRUD at `/api/v1/steps`
+  - Full-text search endpoint
+  - Popular tags endpoint
+  - Rating/review system with verified use tracking
 
 ### What's In Progress
-- User preferences (export format default)
+- Step Library frontend UI (Phase 2.5 continuation)
 
 ### Deployment
 - **Production:** Railway (app.patherly.com / api.patherly.com)
@@ -99,9 +118,11 @@ patherly/
 │   │   │   ├── session.py          # JSONB path_taken, decisions
 │   │   │   ├── attachment.py
 │   │   │   ├── invite_code.py
-│   │   │   ├── category.py         # TreeCategory model (NEW)
+│   │   │   ├── category.py         # TreeCategory model
-│   │   │   ├── tag.py              # TreeTag model (NEW)
+│   │   │   ├── tag.py              # TreeTag model
-│   │   │   └── folder.py           # UserFolder model (NEW)
+│   │   │   ├── folder.py           # UserFolder model
+│   │   │   ├── step_category.py    # StepCategory model (NEW)
+│   │   │   └── step_library.py     # StepLibrary, StepRating, StepUsageLog (NEW)
 │   │   └── schemas/                # Pydantic schemas
 │   ├── alembic/                    # Database migrations
 │   ├── scripts/
@@ -125,7 +146,8 @@ patherly/
 │   │   ├── store/
 │   │   │   ├── authStore.ts        # Zustand auth state
 │   │   │   ├── themeStore.ts       # Dark/light theme
-│   │   │   └── treeEditorStore.ts  # Tree editor state (immer + zundo)
+│   │   │   ├── treeEditorStore.ts  # Tree editor state (immer + zundo)
+│   │   │   └── userPreferencesStore.ts  # User preferences (NEW)
 │   │   ├── components/
 │   │   │   ├── common/             # Modal, ErrorBoundary, ThemeToggle
 │   │   │   ├── layout/             # AppLayout, ProtectedRoute
@@ -139,7 +161,8 @@ patherly/
 │   │   │   ├── TreeNavigationPage.tsx  # Core feature
 │   │   │   ├── TreeEditorPage.tsx
 │   │   │   ├── SessionHistoryPage.tsx
-│   │   │   └── SessionDetailPage.tsx
+│   │   │   ├── SessionDetailPage.tsx
+│   │   │   └── SettingsPage.tsx    # User preferences (NEW)
 │   │   ├── types/                  # TypeScript interfaces
 │   │   └── lib/utils.ts            # cn() utility for Tailwind
 │   ├── package.json
@@ -352,7 +375,7 @@ PUT    /api/v1/tags/trees/{id}    - Replace tree's tags
 DELETE /api/v1/tags/trees/{id}/{slug} - Remove tag from tree
 ```
 
-### Folders (NEW)
+### Folders
 ```
 GET    /api/v1/folders            - List user's folders (includes parent_id)
 POST   /api/v1/folders            - Create folder (supports parent_id for subfolders)
@@ -370,6 +393,32 @@ DELETE /api/v1/folders/{id}/trees/{tree_id} - Remove tree from folder
 - Same folder name allowed under different parents
 - Moving folders validates cycle prevention
 
+### Step Categories (NEW)
+```
+GET    /api/v1/step-categories         - List categories (global + user's team)
+POST   /api/v1/step-categories         - Create category (admin/team_admin)
+GET    /api/v1/step-categories/{id}    - Get category
+PUT    /api/v1/step-categories/{id}    - Update category
+DELETE /api/v1/step-categories/{id}    - Soft delete category
+```
+
+### Step Library (NEW)
+```
+GET    /api/v1/steps              - List steps (filters: visibility, category_id, tags, min_rating, step_type, sort_by)
+POST   /api/v1/steps              - Create step
+GET    /api/v1/steps/{id}         - Get step details
+PUT    /api/v1/steps/{id}         - Update step (owner/admin)
+DELETE /api/v1/steps/{id}         - Soft delete step (owner/admin)
+GET    /api/v1/steps/search       - Full-text search (?q=query)
+GET    /api/v1/steps/tags/popular - Popular tags list
+
+# Rating endpoints
+POST   /api/v1/steps/{id}/rate    - Rate a step (1-5 stars + optional review)
+PUT    /api/v1/steps/{id}/rate    - Update your rating
+DELETE /api/v1/steps/{id}/rate    - Remove your rating
+GET    /api/v1/steps/{id}/reviews - Get reviews for a step
+```
+
 ### Sessions
 ```
 GET  /api/v1/sessions             - List user's sessions
@@ -441,6 +490,7 @@ interface Decision {
 - **Auth:** `useAuthStore` - Zustand with localStorage persistence
 - **Theme:** `useThemeStore` - Dark/light/system preference
 - **Tree Editor:** `useTreeEditorStore` - Zustand + immer + zundo (undo/redo)
+- **User Preferences:** `useUserPreferencesStore` - Zustand with localStorage persistence (export format default)
 
 ### Component Guidelines
 - Use `cn()` from `@/lib/utils` for Tailwind class merging
@@ -508,10 +558,16 @@ const response = await api.get('/api/v1/trees')
 
 ## Future Roadmap
 
-### Phase 2.5 (Planned)
+### Phase 2.5 (In Progress)
-- Personal tree branching (add custom steps during sessions)
+- ✅ Step Categories database and API
-- Step library with categories, tags, and ratings
+- ✅ Step Library database schema (step_library, step_ratings, step_usage_log)
-- Tree forking and sharing
+- ✅ Step Library CRUD API with search and ratings
+- ✅ User Preferences (Settings page, export format default)
+- 🔲 Step Library browser component (frontend)
+- 🔲 Add Custom Step button in tree navigation
+- 🔲 Custom step creation modal
+- 🔲 Personal tree branching (add custom steps during sessions)
+- 🔲 Tree forking and sharing
 
 ### Phase 3 (Planned)
 - File attachments (screenshots, logs)
@@ -580,6 +636,7 @@ Railway creates isolated preview environments for each pull request.
    - Switch to the PR environment
    - Click on each service → Settings → Networking → Generate Domain
 6. **Set `VITE_API_URL`** on frontend service to point to the PR backend URL
+   - **IMPORTANT:** Must include `https://` prefix (e.g., `https://patherly-patherly-pr-24.up.railway.app`)
 7. Redeploy frontend if needed
 8. Test at preview URLs
 9. Merge PR → auto-deploys to production
@@ -589,12 +646,16 @@ Railway creates isolated preview environments for each pull request.
 - PR environments inherit from `production` base environment
 - `REQUIRE_INVITE_CODE=true` is inherited (create invite codes in PR DB if needed)
 - `DATABASE_URL` is auto-provided for isolated PR database
+- `ALLOW_RAILWAY_ORIGINS=true` (shared variable) - enables CORS for all `*.up.railway.app` origins
 
 **Notes:**
 - Each PR gets a fresh database - no existing users/trees
 - Migrations run automatically via `releaseCommand`
 - Domains must be generated manually for each PR service
 
+**Debug Endpoints (available in PR environments):**
+- `/debug/cors` - Check CORS configuration (allow_railway_origins, cors_mode)
+
 ---
 
 ## Contact