docs(detached-note): expand README with comprehensive feature documentation

Add detailed table of contents and expand feature sections to cover all GitCaddy capabilities including core repository management, collaboration tools, CI/CD, package registry, vault system, AI features, and landing pages. Reorganize content for better discoverability and add 600+ lines of documentation covering installation, configuration, usage examples, and API references. Also update vault fix note with related projects table.
2026-01-27 22:17:47 -05:00
parent ce7438cc9c
commit 1c0c1b8b74
2 changed files with 664 additions and 81 deletions
--- a/README.md
+++ b/README.md
@@ -2,6 +2,52 @@

 The AI-native Git platform. Self-hosted, fast, and designed for the age of AI-assisted development.

+## Table of Contents
+
+- [What is GitCaddy?](#what-is-gitcaddy)
+- [Key Features](#key-features)
+  - [V2 API - Modern, AI-Optimized Interface](#v2-api---modern-ai-optimized-interface)
+  - [AI Context APIs - Repository Intelligence](#ai-context-apis---repository-intelligence)
+  - [Runner Capability Discovery](#runner-capability-discovery)
+  - [Workflow Validation](#workflow-validation)
+  - [Action Compatibility Database](#action-compatibility-database)
+  - [Core Repository Management](#core-repository-management)
+  - [Collaboration Tools](#collaboration-tools)
+  - [CI/CD & Actions](#cicd--actions)
+  - [Package Registry](#package-registry)
+  - [Vault System (Pro/Enterprise)](#vault-system-proenterprise)
+  - [AI-Powered Features](#ai-powered-features)
+  - [Landing Pages & Public Releases](#landing-pages--public-releases)
+  - [App Update API (Electron/Squirrel Compatible)](#app-update-api-electronsquirrel-compatible)
+  - [Release Archive](#release-archive)
+  - [Security & Authentication](#security--authentication)
+  - [Organization Management](#organization-management)
+  - [Advanced UI Features](#advanced-ui-features)
+- [Installation](#installation)
+  - [From Binary](#from-binary)
+  - [From Source](#from-source)
+  - [Docker](#docker)
+- [Configuration](#configuration)
+  - [Database Setup](#database-setup)
+  - [AI Features Configuration](#ai-features-configuration)
+  - [Authentication Sources](#authentication-sources)
+  - [Email/SMTP Setup](#emailsmtp-setup)
+- [Usage](#usage)
+  - [Repository Operations](#repository-operations)
+  - [Project Management](#project-management)
+  - [CI/CD Workflows](#cicd-workflows)
+  - [Package Registry Usage](#package-registry-usage)
+  - [Vault Usage (Pro/Enterprise)](#vault-usage-proenterprise)
+  - [Landing Pages Configuration](#landing-pages-configuration)
+  - [AI Features Usage](#ai-features-usage)
+- [GitCaddy Runner](#gitcaddy-runner)
+- [API Documentation](#api-documentation)
+- [Internationalization](#internationalization)
+- [Building from Source](#building-from-source)
+- [Contributing](#contributing)
+- [License](#license)
+- [Acknowledgments](#acknowledgments)
+
 ## What is GitCaddy?

 GitCaddy transforms Git hosting into an AI-ready platform. While traditional Git servers treat AI tools as an afterthought, GitCaddy is built from the ground up with structured APIs, capability discovery, and intelligent context that AI assistants need to write correct code, generate valid CI/CD workflows, and understand your projects deeply.
@@ -13,8 +59,9 @@ GitCaddy transforms Git hosting into an AI-ready platform. While traditional Git
 - **Action Compatibility Database** - Curated compatibility matrix prevents workflow errors
 - **AI Context APIs** - Rich, structured repository and issue intelligence
 - **Workflow Validation** - Pre-flight checks for CI/CD workflows before commit
+- **Comprehensive Platform** - Full-featured Git hosting with collaboration, CI/CD, package registry, and enterprise features

-## Features
+## Key Features

 ### V2 API - Modern, AI-Optimized Interface

@@ -166,27 +213,66 @@ Built-in knowledge of GitHub Action compatibility:
 | `actions/upload-artifact` | v2, v3 | v4 not supported |
 | `actions/download-artifact` | v2, v3 | v4 not supported |

-### Release Archive
+### Core Repository Management

-Archive old releases without deleting them:
+- **Repository Operations:** Create, fork, mirror (push/pull), and migrate repositories from external services
+- **Branch & Tag Management:** Branch protection rules with status checks, approval requirements, and reorderable protection rules
+- **Code Browsing:** Commit history, blame view, diff visualization, and file tree navigation with Vue-based sidebar
+- **File Operations:** Web-based editor for uploading, editing, and deleting files
+- **Code Search:** Full-text search across repository files
+- **Release Management:** Create releases with automatic release notes generation and archive old releases
+- **Wiki Pages:** Markdown-based documentation with full editing capabilities
+- **Git LFS Support:** Large File Storage for binary assets

- Toggle archived status via UI or API
- Filter releases by archived state
- Archived releases hidden by default, toggle to show
- Preserves release history for compliance
+### Collaboration Tools

-```
-POST   /api/v1/repos/{owner}/{repo}/releases/{id}/archive
-DELETE /api/v1/repos/{owner}/{repo}/releases/{id}/archive
-GET    /api/v1/repos/{owner}/{repo}/releases?archived=false
-```
+- **Issues:** Labels, milestones, assignments, dependencies, and time tracking with real-time stopwatch
+- **Pull Requests:** Code review workflows with approval requirements and multiple merge strategies
+- **Project Boards:** Kanban-style boards with drag-and-drop organization using Sortable.js
+- **Comments & Reactions:** Mention autocomplete with Tribute.js, emoji reactions, and threaded discussions
+- **Notifications:** Comprehensive notification system for repository activity
+- **Activity Tracking:** Contribution graphs and activity heatmaps

-### Public Landing Pages & Releases for Private Repos
+### CI/CD & Actions

-Private repositories can expose a public landing page and/or public releases. Perfect for:
- Commercial software with private source but public downloads
- Open-core projects with public documentation
- Electron/desktop apps needing public update endpoints
+- **Workflow Execution:** Run GitHub Actions-compatible workflows with monitoring and logs
+- **Runner Management:** Track bandwidth, disk usage, and online/offline status
+- **Job Queue:** Monitor job status and view detailed execution logs
+- **Secrets & Variables:** Encrypted secrets management with CI/CD integration
+- **Status Checks:** Integrate workflow results into branch protection rules
+
+### Package Registry
+
+Multi-format package hosting with versioning and dependency management:
+
+- **Supported Formats:** Alpine, Arch, Cargo, Chef, Composer, Conda, Debian, Docker, Go, Helm, Maven, npm, NuGet, PyPI, RPM, RubyGems, Swift, Vagrant
+- **Access Controls:** Global and per-package permission management
+- **Version Management:** Full version history and dependency tracking
+
+### Vault System (Pro/Enterprise)
+
+Enterprise-grade encrypted secrets management:
+
+- **Encrypted Storage:** Version history for all secrets with rollback capabilities
+- **Audit Logging:** Comprehensive access logs with extended retention for Enterprise tier
+- **CI/CD Integration:** Generate tokens for workflow access to secrets
+- **Tiered Licensing:** Solo, Pro, Team, and Enterprise tiers with different feature sets
+
+### AI-Powered Features
+
+- **AI Code Review:** Automated code review suggestions on pull requests
+- **Issue Triage:** Automatic categorization and priority assignment
+- **Code Explanation:** Generate documentation and explain complex code
+- **Error Diagnosis:** AI learning patterns for debugging assistance
+
+### Landing Pages & Public Releases
+
+Customizable repository landing pages with optional public access for private repositories:
+
+- **Custom Domains:** Configure custom domains with SSL management
+- **Templates:** Choose from pre-built templates or create custom designs
+- **Branding:** Logos, icons, and theme customization
+- **Public Access:** Expose landing pages and releases for private repos (perfect for commercial software with public downloads)

 Configure in `.gitea/landing.yaml`:
 ```yaml
@@ -211,7 +297,7 @@ GET /api/v2/repos/{owner}/{repo}/releases/latest # Latest release

 ### App Update API (Electron/Squirrel Compatible)

-Purpose-built endpoint for desktop app auto-updates. Returns Squirrel-compatible JSON format.
+Purpose-built endpoint for desktop app auto-updates with Squirrel-compatible JSON format.

 **Endpoint:** `GET /api/v2/repos/{owner}/{repo}/releases/update`

@@ -256,6 +342,54 @@ autoUpdater.setFeedURL({
 autoUpdater.checkForUpdates()
 ```

+### Release Archive
+
+Archive old releases without deleting them:
+
+- Toggle archived status via UI or API
+- Filter releases by archived state
+- Archived releases hidden by default with toggle to show
+- Preserves release history for compliance
+
+```
+POST   /api/v1/repos/{owner}/{repo}/releases/{id}/archive
+DELETE /api/v1/repos/{owner}/{repo}/releases/{id}/archive
+GET    /api/v1/repos/{owner}/{repo}/releases?archived=false
+```
+
+### Security & Authentication
+
+- **Two-Factor Authentication:** TOTP-based 2FA with recovery codes
+- **WebAuthn/Hardware Keys:** Passkey support with credential management
+- **SSH/GPG Keys:** Key management with parsing and validation
+- **OAuth2/OpenID Connect:** Integration with external identity providers
+- **LDAP/SAML/SSPI:** Enterprise authentication support
+- **Signed Commits:** GPG signature verification
+- **Branch Protection:** Enforce status checks and approval requirements
+
+### Organization Management
+
+- **Team Management:** Granular permissions with role-based access control
+- **Member Roles:** Owner, member, and restricted user types
+- **Visibility Controls:** Public, private, and limited organization visibility
+- **Pinned Repositories:** Feature important projects on organization pages
+- **License Management:** Organization-level licensing for Pro/Enterprise features
+
+### Advanced UI Features
+
+- **Real-time Updates:** EventSource/SharedWorker for synchronized time tracking across tabs
+- **Interactive Tables:** Sortable columns and filterable data
+- **Math Rendering:** LaTeX equations with KaTeX
+- **Diagram Rendering:** Mermaid diagrams in isolated iframes
+- **Code Block Enhancements:** Copy-to-clipboard buttons and syntax highlighting
+- **Task Lists:** Interactive checkboxes in Markdown
+- **Terminal Playback:** Asciinema recording playback
+- **Accessibility:** ARIA attributes, keyboard navigation, and screen reader support
+- **Responsive Design:** Mobile-friendly interface with overflow menus
+- **Toast Notifications:** Non-intrusive status messages with Toastify.js
+- **Tooltips:** Context-sensitive help with Tippy.js
+- **Image Gallery:** Project showcase capabilities
+
 ## Installation

 ### From Binary
@@ -265,32 +399,98 @@ Download from [Releases](https://git.marketally.com/gitcaddy/gitcaddy-server/rel
 ```bash
 # Linux (amd64)
 curl -L -o gitcaddy-server https://git.marketally.com/gitcaddy/gitcaddy-server/releases/latest/download/gitcaddy-server-linux-amd64
-chmod +x gitcaddy
-./gitcaddy web
+chmod +x gitcaddy-server
+./gitcaddy-server web
+
+# macOS (arm64)
+curl -L -o gitcaddy-server https://git.marketally.com/gitcaddy/gitcaddy-server/releases/latest/download/gitcaddy-server-darwin-arm64
+chmod +x gitcaddy-server
+./gitcaddy-server web
+
+# Windows (amd64)
+# Download gitcaddy-server-windows-amd64.exe and run:
+gitcaddy-server.exe web
 ```

+The server will start on `http://localhost:3000` by default. On first run, you'll be redirected to the installation wizard.
+
 ### From Source

 ```bash
+# Clone the repository
 git clone https://git.marketally.com/gitcaddy/gitcaddy-server.git
 cd gitcaddy-server
+
+# Build with SQLite support
 TAGS="bindata sqlite sqlite_unlock_notify" make build
+
+# Run the server
 ./gitcaddy-server web
 ```

+**Requirements:**
+- Go 1.24+ (see `go.mod`)
+- Node.js 22.6+ (for frontend)
+- Make
+
 ### Docker

 ```bash
+# Run with Docker
 docker run -d \
  --name gitcaddy \
  -p 3000:3000 \
  -v ./data:/data \
  gitcaddy/gitea:latest
+
+# Or use Docker Compose
+version: "3"
+services:
+  gitcaddy:
+    image: gitcaddy/gitea:latest
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./data:/data
+    restart: unless-stopped
 ```

 ## Configuration

-GitCaddy uses the same configuration as Gitea. Key settings for AI features:
+### Database Setup
+
+GitCaddy supports multiple database backends. Configure during installation or in `app.ini`:
+
+**Supported Databases:**
+- SQLite (default, no additional setup required)
+- MySQL 5.7+ / MariaDB 10.2+
+- PostgreSQL 10+
+- MSSQL 2008+
+
+**Example MySQL Configuration:**
+```ini
+[database]
+DB_TYPE = mysql
+HOST = 127.0.0.1:3306
+NAME = gitcaddy
+USER = gitcaddy
+PASSWD = your_password
+```
+
+**Example PostgreSQL Configuration:**
+```ini
+[database]
+DB_TYPE = postgres
+HOST = 127.0.0.1:5432
+NAME = gitcaddy
+USER = gitcaddy
+PASSWD = your_password
+SSL_MODE = disable
+```
+
+### AI Features Configuration
+
+Enable and configure AI-powered features in `app.ini`:

 ```ini
 [server]
@@ -310,78 +510,400 @@ MAX_BATCH_SIZE = 100
 ENABLE_AI_CONTEXT = true
 ```

+### Authentication Sources
+
+Configure external authentication through the admin dashboard or `app.ini`:
+
+**OAuth2 Providers:**
+- GitHub, GitLab, Gitea, Bitbucket
+- Google, Microsoft, Discord, Twitter
+- Generic OAuth2 providers
+
+**LDAP/Active Directory:**
+```ini
+[auth.ldap]
+ENABLED = true
+HOST = ldap.example.com
+PORT = 389
+BIND_DN = cn=admin,dc=example,dc=com
+BIND_PASSWORD = password
+USER_BASE = ou=users,dc=example,dc=com
+USER_FILTER = (uid=%s)
+```
+
+**SAML 2.0:**
+Configure through the admin dashboard with your identity provider's metadata.
+
+### Email/SMTP Setup
+
+Configure email notifications in `app.ini`:
+
+```ini
+[mailer]
+ENABLED = true
+FROM = noreply@your-instance.com
+PROTOCOL = smtp
+SMTP_ADDR = smtp.gmail.com
+SMTP_PORT = 587
+USER = your-email@gmail.com
+PASSWD = your-app-password
+```
+
+## Usage
+
+### Repository Operations
+
+**Creating Repositories:**
+1. Click the "+" icon in the top navigation
+2. Select "New Repository"
+3. Choose a template (optional) or start from scratch
+4. Configure repository settings (visibility, README, .gitignore, license)
+
+**Forking:**
+1. Navigate to any repository
+2. Click "Fork" in the top-right corner
+3. Select the destination organization or user
+
+**Mirroring:**
+1. Create a new repository
+2. Enable "This repository is a mirror"
+3. Configure pull/push mirror settings
+4. Set synchronization schedule
+
+**Migration:**
+1. Click "+" → "New Migration"
+2. Select source platform (GitHub, GitLab, Gitea, Gogs)
+3. Provide repository URL and credentials
+4. Choose items to migrate (issues, PRs, releases, wiki)
+
+### Project Management
+
+**Issues:**
+- Create issues with labels, milestones, and assignments
+- Add dependencies between issues
+- Track time with the built-in stopwatch (synchronized across browser tabs)
+- Use mentions (@username) with autocomplete
+- Add reactions and threaded comments
+
+**Pull Requests:**
+- Create PRs from branches or forks
+- Request reviews from team members
+- View inline diff with syntax highlighting
+- Approve/request changes with review comments
+- Merge with strategies: merge commit, squash, or rebase
+
+**Project Boards:**
+- Create Kanban boards with custom columns
+- Drag and drop issues/PRs between columns
+- Filter by labels, milestones, or assignees
+- Track progress with visual indicators
+
+### CI/CD Workflows
+
+**Creating Workflows:**
+
+Create `.gitea/workflows/build.yml`:
+```yaml
+name: Build and Test
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install
+      - run: npm test
+```
+
+**Validating Before Commit:**
+```bash
+# Use the validation API
+curl -X POST https://your-instance.com/api/v2/repos/owner/repo/actions/workflows/validate \
+  -H "Authorization: token YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"content": "..."}'
+```
+
+**Monitoring Workflows:**
+- View workflow runs in the "Actions" tab
+- Check runner status and capabilities
+- View job logs in real-time
+- Re-run failed jobs
+
+### Package Registry Usage
+
+**Publishing npm Packages:**
+```bash
+# Configure registry
+npm config set registry https://your-instance.com/api/packages/owner/npm/
+
+# Authenticate
+npm login --registry=https://your-instance.com/api/packages/owner/npm/
+
+# Publish
+npm publish
+```
+
+**Publishing Docker Images:**
+```bash
+# Login
+docker login your-instance.com
+
+# Tag and push
+docker tag myimage:latest your-instance.com/owner/myimage:latest
+docker push your-instance.com/owner/myimage:latest
+```
+
+**Other Formats:**
+Refer to the package registry documentation for Maven, PyPI, Cargo, Helm, and other formats.
+
+### Vault Usage (Pro/Enterprise)
+
+**Creating Secrets:**
+1. Navigate to repository settings → Vault
+2. Click "New Secret"
+3. Enter key-value pairs
+4. Secrets are automatically encrypted and versioned
+
+**Using in Workflows:**
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy
+        env:
+          API_KEY: ${{ secrets.API_KEY }}
+        run: ./deploy.sh
+```
+
+**Viewing Audit Logs:**
+- Access audit logs in the Vault section
+- Filter by user, action, and date range
+- Export logs for compliance (Enterprise tier)
+
+**Rolling Back Secrets:**
+1. View secret history
+2. Select a previous version
+3. Click "Restore"
+
+### Landing Pages Configuration
+
+**Creating a Landing Page:**
+
+1. Create `.gitea/landing.yaml` in your repository:
+```yaml
+enabled: true
+public_landing: true  # For private repos with public landing page
+
+hero:
+  title: "My Amazing Project"
+  tagline: "The best solution for your needs"
+  cta_text: "Download Now"
+  cta_link: "/releases/latest"
+
+features:
+  - title: "Fast"
+    description: "Lightning-fast performance"
+    icon: "⚡"
+  - title: "Secure"
+    description: "Enterprise-grade security"
+    icon: "🔒"
+
+gallery:
+  - image: "screenshot1.png"
+    caption: "Main interface"
+  - image: "screenshot2.png"
+    caption: "Advanced features"
+
+advanced:
+  custom_domain: "myproject.com"
+  ssl_enabled: true
+  public_releases: true
+```
+
+2. Commit and push the file
+3. Access your landing page at `https://your-instance.com/owner/repo/pages`
+
+### AI Features Usage
+
+**AI Code Review:**
+1. Create a pull request
+2. Enable AI review in PR settings
+3. AI will analyze changes and provide suggestions
+4. Review and apply suggestions as needed
+
+**Issue Triage:**
+- AI automatically categorizes new issues
+- Suggests labels based on content
+- Estimates complexity
+- Recommends relevant files for investigation
+
+**Code Explanation:**
+1. Select code in the file viewer
+2. Click "Explain with AI"
+3. View generated documentation
+
+**Using AI Context APIs:**
+```bash
+# Get repository summary
+curl https://your-instance.com/api/v2/ai/repo/summary?owner=owner&repo=repo \
+  -H "Authorization: token YOUR_TOKEN"
+
+# Get issue context
+curl https://your-instance.com/api/v2/ai/issue/context?owner=owner&repo=repo&issue=123 \
+  -H "Authorization: token YOUR_TOKEN"
+
+# Get repository navigation
+curl https://your-instance.com/api/v2/ai/repo/navigation?owner=owner&repo=repo&depth=3 \
+  -H "Authorization: token YOUR_TOKEN"
+```
+
 ## GitCaddy Runner

-For full capability reporting, use the [GitCaddy act_runner](https://git.marketally.com/gitcaddy/act_runner):
+For full capability reporting and optimal workflow execution, use the [GitCaddy act_runner](https://git.marketally.com/gitcaddy/act_runner):

 ```bash
 # Download
 curl -L -o act_runner https://git.marketally.com/gitcaddy/act_runner/releases/latest/download/act_runner-linux-amd64
 chmod +x act_runner

-# Register
+# Register with your GitCaddy instance
 ./act_runner register \
  --instance https://your-instance.com \
-  --token YOUR_TOKEN \
-  --name my-runner
+  --token YOUR_REGISTRATION_TOKEN \
+  --name my-runner \
+  --labels ubuntu-latest,docker

-# Run (automatically detects and reports capabilities)
+# Run the runner daemon
 ./act_runner daemon
 ```

-The runner automatically detects:
- OS and architecture
- Docker/Podman availability
- Installed tools (Node.js, Go, Python, Java, .NET, Rust)
- Available shells
+**Automatic Capability Detection:**
+
+The runner automatically detects and reports:
+- Operating system and architecture
+- Docker/Podman availability and version
 - Docker Compose support
+- Installed tools and their versions:
+  - Node.js
+  - Go
+  - Python
+  - Java
+  - .NET
+  - Rust
+  - Ruby
+  - PHP
+- Available shells (bash, sh, pwsh, cmd)
+- Cache support
+- Service containers support
+
+**Viewing Runner Capabilities:**
+
+Access runner capabilities through the API or UI:
+```bash
+curl https://your-instance.com/api/v2/repos/owner/repo/actions/runners/capabilities \
+  -H "Authorization: token YOUR_TOKEN"
+```

 ## API Documentation

-Interactive API documentation available at:
- `/api/v2/docs` - Scalar API explorer
- `/api/v2/swagger.json` - OpenAPI specification
+GitCaddy provides comprehensive API documentation:

-## Architecture
+- **Interactive Explorer:** Visit `/api/v2/docs` on your instance for the Scalar API explorer
+- **OpenAPI Specification:** Download from `/api/v2/swagger.json`
+- **Legacy API:** V1 API documentation available at `/api/swagger`

-```
-                                    GitCaddy
-                                       |
-        +------------------------------+------------------------------+
-        |                              |                              |
-   V2 API Layer                  Actions Engine                  Web Interface
-        |                              |                              |
-   +----+----+                    +----+----+                    +----+----+
-   |         |                    |         |                    |         |
- Batch   Streaming            Runners   Workflows              Repos   Releases
- Files    (NDJSON)           Capability  Validation           (Archive)
-   |         |               Discovery      |
-   |         |                    |         |
-   +----+----+--------------------+---------+
-        |
-   AI Context APIs
-        |
-   +----+----+----+
-   |    |    |    |
-  Repo Issue Nav Summary
+**Authentication:**
+
+All API endpoints require authentication via token:
+```bash
+# Create a token in Settings → Applications → Generate New Token
+
+# Use in requests
+curl https://your-instance.com/api/v2/repos/owner/repo \
+  -H "Authorization: token YOUR_TOKEN"
 ```

-## Related Projects
-
-| Project | Description |
-|---------|-------------|
-| [gitcaddy/act_runner](https://git.marketally.com/gitcaddy/act_runner) | Runner with capability detection |
-| [gitcaddy/actions-proto-go](https://git.marketally.com/gitcaddy/actions-proto-go) | Protocol definitions |
-
-## Building
-
-Requirements:
- Go 1.24+ (see `go.mod`)
- Node.js 22.6+ (for frontend)
- Make
+**Common API Operations:**

 ```bash
-# Full build
+# List repositories
+GET /api/v2/user/repos
+
+# Get repository details
+GET /api/v2/repos/{owner}/{repo}
+
+# Create an issue
+POST /api/v2/repos/{owner}/{repo}/issues
+
+# List pull requests
+GET /api/v2/repos/{owner}/{repo}/pulls
+
+# Get runner capabilities
+GET /api/v2/repos/{owner}/{repo}/actions/runners/capabilities
+
+# Validate workflow
+POST /api/v2/repos/{owner}/{repo}/actions/workflows/validate
+
+# Batch file retrieval
+GET /api/v2/batch/files?paths=file1.go,file2.go&owner=owner&repo=repo
+
+# Stream files (NDJSON)
+POST /api/v2/stream/files
+```
+
+## Internationalization
+
+GitCaddy supports 12+ languages with full UI translation:
+
+**Supported Languages:**
+- German (de-DE)
+- English (en-US)
+- Irish (ga-IE)
+- Hindi (hi-IN)
+- Hungarian (hu-HU)
+- Indonesian (id-ID)
+- Icelandic (is-IS)
+- Italian (it-IT)
+- Dutch (nl-NL)
+- Polish (pl-PL)
+- Brazilian Portuguese (pt-BR)
+- Portuguese (pt-PT)
+
+**Changing Language:**
+1. Click your avatar in the top-right
+2. Select "Settings"
+3. Choose "Language" from the dropdown
+4. Save changes
+
+**Contributing Translations:**
+
+Translations are stored in JSON files at `options/locale/`. To contribute:
+1. Copy an existing locale file
+2. Translate all strings
+3. Submit a pull request
+
+## Building from Source
+
+**Requirements:**
+- Go 1.24+ (see `go.mod` for exact version)
+- Node.js 22.6+
+- Make
+- Git
+
+**Build Commands:**
+
+```bash
+# Clone the repository
+git clone https://git.marketally.com/gitcaddy/gitcaddy-server.git
+cd gitcaddy-server
+
+# Full build (backend + frontend)
 TAGS="bindata sqlite sqlite_unlock_notify" make build

 # Backend only
@@ -392,26 +914,87 @@ make frontend

 # Run tests
 make test
+
+# Run with live reload (development)
+make watch
+
+# Generate API documentation
+make generate-swagger
+```
+
+**Build Tags:**
+
+- `bindata` - Embed static assets into binary
+- `sqlite` - Enable SQLite support
+- `sqlite_unlock_notify` - Enable SQLite unlock notifications
+- `pam` - Enable PAM authentication
+- `gogit` - Use pure Go git implementation
+
+**Development Setup:**
+
+```bash
+# Install frontend dependencies
+npm install
+
+# Run frontend in development mode
+npm run dev
+
+# Run backend with hot reload
+make watch-backend
+
+# Run tests with coverage
+make test-coverage
 ```

 ## Contributing

-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Run tests: `make test`
-5. Submit a pull request
+We welcome contributions! Here's how to get started:
+
+1. **Fork the repository** on GitCaddy
+2. **Create a feature branch:** `git checkout -b feature/my-feature`
+3. **Make your changes** with clear commit messages
+4. **Run tests:** `make test`
+5. **Run linters:** `make lint`
+6. **Submit a pull request** with a clear description
+
+**Code Style:**
+- Go: Follow standard Go conventions (`gofmt`, `golint`)
+- TypeScript: Use ESLint configuration in the repository
+- Commit messages: Use conventional commits format
+
+**Testing:**
+- Write unit tests for new features
+- Ensure all tests pass before submitting
+- Add integration tests for API changes
+
+**Documentation:**
+- Update README.md for user-facing changes
+- Add API documentation for new endpoints
+- Include code comments for complex logic

 ## License

 MIT License - see [LICENSE](LICENSE) for details.

---
-
 ## Acknowledgments

 GitCaddy is a fork of [Gitea](https://gitea.io), the open-source self-hosted Git service. We thank the Gitea team and all contributors for building the foundation that makes GitCaddy possible.

- [Gitea Project](https://gitea.io)
- [Claude Code](https://claude.ai/code) - AI-assisted development by Anthropic
- [Gitea Contributors](https://github.com/go-gitea/gitea/graphs/contributors)
+- **[Gitea Project](https://gitea.io)** - The upstream project
+- **[Claude Code](https://claude.ai/code)** - AI-assisted development by Anthropic
+- **[Gitea Contributors](https://github.com/go-gitea/gitea/graphs/contributors)** - All the amazing contributors
+
+---
+
+**Related Projects:**
+
+| Project | Description |
+|---------|-------------|
+| [gitcaddy/act_runner](https://git.marketally.com/gitcaddy/act_runner) | Runner with automatic capability detection |
+| [gitcaddy/actions-proto-go](https://git.marketally.com/gitcaddy/actions-proto-go) | Protocol buffer definitions for Actions |
+
+**Support:**
+
+- **Documentation:** [https://docs.gitcaddy.com](https://docs.gitcaddy.com)
+- **Issues:** Report bugs and request features on our [issue tracker](https://git.marketally.com/gitcaddy/gitcaddy-server/issues)
+- **Community:** Join discussions in our repository