# GitHub Issues Migration Instructions > **For Claude Code:** Use these instructions to set up GitHub Issues for Patherly > **Repository:** github.com/patherly/patherly > **Date:** February 2, 2026 --- ## Status Snapshot (Updated February 12, 2026) Live GitHub status (`patherly/patherly`): - Total issues: 54 - Closed: 38 - Open: 16 ### Completed So Far (Closed Issues) - Foundation and initial Phase 2.5 set: - `#2` to `#14` closed - `#15` to `#19` closed - Historical bug backlog: - `#20` to `#23` closed - Additional cleanup and UX/quality work: - `#25`, `#28`, `#29`, `#30`, `#31`, `#33`, `#34`, `#35`, `#36`, `#37`, `#38` closed - Recent quick wins delivered: - `#51` Session timer - `#52` Keyboard-first navigation - `#53` Repeat last session - `#54` Session draft auto-recovery - `#55` Copy individual step to clipboard ### Current Open Feature Queue - `#56` to `#71` remain open (newer strategic feature set, created February 10, 2026) Note: This file remains the original migration/setup checklist; the section above is the current progress snapshot. --- ## Step 1: Create Labels Create the following labels in the repository: | Label | Color (hex) | Description | |-------|-------------|-------------| | `bug` | `d73a4a` | Something isn't working | | `feature` | `0e8a16` | New functionality | | `enhancement` | `a2eeef` | Improvement to existing feature | | `documentation` | `0075ca` | Documentation updates | | `backend` | `7057ff` | FastAPI/Python work | | `frontend` | `fbca04` | React work | | `database` | `b60205` | PostgreSQL/schema changes | | `priority: high` | `d93f0b` | Do this soon | | `priority: medium` | `fbca04` | Important but not urgent | | `priority: low` | `c5def5` | Nice to have | --- ## Step 2: Create Milestones | Milestone | Description | Due Date | |-----------|-------------|----------| | Phase 2 Completion | Tree editor polish, deployment | (leave open) | | Phase 2.5 | Personal branching, step library | (leave open) | | Backlog | Ideas not yet scheduled | (no due date) | --- ## Step 3: Create Issues ### Phase 2 Remaining (3 issues) **Issue 1:** - Title: Tree Editor Validation - required fields and orphan detection - Labels: `feature`, `frontend`, `priority: high` - Milestone: Phase 2 Completion - Body: ``` Add validation to the tree editor: - [ ] Required fields validation (name, at least one node) - [ ] Orphan node detection (nodes not reachable from root) - [ ] Circular reference detection - [ ] Show validation errors before save - [ ] Prevent save if validation fails ``` **Issue 2:** - Title: User Preferences - export format default setting - Labels: `feature`, `frontend`, `priority: medium` - Milestone: Phase 2 Completion - Body: ``` Add export format preference to user settings: - [ ] Add "Default Export Format" dropdown in settings (Markdown/Text/HTML) - [ ] Persist preference in localStorage - [ ] Use preference as default in export dialog - [ ] Dark mode toggle already complete ✅ ``` **Issue 3:** - Title: Deploy to Railway - CI/CD pipeline setup - Labels: `feature`, `priority: high` - Milestone: Phase 2 Completion - Body: ``` Set up production deployment on Railway Pro: - [ ] Configure Railway project with 3 services (PostgreSQL, backend, frontend) - [ ] Set up environment variables - [ ] Configure custom domains (patherly.com, api.patherly.com) - [ ] Set up PR environments for testing - [ ] Document deployment process ``` --- ### Phase 2.5 Features (15 issues) **Issue 4:** - Title: Step Categories - database table and seed data - Labels: `feature`, `backend`, `database`, `priority: high` - Milestone: Phase 2.5 - Body: ``` Create step_categories table for organizing the step library: - [ ] Create Alembic migration for step_categories table - [ ] Add SQLAlchemy model - [ ] Seed default categories (Citrix/VDI, Active Directory, Microsoft 365, Networking, etc.) - [ ] Create API endpoints for category CRUD (admin only) Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 5:** - Title: Step Library - database schema and migrations - Labels: `feature`, `backend`, `database`, `priority: high` - Milestone: Phase 2.5 - Body: ``` Create step_library table for reusable troubleshooting steps: - [ ] Create Alembic migration - [ ] Add SQLAlchemy model with fields: title, step_type, content (JSONB), visibility, category_id, tags, ratings aggregates - [ ] Add indexes for search and filtering - [ ] Add step_ratings table for user ratings/reviews - [ ] Add step_usage_log table for "Verified Use" tracking Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 6:** - Title: Step Library - CRUD API endpoints - Labels: `feature`, `backend`, `priority: high` - Milestone: Phase 2.5 - Body: ``` Create API endpoints for step library: - [ ] GET /api/v1/steps - List steps with filters (visibility, category, tags, rating) - [ ] GET /api/v1/steps/{id} - Get step details - [ ] POST /api/v1/steps - Create new step - [ ] PUT /api/v1/steps/{id} - Update step - [ ] DELETE /api/v1/steps/{id} - Soft delete - [ ] GET /api/v1/steps/search - Full-text search - [ ] GET /api/v1/steps/tags/popular - Popular tags Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 7:** - Title: Step Library - rating and review system - Labels: `feature`, `backend`, `priority: medium` - Milestone: Phase 2.5 - Body: ``` Implement step rating and review system: - [ ] POST /api/v1/steps/{id}/rate - Rate a step (1-5 stars + optional review) - [ ] PUT /api/v1/steps/{id}/rate - Update rating - [ ] DELETE /api/v1/steps/{id}/rate - Remove rating - [ ] POST /api/v1/steps/{id}/helpful - Vote helpful (yes/no) - [ ] GET /api/v1/steps/{id}/reviews - Get reviews - [ ] Track "Verified Use" when step is actually used in a session - [ ] Calculate and update aggregated ratings on step_library table Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 8:** - Title: Add Custom Step button in tree navigation - Labels: `feature`, `frontend`, `priority: high` - Milestone: Phase 2.5 - Body: ``` Add ability to insert custom steps during active troubleshooting: - [ ] Add "+ Add Custom Step" button at each decision node - [ ] Button opens modal with two tabs: "Type My Own" and "Browse Library" - [ ] Custom steps inserted into session only (not original tree) - [ ] Visual indicator showing step is custom/user-added - [ ] Custom steps included in session export Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 9:** - Title: Custom step creation modal - Labels: `feature`, `frontend`, `priority: high` - Milestone: Phase 2.5 - Body: ``` Create modal for adding custom steps: - [ ] Tab 1: "Type My Own" - form to create step (type, title, description, commands) - [ ] Tab 2: "Browse Library" - search and select from step library - [ ] Option to save custom step to personal library - [ ] Validate step before insertion - [ ] Insert step into current session Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 10:** - Title: Step library browser component - Labels: `feature`, `frontend`, `priority: medium` - Milestone: Phase 2.5 - Body: ``` Create UI component for browsing step library: - [ ] Search input with full-text search - [ ] Category filter dropdown - [ ] Tag filter (show popular tags as chips) - [ ] Minimum rating filter - [ ] Sort options (recent, popular, rating) - [ ] Step cards showing title, type, rating, usage count - [ ] Step preview/detail modal - [ ] Insert button to add to session Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 11:** - Title: User Trees - database schema - Labels: `feature`, `backend`, `database`, `priority: medium` - Milestone: Phase 2.5 - Body: ``` Create user_trees table for personal/forked trees: - [ ] Create Alembic migration - [ ] Fields: user_id, forked_from_tree_id, name, tree_content (JSONB), visibility, share_token - [ ] Add session_custom_steps table to track custom steps per session - [ ] Add indexes for user lookup and share token Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 12:** - Title: Tree forking API endpoint - Labels: `feature`, `backend`, `priority: medium` - Milestone: Phase 2.5 - Body: ``` Create API for forking trees: - [ ] POST /api/v1/user-trees/fork/{tree_id} - Fork an official tree - [ ] Deep copy tree structure to user_trees - [ ] Track lineage (forked_from_tree_id, forked_at_version) - [ ] Increment fork_count on original tree Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 13:** - Title: User Trees - CRUD endpoints - Labels: `feature`, `backend`, `priority: medium` - Milestone: Phase 2.5 - Body: ``` Create API endpoints for user tree management: - [ ] GET /api/v1/user-trees - List user's custom trees - [ ] GET /api/v1/user-trees/{id} - Get custom tree - [ ] POST /api/v1/user-trees - Create new custom tree - [ ] PUT /api/v1/user-trees/{id} - Update custom tree - [ ] DELETE /api/v1/user-trees/{id} - Soft delete - [ ] PUT /api/v1/user-trees/{id}/share - Update sharing settings Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 14:** - Title: My Trees dashboard page - Labels: `feature`, `frontend`, `priority: medium` - Milestone: Phase 2.5 - Body: ``` Create "My Trees" page for managing personal trees: - [ ] List user's forked/custom trees - [ ] Show original tree reference (if forked) - [ ] Last used date, usage count - [ ] Quick actions: start session, edit, share, delete - [ ] Fork button on tree detail view - [ ] Notification when original tree updated (basic) Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 15:** - Title: Tree sharing via link - Labels: `feature`, `frontend`, `backend`, `priority: medium` - Milestone: Phase 2.5 - Body: ``` Allow sharing trees via link: - [ ] Generate unique share token for tree - [ ] GET /api/v1/shared/{share_token} - Access shared tree (no auth required) - [ ] Share modal with visibility options (private, link, team, public) - [ ] Copy link button - [ ] Option to allow/disallow forking Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 16:** - Title: Save session as custom tree - Labels: `feature`, `frontend`, `backend`, `priority: low` - Milestone: Phase 2.5 - Body: ``` After completing a session with custom steps, offer to save as tree: - [ ] POST /api/v1/sessions/{id}/save-as-tree endpoint - [ ] Prompt user after session completion (if custom steps were added) - [ ] Create user_tree from session path + custom steps - [ ] Allow user to name and edit before saving Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 17:** - Title: Admin - category management UI - Labels: `feature`, `frontend`, `priority: low` - Milestone: Phase 2.5 - Body: ``` Admin interface for managing step categories: - [ ] List categories with step counts - [ ] Create new category - [ ] Edit category name/description - [ ] Archive category (soft delete) - [ ] Reorder categories (display_order) Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` **Issue 18:** - Title: Rate/review modal after using a step - Labels: `feature`, `frontend`, `priority: low` - Milestone: Phase 2.5 - Body: ``` Prompt users to rate steps after using them: - [ ] After session completion, show steps used from library - [ ] Rating modal with 1-5 stars - [ ] Optional written review (max 500 chars) - [ ] "Was this helpful?" quick vote - [ ] Mark rating as "Verified Use" Reference: PHASE-2.5-PERSONAL-BRANCHING.md ``` --- ### Known Bugs (create as closed issues for history) **Issue 19:** - Title: [FIXED] DateTime timezone handling causing Internal Server Errors - Labels: `bug`, `backend` - State: CLOSED - Body: ``` **Problem:** Mixing timezone-aware and timezone-naive datetime objects caused errors in session completion. **Solution:** - Updated all SQLAlchemy models to use `DateTime(timezone=True)` - Changed all default datetime factories to `lambda: datetime.now(timezone.utc)` **Files affected:** All models with timestamp fields Fixed: January 28, 2026 ``` **Issue 20:** - Title: [FIXED] bcrypt/passlib version compatibility - Labels: `bug`, `backend` - State: CLOSED - Body: ``` **Problem:** Password hashing failed with newer bcrypt versions. **Solution:** Pin bcrypt version in requirements.txt: - bcrypt==4.0.1 - passlib[bcrypt]==1.7.4 Fixed: January 2026 ``` **Issue 21:** - Title: [FIXED] Email validation rejecting .local domains - Labels: `bug`, `backend` - State: CLOSED - Body: ``` **Problem:** Seed script failed with email validation error when using `.local` TLD. **Cause:** email-validator library correctly rejects `.local` as reserved per RFC 6761. **Solution:** Use standard domains like `example.com` for seed/test users. Fixed: January 29, 2026 ``` **Issue 22:** - Title: [FIXED] httpx not installed for seed scripts - Labels: `bug`, `backend` - State: CLOSED - Body: ``` **Problem:** Running seed_trees.py failed with ModuleNotFoundError for httpx. **Solution:** Install httpx before running seed scripts: ``` pip install httpx ``` Fixed: January 29, 2026 ``` --- ## Step 4: Verify After creating all issues: 1. Check that labels appear correctly 2. Check that milestones have correct issues assigned 3. Verify closed issues show in closed state --- ## Notes - Issues 4-18 are Phase 2.5 features from PHASE-2.5-PERSONAL-BRANCHING.md - Issues 19-22 are historical bugs documented in LESSONS-LEARNED.md (create as closed) - Long-term feature ideas are in BACKLOG.md (not GitHub Issues yet)