# Transmission Manager — AGENTS.md

## Project Overview
A lightweight single-binary Go web app that provides a beautiful dark-mode SPA for managing/viewing torrents in a Transmission RPC client.

## Architecture
- **Backend**: Go (stdlib net/http only, no external dependencies). Serves on port 8080.
  - `GET /` → serves embedded static files (index.html, app.js, styles.css)
  - `GET /api/torrents` → proxies to Transmission RPC, returns clean JSON
  - `GET /api/stats` → global session stats
- **Frontend**: Vanilla HTML + CSS + JS. No frameworks. Single page. Dark mode only.

## Transmission RPC Details
- RPC URL: `http://192.168.20.22:3210/transmission/rpc`
- No auth required (open on LAN)
- The RPC requires a session-ID handshake:
  1. POST to the RPC URL
  2. If response is 409, read the `X-Transmission-Session-Id` header from the response
  3. Re-send the request with that header
  4. Cache the session-ID for future requests
- For torrent list, request these fields:
  ```
  id, name, totalSize, downloadedEver, uploadedEver, uploadRatio,
  percentDone, status, eta, error, errorString, doneDate, isFinished,
  rateDownload, rateUpload, peersConnected, peersGettingFromUs, peersSendingToUs,
  peers (array of {address, clientName, progress, isDownloadingFrom, isUploadingTo, rateToClient, rateToPeer})
  ```
- "Peers with 100%" = count of peers in the `peers` array where `progress === 1.0`
- "Finished date" = `doneDate` (Unix timestamp, 0 means not finished)

## Design Requirements (CRITICAL)
- **Dark mode only** — deep dark background (#0a0a0f or similar)
- **Modern, stylish, clean** — think Linear, Vercel, Raycast aesthetic
- **Accent color**: Use a vibrant accent (cyan/teal #00d4ff or purple #8b5cf6)
- **Typography**: System font stack, -apple-system, Inter-like
- **Torrent cards or rows** with:
  - Name (truncated with ellipsis if long)
  - Size (human-readable: GB, MB, etc.)
  - Progress bar (animated, smooth)
  - Percentage done
  - Ratio (uploadRatio)
  - Downloaded / Uploaded amounts
  - Download/Upload speeds
  - ETA (when downloading)
  - Status badge (downloading, seeding, paused, finished, error)
  - Finish date (formatted nicely, e.g. "Jul 8, 2026")
  - Peer count with 100% (e.g. "3/7 peers at 100%")
- **Auto-refresh** every 3 seconds
- **Header** with app title and global stats (total download/upload speed, torrent count)
- **Responsive** — works on mobile and desktop
- Use CSS variables for theming
- Smooth transitions and micro-animations
- Cards with subtle borders and hover effects

## Code Structure
```
main.go          — Go backend (HTTP server, Transmission RPC proxy, static file serving via embed)
web/
  index.html     — SPA shell
  app.js         — Frontend logic (fetch API, render, auto-refresh)
  styles.css    — All styling
Dockerfile       — Multi-stage: golang:1.24-alpine (build) → alpine:latest (runtime)
go.mod           — module transmission-manager, go 1.24
```

## Go Implementation Notes
- Use `embed` package to embed web/ directory into the binary
- Transmission RPC communication via net/http client
- Implement session-ID handshake with retry on 409
- Use sync.Mutex to protect session-ID cache
- Format numbers nicely (human-readable sizes) in the frontend, not backend
- CORS not needed (same origin)
- The Go server should be minimal and fast

## Dockerfile
```dockerfile
FROM golang:1.24-alpine AS builder
WORKDIR /app
COPY go.mod ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o transmission-manager .

FROM alpine:latest
RUN apk add --no-cache ca-certificates
WORKDIR /app
COPY --from=builder /app/transmission-manager .
EXPOSE 8080
CMD ["./transmission-manager"]
```

## Do NOT
- Do not use any Go web framework (gin, fiber, etc.) — stdlib only
- Do not use any JS framework (React, Vue, etc.) — vanilla only
- Do not add authentication
- Do not add CI/CD or GitHub Actions
- Do not create any GitHub repository
- Do not add vendored dependencies
- Do not add tests unless necessary — keep it simple