# 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)
