# Projects Feature Documentation

## Feature Overview

The Projects feature provides a powerful way to organize your Obsidian web sessions into logical groupings. Each session can belong to one project, allowing you to:

- Group related sessions together (e.g., by client, topic, or time period)
- Track sessions per project
- View project progress and statistics
- Maintain a clean, organized workspace with automatic session assignment

### Key Features

- **Automatic Session Assignment**: Sessions are automatically assigned to active projects when created
- **Smart Suggestions**: AI-powered suggestions for project names based on your workspace
- **Flexible Organization**: Move sessions between projects, create standalone sessions
- **Soft Delete**: Deleted projects go to the recycle bin for easy restoration
- **Project Insights**: View session counts and per-project statistics

---

## Creating Projects

### Via the Projects Page

1. Navigate to `/projects` in your browser
2. Click the **"New Project"** button in the top-right
3. In the dialog:
   - **Project Name**: Enter a descriptive name (required)
   - **Description**: Add an optional description
   - **Color**: Choose a color for visual identification
   - **Active Status**: Toggle whether the project should accept new sessions
4. Click **"Create Project"**

### Via Smart Suggestions

1. Navigate to `/projects`
2. Click the **"Suggestions"** button (✨)
3. Review AI-generated project name suggestions based on your workspace content
4. Click **"Use"** next to any suggestion to quickly create a project with that name

### Best Practices

- Use descriptive names that reflect the project's purpose
- Set projects to **inactive** when you're no longer actively working on them
- Use colors to visually distinguish between different types of projects
- Add descriptions to provide context for future reference

---

## Assigning Sessions to Projects

### Automatic Assignment

When you create a new session while an active project exists:

1. The session is **automatically assigned** to one of your active projects
2. Assignment follows these priority rules:
   - **User-selected project** (if you manually selected one)
   - **Most recently created active project**
   - **Oldest active project**
3. You'll see the project name displayed on the session card

### Manual Assignment via Context Menu

To move a session to a different project:

1. **Right-click** (or long-press on mobile) on any session card
2. Select **"Move to Project"** from the context menu
3. Choose the destination project from the dropdown
4. Click **"Move"** to confirm

The session will be removed from its current project and assigned to the new one.

### Creating Standalone Sessions

To create a session without assigning it to any project:

1. **Deactivate all projects** before creating the session
2. Or **move the session** out of its current project (using "Move to Project" → "No Project")

---

## Managing Projects

### Viewing Projects

Navigate to `/projects` to see:

- **All Projects**: Grid view of all your projects
- **Project Cards**: Each card shows:
  - Project name and color
  - Description
  - Number of sessions
  - Status badge (Active/Inactive)
  - Action buttons (Edit, Delete)
- **Recycle Bin**: View soft-deleted projects that can be restored

### Editing Projects

1. Navigate to `/projects`
2. Click the **"Edit"** button on the project card
3. Modify the project details:
   - Name
   - Description
   - Color
   - Active status
4. Click **"Save Changes"**

### Deleting Projects

1. Navigate to `/projects`
2. Click the **"Delete"** button on the project card
3. Confirm the deletion

**What happens when you delete a project:**
- The project is **soft-deleted** (moved to recycle bin)
- All sessions become **unassigned** (no project)
- The project can be **restored** from the recycle bin within 30 days
- After 30 days, soft-deleted projects are permanently removed

### Restoring Projects

1. Navigate to `/projects`
2. Click the **"Recycle Bin"** button
3. Find the project you want to restore
4. Click **"Restore"**
5. The project is restored with all its original settings

**Note**: Sessions are NOT automatically reassigned when restoring a project. You'll need to manually move sessions back if desired.

### Permanently Deleting Projects

To immediately and permanently delete a project:

1. Navigate to `/projects`
2. Click the **"Recycle Bin"** button
3. Find the project
4. Click **"Delete Permanently"**

**Warning**: This action cannot be undone!

---

## API Reference

### Projects API

#### List All Projects
```
GET /api/projects
```

**Response:**
```json
{
  "success": true,
  "projects": [
    {
      "id": "uuid",
      "name": "Project Name",
      "description": "Optional description",
      "color": "#3b82f6",
      "is_active": true,
      "created_at": "2025-01-19T10:00:00Z",
      "updated_at": "2025-01-19T10:00:00Z",
      "session_count": 5
    }
  ]
}
```

#### Create Project
```
POST /api/projects
Content-Type: application/json

{
  "name": "Project Name",
  "description": "Optional description",
  "color": "#3b82f6",
  "is_active": true
}
```

**Response:**
```json
{
  "success": true,
  "project": {
    "id": "uuid",
    "name": "Project Name",
    "description": "Optional description",
    "color": "#3b82f6",
    "is_active": true,
    "created_at": "2025-01-19T10:00:00Z",
    "updated_at": "2025-01-19T10:00:00Z",
    "session_count": 0
  }
}
```

#### Get Project Details
```
GET /api/projects/:id
```

**Response:**
```json
{
  "success": true,
  "project": {
    "id": "uuid",
    "name": "Project Name",
    "description": "Optional description",
    "color": "#3b82f6",
    "is_active": true,
    "created_at": "2025-01-19T10:00:00Z",
    "updated_at": "2025-01-19T10:00:00Z",
    "session_count": 5,
    "sessions": [
      {
        "id": "uuid",
        "name": "Session Name",
        "created_at": "2025-01-19T10:00:00Z"
      }
    ]
  }
}
```

#### Update Project
```
PATCH /api/projects/:id
Content-Type: application/json

{
  "name": "Updated Name",
  "description": "Updated description",
  "color": "#ef4444",
  "is_active": false
}
```

**Response:**
```json
{
  "success": true,
  "project": {
    "id": "uuid",
    "name": "Updated Name",
    "description": "Updated description",
    "color": "#ef4444",
    "is_active": false,
    "created_at": "2025-01-19T10:00:00Z",
    "updated_at": "2025-01-19T11:00:00Z",
    "session_count": 5
  }
}
```

#### Delete Project (Soft Delete)
```
DELETE /api/projects/:id
```

**Response:**
```json
{
  "success": true,
  "message": "Project moved to recycle bin"
}
```

#### Restore Project
```
POST /api/projects/:id/restore
```

**Response:**
```json
{
  "success": true,
  "project": {
    "id": "uuid",
    "name": "Project Name",
    "description": "Optional description",
    "color": "#3b82f6",
    "is_active": true,
    "created_at": "2025-01-19T10:00:00Z",
    "updated_at": "2025-01-19T11:00:00Z",
    "session_count": 0
  }
}
```

#### Permanently Delete Project
```
DELETE /api/projects/:id/permanent
```

**Response:**
```json
{
  "success": true,
  "message": "Project permanently deleted"
}
```

### Sessions API (Project-Related)

#### Move Session to Project
```
PATCH /api/sessions/:sessionId/project
Content-Type: application/json

{
  "project_id": "uuid"  // or null for "no project"
}
```

**Response:**
```json
{
  "success": true,
  "session": {
    "id": "uuid",
    "name": "Session Name",
    "project_id": "uuid",
    "project_name": "Project Name"
  }
}
```

#### Get Project Suggestions
```
GET /api/projects/suggestions
```

**Response:**
```json
{
  "success": true,
  "suggestions": [
    "Client Work",
    "Research",
    "Personal Notes"
  ]
}
```

---

## Smart Suggestions

The Smart Suggestions feature uses AI to analyze your workspace and suggest relevant project names. This helps you quickly create projects that match your workflow.

### How It Works

1. **Content Analysis**: The system scans your session names, content, and existing projects
2. **Pattern Recognition**: Identifies common themes, topics, and categories
3. **AI Generation**: Uses language models to generate relevant project name suggestions
4. **Smart Filtering**: Excludes names already in use and generic terms

### Using Suggestions

1. Navigate to `/projects`
2. Click the **"Suggestions"** button (✨ icon)
3. Browse the list of suggested project names
4. Click **"Use"** next to any suggestion to create a project with that name
5. The new project is created immediately with default settings

### Suggestion Types

- **Topic-Based**: E.g., "Research Notes", "Meeting Minutes"
- **Client-Based**: E.g., "Client: Acme Corp", "Project: Website Redesign"
- **Time-Based**: E.g., "Q1 Planning", "Monthly Review"
- **Workflow-Based**: E.g., "Drafts", "In Progress", "Completed"

### Customizing Suggestions

After creating a project from a suggestion:
1. Click **"Edit"** on the project card
2. Modify the name, description, color, or status
3. Click **"Save Changes"**

---

## Tips and Best Practices

### Organization Strategies

1. **By Client**: Create projects for each client or customer
2. **By Topic**: Group sessions by subject area (e.g., Research, Ideas, Tasks)
3. **By Time**: Use projects for time-based organization (e.g., Q1 2025, January)
4. **By Status**: Create workflow projects (Drafts, In Progress, Review, Done)

### Active vs. Inactive Projects

- **Keep active projects minimal**: Only mark projects as active when you're currently working on them
- **Use inactive for archival**: Mark completed projects as inactive to reduce clutter
- **Automatic assignment**: Only active projects are considered for automatic session assignment

### Color Coding

- **Red/Urgent**: High-priority or deadline-driven projects
- **Blue/Standard**: Regular ongoing work
- **Green/Completed**: Finished or reference projects
- **Yellow/Planning**: Projects in planning or ideation phase

### Session Management

- **Review assignments regularly**: Check that sessions are assigned to the correct projects
- **Use "No Project"**: Keep some sessions unassigned for flexibility
- **Bulk organization**: Use the context menu to quickly move multiple sessions

---

## Troubleshooting

### Sessions Not Assigning Automatically

**Problem**: New sessions aren't being assigned to projects

**Solutions**:
1. Check that you have at least one **active** project
2. Verify the project wasn't just created (there may be a brief delay)
3. Try manually assigning the session via the context menu

### Can't Find Deleted Project

**Problem**: Accidentally deleted a project and can't find it

**Solution**:
1. Navigate to `/projects`
2. Click **"Recycle Bin"**
3. Look for your project in the list
4. Click **"Restore"** to recover it

### Projects Not Showing on Landing Page

**Problem**: Projects aren't visible on the main page

**Solutions**:
1. Verify you have created at least one project
2. Check that projects aren't all soft-deleted
3. Refresh the page to clear the cache

### Suggestions Not Appearing

**Problem**: No suggestions appear when clicking the Suggestions button

**Solutions**:
1. Ensure you have existing sessions or content in your workspace
2. Wait a moment for the AI to analyze your workspace
3. Try creating projects manually instead

---

## FAQ

**Q: Can a session belong to multiple projects?**

A: No, each session can only belong to one project at a time. However, you can easily move sessions between projects using the context menu.

**Q: What happens to sessions when I delete a project?**

A: When you soft-delete a project, all its sessions become unassigned (no project). The sessions themselves are not deleted. When you restore the project, sessions remain unassigned and must be manually moved back if desired.

**Q: How long are deleted projects kept?**

A: Soft-deleted projects are kept in the recycle bin for 30 days before permanent deletion.

**Q: Can I permanently delete a project immediately?**

A: Yes, use the "Delete Permanently" button in the recycle bin. This action cannot be undone.

**Q: How many projects can I create?**

A: There's no hard limit on the number of projects you can create. Organize your workspace in whatever way works best for you.

**Q: Do inactive projects appear in automatic assignment?**

A: No, only active projects are considered when automatically assigning new sessions.

**Q: Can I change a project's color after creation?**

A: Yes, use the Edit button on the project card to modify the color at any time.

---

## Support

For issues, questions, or feature requests related to the Projects feature, please refer to the main documentation or contact support.

---

**Last Updated**: January 19, 2025
**Version**: 1.0.0