docs: refresh README

README.md

@@ -1,150 +1,61 @@
 # Headquarter
 
-A self-hosted platform for managing projects, git repositories, and development tools with OAuth2 authentication.
+Headquarter is a self-hosted workspace for managing projects, Git repositories, development-tool instances, SSH keys, and user preferences. It has a FastAPI API, a React frontend, PostgreSQL and Redis, and Authentik OAuth2/session authentication. Built-in tool definitions include code-server and Jupyter.
 
-## Overview
+## Prerequisites
 
-Headquarter provides a centralized workspace for development teams to:
+- Docker and Docker Compose for the provided local and production Compose stacks.
-- Manage projects and their associated git repositories
+- Git for repository workflows.
-- Browse repository files and view git history
+- Python 3.11 or newer for manual API development.
-- Spawn development tools (VS Code Server, Jupyter Notebook, etc.)
+- Node.js and npm for manual frontend development.
-- Manage SSH keys and user preferences
+- An Authentik configuration for the authenticated deployment.
 
-## Features
+Production additionally requires an existing Traefik network and host Docker access for tool-instance management.
 
-### Project Management
+## Local Compose setup
-- Create and manage projects
-- View all projects in a dashboard
-- Click any project to open its workspace
 
-### Git Repository Management
+1. Create a local environment file from the template and replace placeholder credentials before using a shared or production-like environment:
-- Initialize bare repositories
-- Clone repositories (including mirror clones)
-- Smart URL parsing (converts browser URLs to git URLs)
-- View repository history and commit details
 
-### Repository Workspace
-- Browse files and directories
-- View file contents with syntax highlighting
-- Switch between branches
-- Quick file editing with automatic commits
-
-### Git History Visualization
-- View commit history with branch graph
-- See commit details, statistics, and diffs
-- Filter by branch
-
-### Authentication
-- OAuth2 via Authentik
-- Session-based authentication
-- User profile management
-
-### Tool Management
-- Built-in tool types (code-server, jupyter-notebook)
-- Create custom tool types with Docker Compose templates
-- Template validation
-
-### User Settings
-- Theme selection (system/light/dark)
-- Git identity configuration
-- Default editor preference
-
-### SSH Key Management
-- Generate Ed25519 key pairs
-- Copy public keys to clipboard
-- Delete keys
-
-## Quick Start
-
-### Prerequisites
-- Docker and Docker Compose
-- Git
-
-### Local Development
-
-1. **Clone the repository:**
-   ```bash
-   git clone <repository-url>
-   cd headquarter
-   ```
-
-2. **Set up environment:**
    ```bash
    cp .env.example .env
-   # Edit .env with your settings
    ```
 
-3. **Start services:**
+2. Start the local stack:
+
    ```bash
    docker compose up -d
    ```
 
-4. **Access the application:**
+The local Compose stack starts PostgreSQL, Redis, the API, and the web frontend. It publishes the web frontend at <http://localhost:3000>, the API at <http://localhost:8000>, and API documentation at <http://localhost:8000/docs>. PostgreSQL and Redis are also published on ports 5432 and 6379 respectively.
-   - Frontend: http://localhost:5173
-   - API: http://localhost:8000
-   - API Docs: http://localhost:8000/docs
 
-### Production Deployment
+> **Authentication limitation:** this command does not configure the `AUTHENTIK_*`, `API_DOMAIN`, or `WEB_DOMAIN` values required for a verified authenticated flow. Treat authenticated local use as unsupported until those values are supplied through a documented local configuration.
 
-See [Deployment Guide](docs/deployment/) for production setup with Traefik and Authentik.
+Useful operational commands:
 
-## Tech Stack
+```bash
-
+make up        # Start services
-### Backend
+make down      # Stop services
-- **FastAPI** - Python web framework
+make logs      # Follow Compose logs
-- **SQLAlchemy** - ORM with async PostgreSQL support
+make migrate   # Apply database migrations in the API container
-- **Pydantic** - Data validation
+make health    # Show Compose service status
-- **Alembic** - Database migrations
-- **python-jose** - JWT handling
-
-### Frontend
-- **React** - UI library
-- **TypeScript** - Type safety
-- **Vite** - Build tool
-- **React Router** - Client-side routing
-
-### Infrastructure
-- **Docker** - Containerization
-- **PostgreSQL** - Database
-- **Traefik** - Reverse proxy (production)
-- **Authentik** - Identity provider
-
-## Documentation
-
-- [User Guide](docs/features/) - Feature documentation
-- [API Reference](docs/api/) - API endpoints
-- [Architecture](docs/architecture/) - System design
-- [Deployment](docs/deployment/) - Setup guides
-- [Development](docs/development/) - Contributing
-
-## Project Structure
-
-```
-.
-├── apps/
-│   ├── api/              # FastAPI backend
-│   │   ├── src/
-│   │   │   ├── api/      # API routes
-│   │   │   ├── auth/     # Authentication
-│   │   │   ├── models/   # Database models
-│   │   │   └── utils/    # Utilities
-│   │   ├── tests/        # Test suite
-│   │   └── Dockerfile
-│   └── web/              # React frontend
-│       ├── src/
-│       │   ├── api/      # API clients
-│       │   ├── components/# UI components
-│       │   └── pages/    # Page components
-│       └── Dockerfile
-├── docs/                 # Documentation
-├── docker-compose.yml    # Development setup
-├── docker-compose.traefik.yml  # Production setup
-└── Makefile             # Common commands
 ```
 
-## Development
+## Production deployment
+
+The production Compose file is [`docker-compose.traefik.yml`](docker-compose.traefik.yml). It expects an existing external Traefik network (named `traefik` by default), configured domains, an Authentik client secret, and host paths for repositories, working copies, and tool instances.
+
+After preparing `.env` with production values, deploy with:
+
+```bash
+docker compose -f docker-compose.traefik.yml up -d
+```
+
+The production API container mounts `/var/run/docker.sock` so it can manage tool instances. Treat this as privileged host access and restrict it appropriately. The deployment guide and supporting material are under [`docs/deployment/`](docs/deployment/).
+
+## Manual development
+
+### API
 
-### Backend Development
 ```bash
 cd apps/api
 python -m venv .venv
@@ -153,43 +64,70 @@ pip install -e ".[dev]"
 uvicorn src.main:app --reload
 ```
 
-### Frontend Development
+### Web
+
 ```bash
 cd apps/web
 npm install
 npm run dev
 ```
 
-### Running Tests
+## Tests and quality checks
+
+The Make targets run commands in the Compose services:
+
 ```bash
-# Backend tests
 make test
-
+make test-unit
-# Frontend tests
+make test-integration
-make test-web
+make test-system
-
+make test-e2e
-# All quality gates
 make lint
 make typecheck
+make build
 ```
 
+The frontend test command is run directly from its package directory:
+
+```bash
+cd apps/web
+npm run test
+```
+
+`make lint` runs API Ruff and mypy checks plus frontend linting; `make typecheck` runs API mypy and frontend typechecking. Neither target runs frontend tests.
+
 ## Configuration
 
-Key environment variables:
+Copy [`.env.example`](.env.example) to `.env` and replace its placeholder values rather than committing credentials. Key settings include:
 
-| Variable | Description | Default |
+| Setting | Purpose |
-|----------|-------------|---------|
+| --- | --- |
-| `API_DOMAIN` | API domain | `localhost` |
+| `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB` | PostgreSQL connection settings |
-| `WEB_DOMAIN` | Web domain | `localhost` |
+| `REDIS_URL` | Redis connection URL |
-| `AUTHENTIK_DOMAIN` | Authentik domain | - |
+| `SESSION_SECRET`, `SESSION_TTL_HOURS` | Session signing and lifetime |
-| `AUTHENTIK_CLIENT_ID` | OAuth client ID | - |
+| `API_DOMAIN`, `WEB_DOMAIN` | Public API and web domains |
-| `AUTHENTIK_CLIENT_SECRET` | OAuth client secret | - |
+| `AUTHENTIK_DOMAIN`, `AUTHENTIK_CLIENT_ID`, `AUTHENTIK_CLIENT_SECRET` | Authentik OAuth configuration |
-| `DATABASE_URL` | PostgreSQL URL | - |
+| `AUTHENTIK_APPLICATION_SLUG` | Authentik application path component |
-| `JWT_SECRET` | JWT signing secret | - |
+| `VITE_API_BASE_URL`, `VITE_APP_URL` | Frontend build-time public URLs |
-| `REPO_BASE_PATH` | Repository storage path | `/data/repos` |
+| `REPO_BASE_PATH` | Repository storage path |
+| `TRAEFIK_NETWORK` | Existing Traefik network for the production Compose stack |
 
-See [Environment Variables](docs/deployment/environment.md) for complete list.
+The API reads `.env` settings and has development defaults, but defaults such as local credentials and session secrets are not suitable for production.
+
+## Repository layout
+
+```text
+.
+├── apps/
+│   ├── api/                  # FastAPI API, migrations, and tests
+│   └── web/                  # React/Vite frontend
+├── docs/                     # Architecture, API, feature, deployment, and development docs
+├── e2e/                      # Playwright end-to-end tests
+├── docker-compose.yml        # Local Compose stack
+├── docker-compose.traefik.yml # Traefik deployment stack
+└── Makefile                  # Compose, test, quality, and build commands
+```
 
 ## License
 
-[License information]
+No license file or declared license was found in this checkout.