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

Documentation Overhaul - Tasks

Phase 1: README Rewrite

• Task 1.1: Rewrite README.md

  • Add project overview and description
  • List all features with brief descriptions
  • Add quick start section
  • Add tech stack section
  • Add links to docs/ directory
  • Keep testing strategy (or move to docs/testing.md)

• Task 1.2: Create docs/README.md

  • Documentation index
  • Link to all doc sections
  • Quick navigation

Phase 2: Create Documentation Structure

• Task 2.1: Create docs/ directory structure

  • mkdir docs/architecture
  • mkdir docs/features
  • mkdir docs/api
  • mkdir docs/deployment
  • mkdir docs/development
  • mkdir docs/templates

• Task 2.2: Create documentation templates

  • docs/templates/feature-doc.md
  • docs/templates/api-endpoint.md
  • docs/templates/architecture.md

Phase 3: Feature Documentation

• Task 3.1: Document Project Management

  • docs/features/projects.md
  • Creating/editing/deleting projects
  • Project list view
  • Project workspace

• Task 3.2: Document Git Repositories

  • docs/features/repositories.md
  • Creating repos (bare init, mirror clone)
  • Smart URL parsing
  • Repository management

• Task 3.3: Document Repository Workspace

  • docs/features/workspace.md
  • File browser
  • File viewer
  • Branch switching
  • Quick editing

• Task 3.4: Document Git History

  • docs/features/git-history.md
  • Commit history view
  • Branch graph
  • Commit details

• Task 3.5: Document Authentication

  • docs/features/auth.md
  • Authentik OAuth2 flow
  • Session management
  • User profile

• Task 3.6: Document User Settings

  • docs/features/settings.md
  • Theme selection
  • Git identity
  • Preferences

• Task 3.7: Document Tool Types

  • docs/features/tool-types.md
  • Built-in types
  • Custom type creation
  • Compose templates

• Task 3.8: Document SSH Keys

  • docs/features/ssh-keys.md
  • Key generation
  • Management

Phase 4: API Documentation

• Task 4.1: Document Auth API

  • docs/api/auth.md
  • All auth endpoints

• Task 4.2: Document Projects API

  • docs/api/projects.md
  • All project endpoints

• Task 4.3: Document Repositories API

  • docs/api/repositories.md
  • All repository endpoints
  • File operations
  • History endpoints

• Task 4.4: Document Users API

  • docs/api/users.md
  • User profile endpoints
  • Config endpoints

• Task 4.5: Document Tool Types API

  • docs/api/tool-types.md
  • CRUD endpoints

• Task 4.6: Document SSH Keys API

  • docs/api/ssh-keys.md
  • Key management endpoints

Phase 5: Architecture Documentation

• Task 5.1: Create backend architecture doc

  • docs/architecture/backend.md
  • Tech stack
  • Directory structure
  • Data flow
  • Auth flow

• Task 5.2: Create frontend architecture doc

  • docs/architecture/frontend.md
  • Tech stack
  • Directory structure
  • State management
  • Routing

• Task 5.3: Create database schema doc

  • docs/architecture/database.md
  • Entity relationship diagram
  • Table descriptions
  • Migration strategy

• Task 5.4: Create deployment architecture doc

  • docs/architecture/deployment.md
  • Docker architecture
  • Traefik routing
  • Service diagram

Phase 6: Deployment Guide

• Task 6.1: Create Docker setup guide

  • docs/deployment/docker.md
  • Local development setup
  • Docker compose configuration

• Task 6.2: Create Traefik guide

  • docs/deployment/traefik.md
  • Traefik configuration
  • Routing rules
  • TLS setup

• Task 6.3: Create Authentik guide

  • docs/deployment/authentik.md
  • Provider setup
  • Application configuration
  • OAuth2 settings

• Task 6.4: Create environment variables guide

  • docs/deployment/environment.md
  • All env vars explained
  • Required vs optional
  • Default values

Phase 7: Development Guide

• Task 7.1: Create setup guide

  • docs/development/setup.md
  • Prerequisites
  • Installation steps
  • Running locally

• Task 7.2: Move testing strategy

  • Move from README.md to docs/development/testing.md
  • Update references

• Task 7.3: Create contributing guide

  • docs/development/contributing.md
  • Code style
  • PR process
  • Documentation requirements

• Task 7.4: Create quality gates doc

  • docs/development/quality-gates.md
  • Linting rules
  • Type checking
  • Testing requirements

Phase 8: Finalization

• Task 8.1: Review all docs

  • Check for completeness
  • Check for accuracy
  • Fix broken links

• Task 8.2: Create CHANGELOG.md

  • List all features implemented
  • Link to OpenSpec changes

• Task 8.3: Commit all documentation

  • Single commit for docs
  • Conventional commit message