headquarter/openspec/changes/archive/2026-05-19-documentation-overhaul/specs/spec.md

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

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

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