docs: add projects feature documentation and finalize integration
- Add comprehensive projects feature documentation (docs/projects-feature.md) - Add testing guide and checklist (test_projects_feature.js) - Update .gitignore to exclude database files - Include Task 13 completion summary Documentation covers: - Feature overview and key capabilities - Project creation (manual and smart suggestions) - Session assignment (automatic and manual) - Project management (edit, delete, restore) - Complete API reference - Smart suggestions explanation - Troubleshooting and FAQ Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
uroma
499
docs/projects-feature.md
Normal file
499
docs/projects-feature.md
Normal file
@@ -0,0 +1,499 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user