docs: add README.md with project overview, dev setup, and deployment guide

Covers tech stack, project structure, local development with nix develop
and air live reload, environment variables, testing, container build, and
deployment pointer to Talos repo manifests.

Closes leeworks-agents/gitea-mobile#148

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

README.md

@@ -0,0 +1,116 @@
+# Gitea Mobile
+
+A mobile-first Progressive Web App (PWA) for managing Gitea issues and pull requests across multiple repositories and organizations from an iPhone. Built with Go, HTMX, and hand-rolled CSS -- no JavaScript frameworks, no build step, no node_modules.
+
+## Tech Stack
+
+| Layer | Choice |
+|-------|--------|
+| Backend | Go + Gitea SDK (`code.gitea.io/sdk/gitea`) |
+| Frontend | HTMX + Go `html/template` + hand-rolled CSS |
+| Container | Multi-stage Dockerfile -> distroless (~15MB) |
+| Deployment | Kustomize manifests + FluxCD GitOps |
+
+## Project Structure
+
+```
+/
+├── cmd/server/main.go          # entrypoint
+├── internal/
+│   ├── config/config.go        # env-based configuration
+│   ├── gitea/client.go         # Gitea SDK wrapper / aggregation layer
+│   ├── handlers/               # HTTP handlers (issues, PRs, triage, settings)
+│   ├── auth/                   # cookie-based token auth
+│   ├── middleware/              # auth middleware, logging
+│   └── templates/              # Go html/template files (for HTMX)
+├── static/                     # CSS, JS (htmx.min.js), icons, manifest
+├── .gitea/workflows/build.yaml # CI pipeline (Gitea Actions)
+├── Dockerfile
+├── flake.nix                   # Nix dev shell with Go + air
+└── go.mod
+```
+
+## Local Development
+
+### Prerequisites
+
+- [Nix](https://nixos.org/download/) with flakes enabled, **or** Go 1.22+
+- A Gitea instance with an API token
+
+### Quick Start
+
+```bash
+# Enter the Nix dev shell (provides Go, gopls, air)
+nix develop
+
+# Set required environment variables
+export GITEA_URL=https://gitea.leeworks.dev
+export SESSION_SECRET=$(openssl rand -hex 32)
+
+# Optional: set a default API token
+export GITEA_TOKEN=your-gitea-api-token
+
+# Start the server with live reload
+air
+```
+
+If you are not using Nix, install Go 1.22+ and [air](https://github.com/air-verse/air) manually, then run the same commands above starting from the export lines.
+
+### Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `GITEA_URL` | Yes | -- | Base URL of the Gitea instance |
+| `SESSION_SECRET` | Yes | -- | HMAC key for signing session cookies (min 32 chars) |
+| `GITEA_TOKEN` | No | -- | Default API token (users can set their own via the settings page) |
+| `LISTEN_ADDR` | No | `:8080` | Server listen address |
+
+### Live Reload with Air
+
+The dev shell includes [air](https://github.com/air-verse/air) for automatic recompilation on file changes. Configuration is in `.air.toml`. Air watches `.go` and `.html` files under `cmd/`, `internal/`, and `static/` and rebuilds/restarts the server automatically.
+
+## Running Tests
+
+```bash
+# Run all tests
+go test ./...
+
+# Run tests with race detection
+go test -race ./...
+```
+
+## Building the Container
+
+```bash
+# Build the Docker image
+docker build -t gitea-mobile .
+
+# Run locally
+docker run -p 8080:8080 \
+  -e GITEA_URL=https://gitea.leeworks.dev \
+  -e SESSION_SECRET=$(openssl rand -hex 32) \
+  gitea-mobile
+```
+
+The Dockerfile uses a multi-stage build: Go binary compiled in an Alpine builder stage, then copied into a distroless image (~15MB final size).
+
+## Deployment
+
+Kubernetes manifests for this app live in the Talos cluster repo under `testing1/first-cluster/apps/gitea-mobile/`. FluxCD syncs from that repo and handles automated image updates via `ImagePolicy` annotations.
+
+Key deployment resources:
+- `deployment.yaml` -- Pod spec with health checks
+- `service.yaml` -- ClusterIP service on port 8080
+- `ingressroute.yaml` -- Traefik IngressRoute for `gitea-mobile.testing.leeworks.dev`
+- `kustomization.yaml` -- Kustomize overlay
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Make your changes and add tests
+4. Run `go test -race ./...` to verify
+5. Commit with a clear message referencing the issue number
+6. Push to your fork and open a pull request
+
+All PRs target the fork (`leeworks-agents/gitea-mobile`), not the upstream repo.

internal/gitea/client_test.go

@@ -377,6 +377,217 @@ func sortTriageQueue(queue []TriageItem) {
 	}
 }
 
+// --- Issue #117: Tests for GetTriageQueue aggregation ---
+
+func TestGetTriageQueue_Integration(t *testing.T) {
+	// Mock server that returns issues (some assigned, some not) and PRs.
+	requestCount := 0
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		requestCount++
+		switch {
+		case r.URL.Path == "/api/v1/user/orgs":
+			json.NewEncoder(w).Encode([]Org{{Name: "org1"}})
+
+		case strings.HasPrefix(r.URL.Path, "/api/v1/orgs/org1/repos"):
+			json.NewEncoder(w).Encode([]Repo{
+				{ID: 1, Name: "repo1", FullName: "org1/repo1", Owner: struct {
+					Login string `json:"login"`
+				}{Login: "org1"}},
+			})
+
+		case strings.HasSuffix(r.URL.Path, "/issues") && r.Method == "GET":
+			// Return mix of assigned and unassigned issues.
+			issues := []map[string]interface{}{
+				{
+					"id": 1, "number": 1, "title": "Unassigned bug",
+					"state": "open", "assignee": nil, "assignees": []interface{}{},
+					"labels":   []map[string]interface{}{{"id": 1, "name": "P1", "color": "ff0000"}},
+					"html_url": "http://example.com/org1/repo1/issues/1",
+				},
+				{
+					"id": 2, "number": 2, "title": "Assigned issue",
+					"state": "open",
+					"assignee":  map[string]string{"login": "dev1", "avatar_url": ""},
+					"assignees": []map[string]string{{"login": "dev1", "avatar_url": ""}},
+					"labels":    []interface{}{},
+					"html_url":  "http://example.com/org1/repo1/issues/2",
+				},
+				{
+					"id": 3, "number": 3, "title": "Unassigned low priority",
+					"state": "open", "assignee": nil, "assignees": []interface{}{},
+					"labels":   []map[string]interface{}{{"id": 2, "name": "P3", "color": "00ff00"}},
+					"html_url": "http://example.com/org1/repo1/issues/3",
+				},
+			}
+			json.NewEncoder(w).Encode(issues)
+
+		case strings.HasSuffix(r.URL.Path, "/pulls") && r.Method == "GET":
+			prs := []map[string]interface{}{
+				{
+					"id": 10, "number": 10, "title": "Open PR needs review",
+					"state": "open", "body": "please review",
+					"labels":   []map[string]interface{}{{"id": 3, "name": "P2", "color": "ffff00"}},
+					"html_url": "http://example.com/org1/repo1/pulls/10",
+					"head":     map[string]string{"label": "feature", "ref": "feature"},
+					"base":     map[string]string{"label": "master", "ref": "master"},
+				},
+			}
+			json.NewEncoder(w).Encode(prs)
+
+		case strings.HasSuffix(r.URL.Path, "/reviews"):
+			json.NewEncoder(w).Encode([]interface{}{})
+
+		default:
+			w.WriteHeader(http.StatusNotFound)
+			fmt.Fprintf(w, "unexpected request: %s %s", r.Method, r.URL.Path)
+		}
+	}))
+	defer server.Close()
+
+	c := NewClient(server.URL)
+	queue, err := c.GetTriageQueue(context.Background(), "test-token", []string{"org1"})
+	if err != nil {
+		t.Fatalf("GetTriageQueue: %v", err)
+	}
+
+	// Should include: 2 unassigned issues + 1 PR = 3 items.
+	// Assigned issue (#2) should be excluded.
+	if len(queue) != 3 {
+		t.Fatalf("expected 3 triage items, got %d", len(queue))
+	}
+
+	// Verify sorting: P1 > P2 > P3.
+	if queue[0].Title != "Unassigned bug" {
+		t.Errorf("queue[0] should be P1 'Unassigned bug', got %q", queue[0].Title)
+	}
+	if queue[1].Title != "Open PR needs review" {
+		t.Errorf("queue[1] should be P2 'Open PR needs review', got %q", queue[1].Title)
+	}
+	if queue[2].Title != "Unassigned low priority" {
+		t.Errorf("queue[2] should be P3 'Unassigned low priority', got %q", queue[2].Title)
+	}
+
+	// Verify types.
+	if queue[0].Type != "issue" {
+		t.Errorf("queue[0].Type = %q, want 'issue'", queue[0].Type)
+	}
+	if queue[1].Type != "pull" {
+		t.Errorf("queue[1].Type = %q, want 'pull'", queue[1].Type)
+	}
+}
+
+func TestGetTriageQueue_EmptyOrgs(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.URL.Path == "/api/v1/user/orgs":
+			json.NewEncoder(w).Encode([]Org{})
+		default:
+			json.NewEncoder(w).Encode([]interface{}{})
+		}
+	}))
+	defer server.Close()
+
+	c := NewClient(server.URL)
+	queue, err := c.GetTriageQueue(context.Background(), "test-token", []string{})
+	if err != nil {
+		t.Fatalf("GetTriageQueue with empty orgs: %v", err)
+	}
+	if len(queue) != 0 {
+		t.Errorf("expected empty queue for empty orgs, got %d items", len(queue))
+	}
+}
+
+func TestGetTriageQueue_AllAssigned(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.URL.Path == "/api/v1/user/orgs":
+			json.NewEncoder(w).Encode([]Org{{Name: "org1"}})
+		case strings.HasPrefix(r.URL.Path, "/api/v1/orgs/org1/repos"):
+			json.NewEncoder(w).Encode([]Repo{
+				{ID: 1, Name: "repo1", FullName: "org1/repo1", Owner: struct {
+					Login string `json:"login"`
+				}{Login: "org1"}},
+			})
+		case strings.HasSuffix(r.URL.Path, "/issues"):
+			// All issues are assigned.
+			json.NewEncoder(w).Encode([]map[string]interface{}{
+				{
+					"id": 1, "number": 1, "title": "Assigned issue",
+					"state": "open",
+					"assignee":  map[string]string{"login": "dev1"},
+					"assignees": []map[string]string{{"login": "dev1"}},
+					"labels":    []interface{}{},
+					"html_url":  "http://example.com/org1/repo1/issues/1",
+				},
+			})
+		case strings.HasSuffix(r.URL.Path, "/pulls"):
+			json.NewEncoder(w).Encode([]interface{}{}) // No PRs.
+		case strings.HasSuffix(r.URL.Path, "/reviews"):
+			json.NewEncoder(w).Encode([]interface{}{})
+		default:
+			json.NewEncoder(w).Encode([]interface{}{})
+		}
+	}))
+	defer server.Close()
+
+	c := NewClient(server.URL)
+	queue, err := c.GetTriageQueue(context.Background(), "test-token", []string{"org1"})
+	if err != nil {
+		t.Fatalf("GetTriageQueue: %v", err)
+	}
+	// Only PRs should appear (none here), all issues are assigned.
+	if len(queue) != 0 {
+		t.Errorf("expected 0 items (all assigned), got %d", len(queue))
+	}
+}
+
+func TestGetTriageQueue_LabelExtraction(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch {
+		case r.URL.Path == "/api/v1/user/orgs":
+			json.NewEncoder(w).Encode([]Org{{Name: "org1"}})
+		case strings.HasPrefix(r.URL.Path, "/api/v1/orgs/org1/repos"):
+			json.NewEncoder(w).Encode([]Repo{
+				{ID: 1, Name: "repo1", FullName: "org1/repo1", Owner: struct {
+					Login string `json:"login"`
+				}{Login: "org1"}},
+			})
+		case strings.HasSuffix(r.URL.Path, "/issues"):
+			json.NewEncoder(w).Encode([]map[string]interface{}{
+				{
+					"id": 1, "number": 1, "title": "Multi-label issue",
+					"state": "open", "assignee": nil, "assignees": []interface{}{},
+					"labels": []map[string]interface{}{
+						{"id": 1, "name": "bug", "color": "d73a4a"},
+						{"id": 2, "name": "P1", "color": "ff0000"},
+						{"id": 3, "name": "help wanted", "color": "0e8a16"},
+					},
+					"html_url": "http://example.com/org1/repo1/issues/1",
+				},
+			})
+		case strings.HasSuffix(r.URL.Path, "/pulls"):
+			json.NewEncoder(w).Encode([]interface{}{})
+		case strings.HasSuffix(r.URL.Path, "/reviews"):
+			json.NewEncoder(w).Encode([]interface{}{})
+		default:
+			json.NewEncoder(w).Encode([]interface{}{})
+		}
+	}))
+	defer server.Close()
+
+	c := NewClient(server.URL)
+	queue, err := c.GetTriageQueue(context.Background(), "test-token", []string{"org1"})
+	if err != nil {
+		t.Fatalf("GetTriageQueue: %v", err)
+	}
+	if len(queue) != 1 {
+		t.Fatalf("expected 1 item, got %d", len(queue))
+	}
+	if len(queue[0].Labels) != 3 {
+		t.Errorf("expected 3 labels, got %d: %v", len(queue[0].Labels), queue[0].Labels)
+	}
+}
+
 // --- Issue #122: Tests for ListOrgsAndRepos and CreateIssue ---
 
 func TestListOrgsAndRepos(t *testing.T) {