# Documentation Overhaul Specification

## Requirements

### Functional Requirements

1. **README Rewrite**: Comprehensive project overview with features, quick start, and links
2. **Feature Documentation**: Every feature has a user guide in docs/features/
3. **API Documentation**: All endpoints documented with examples
4. **Architecture Docs**: Backend, frontend, and deployment architecture explained
5. **Deployment Guide**: Step-by-step Docker/Traefik/Authentik setup
6. **Development Guide**: Setup, testing, contributing guidelines
7. **Templates**: Reusable templates for future documentation
8. **Auto-Documentation**: Process ensuring new features get documented

### Non-Functional Requirements

1. **Discoverability**: Users can find docs easily from README
2. **Completeness**: All current features documented
3. **Accuracy**: Docs match current implementation
4. **Maintainability**: Templates and processes keep docs up-to-date
5. **Accessibility**: Markdown format, clear structure

## Documentation Inventory

### Current Features to Document

1. **Project Management**
   - Create/edit/delete projects
   - Project list view
   - Project workspace (default view)

2. **Git Repositories**
   - Create repositories (bare init, mirror clone)
   - Smart URL parsing
   - Repository list
   - Repository deletion

3. **Repository Workspace**
   - File browser (tree view)
   - File viewer (syntax highlighting)
   - Branch switching
   - Repository switching
   - Quick file editing

4. **Git History**
   - Commit history visualization
   - Branch graph
   - Commit details (diff, stats)
   - Branch filtering

5. **Authentication**
   - Authentik OAuth2 flow
   - Session-based auth
   - User profile
   - Logout

6. **User Settings**
   - Theme selection
   - Git identity
   - Default editor

7. **Tool Types**
   - Built-in types (code-server, jupyter)
   - Custom type creation
   - Compose template validation

8. **SSH Keys**
   - Generate key pairs
   - List/delete keys
   - Copy public key

## API Endpoints to Document

### Auth
- GET /auth/login
- GET /auth/callback
- GET /auth/me
- POST /auth/logout

### Projects
- GET /projects
- POST /projects
- GET /projects/{id}
- PUT /projects/{id}
- DELETE /projects/{id}

### Repositories
- GET /projects/{id}/repositories
- POST /projects/{id}/repositories
- DELETE /projects/{id}/repositories/{id}
- GET /projects/{id}/repositories/{id}/files
- GET /projects/{id}/repositories/{id}/files/content
- POST /projects/{id}/repositories/{id}/files/content
- GET /projects/{id}/repositories/{id}/branches
- GET /projects/{id}/repositories/{id}/history
- GET /projects/{id}/repositories/{id}/commits/{hash}

### Users
- GET /users/me
- PUT /users/me
- POST /users/me/avatar
- GET /users/me/config
- PATCH /users/me/config

### Tool Types
- GET /tool-types
- POST /tool-types
- GET /tool-types/{id}
- PUT /tool-types/{id}
- DELETE /tool-types/{id}

### SSH Keys
- GET /ssh-keys
- POST /ssh-keys
- DELETE /ssh-keys/{id}

## Documentation Templates

### Feature Doc Template
```markdown
# [Feature Name]

## Overview
[1-2 sentence description]

## How to Use
[Step-by-step guide]

## Screenshots
[If applicable]

## API Reference
[Links to API docs]

## Configuration
[Relevant env vars/settings]

## Related
[Links to related features]
```

### API Doc Template
```markdown
## [METHOD] [PATH]

**Auth:** [Required/Optional]

**Description:** [What it does]

### Request
[Params/body schema]

### Response
[Success/error schemas]

### Example
[Code example]
```

## Implementation Checklist

For every new feature:
- [ ] Create feature doc in docs/features/
- [ ] Document API endpoints in docs/api/
- [ ] Update README.md features list
- [ ] Update architecture docs if needed
- [ ] Add to CHANGELOG.md

## Success Criteria

1. README provides clear project overview
2. All 8 feature areas have user guides
3. All API endpoints have documentation
4. New developer can set up project in < 15 minutes
5. Deployment guide enables setup without asking questions
6. Templates exist for future documentation
7. CONTRIBUTING.md explains documentation requirements