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>
2026-02-03 01:59:42 -05:00
parent 46da0d78fd
commit 3b0f036077
1 changed files with 76 additions and 15 deletions
--- a/CLAUDE.md
+++ b/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)
- **Backend:** Complete (18 API endpoints, 40+ integration tests, all passing)
- **Frontend:** Core features complete, Tree Editor functional
+- **Phase:** Phase 2.5 - Step Library Foundation (In Progress)
+- **Backend:** Complete (20+ API endpoints, 40+ integration tests, all passing)
+- **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)
-│   │   │   ├── tag.py              # TreeTag model (NEW)
-│   │   │   └── folder.py           # UserFolder model (NEW)
+│   │   │   ├── category.py         # TreeCategory model
+│   │   │   ├── tag.py              # TreeTag model
+│   │   │   ├── 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)
- Personal tree branching (add custom steps during sessions)
- Step library with categories, tags, and ratings
- Tree forking and sharing
+### Phase 2.5 (In Progress)
+- ✅ Step Categories database and API
+- ✅ Step Library database schema (step_library, step_ratings, step_usage_log)
+- ✅ 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