SuperCharged-Claude-Code-Upgrade/docs/projects-feature.md

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "success": true,
  "message": "Project moved to recycle bin"
}

Restore Project

POST /api/projects/:id/restore

Response:

{
  "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:

{
  "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:

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

Get Project Suggestions

GET /api/projects/suggestions

Response:

{
  "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