diff --git a/CHEATSHEET.md b/CHEATSHEET.md
new file mode 100644
index 0000000..af07185
--- /dev/null
+++ b/CHEATSHEET.md
@@ -0,0 +1,153 @@
+# gitea-ci Cheatsheet
+
+## Quick Reference
+
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│ SETUP
+├────────────────────────────────────────────────────────────────────────────┤
+│ export GITEA_URL="https://gitea.example.com"
+│ export GITEA_TOKEN="your-token"
+│ gitea-ci config --test                     Verify connectivity
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Common Tasks
+
+```
+┌──────────────────────────┬─────────────────────────────────────────────────┐
+│ Task                     │ Command
+├──────────────────────────┼─────────────────────────────────────────────────┤
+│ List runs                │ gitea-ci list owner/repo
+│ List failed only         │ gitea-ci list --failed
+│ Show run status          │ gitea-ci status owner/repo 123
+│ View logs                │ gitea-ci logs -R 123
+│ Watch live               │ gitea-ci watch owner/repo
+│ Trigger workflow         │ gitea-ci trigger -w deploy.yml
+│ Re-run failed            │ gitea-ci rerun -R 123 -f
+│ Cancel run               │ gitea-ci cancel -R 123
+│ Validate workflows       │ gitea-ci validate
+└──────────────────────────┴─────────────────────────────────────────────────┘
+```
+
+## Commands at a Glance
+
+```
+┌─────────────────┬────────┬──────────────────────────────────────────────────┐
+│ Command         │ Alias  │ Purpose
+├─────────────────┼────────┼──────────────────────────────────────────────────┤
+│ list            │ ls l   │ List workflow runs
+│ status          │ s      │ Show run details
+│ logs            │ log    │ View job logs
+│ watch           │ w      │ Live watch runs
+│ stats           │        │ Statistics with graphs
+│ trigger         │ t      │ Trigger workflow_dispatch
+│ rerun           │        │ Re-run workflow/jobs
+│ cancel          │        │ Cancel running workflow
+│ delete          │ rm     │ Delete workflow run
+│ artifacts       │ art    │ List/download artifacts
+│ pr              │        │ PR CI status
+│ compare         │ diff   │ Compare two runs
+│ workflows       │ wf     │ List workflow files
+│ validate        │ lint   │ Validate local workflows
+│ runners         │        │ Manage runners
+│ register-token  │ regtoken│ Get registration token
+│ config          │        │ Configure tool
+│ repo            │        │ Repository operations
+│ infra           │        │ Infrastructure status
+└─────────────────┴────────┴──────────────────────────────────────────────────┘
+```
+
+## Flags
+
+```
+┌────────────────────────┬────────────────────────────────────────────────────┐
+│ Flag                   │ Meaning
+├────────────────────────┼────────────────────────────────────────────────────┤
+│ -o, --owner            │ Repository owner
+│ -r, --repo             │ Repository name
+│ -R, --run              │ Run ID
+│ -j, --job              │ Job ID
+│ -n, --limit            │ Number of items
+│ -b, --branch           │ Branch filter
+│ -w, --workflow         │ Workflow file
+│ -i, --input            │ Workflow input (key=value)
+│ -f, --force            │ Skip confirmation
+│ --json                 │ JSON output
+│ --compact              │ Single-line output
+└────────────────────────┴────────────────────────────────────────────────────┘
+```
+
+## Status Symbols
+
+```
+✓  success       ●  running       ◌  queued
+✗  failure       ○  pending       ⊘  cancelled/skipped
+```
+
+## Patterns
+
+### After git push
+
+```sh
+git push && gitea-ci watch --notify
+```
+
+### Check last run status
+
+```sh
+gitea-ci list --compact | head -1
+```
+
+### Re-run latest failed
+
+```sh
+gitea-ci rerun -R "$(gitea-ci list --failed --compact | head -1 | awk '{print $1}')" -f
+```
+
+### Validate before commit
+
+```sh
+gitea-ci validate --strict && git commit -m "message"
+```
+
+### Export run data
+
+```sh
+gitea-ci list --json > runs.json
+gitea-ci status -R 123 --json | jq '.jobs[].name'
+```
+
+### Watch with timeout
+
+```sh
+gitea-ci watch -t 600 --notify  # 10 min timeout
+```
+
+### Get artifact
+
+```sh
+gitea-ci artifacts -R 123
+gitea-ci artifacts -d 456 -O build.zip
+```
+
+## Environment
+
+```
+GITEA_URL      Gitea instance URL
+GITEA_TOKEN    API authentication token
+NO_COLOR       Disable colors when set
+```
+
+## Config File
+
+`~/.config/gitea-ci/config.json`
+
+```json
+{
+  "url": "https://gitea.example.com",
+  "token": "...",
+  "default_owner": "myorg",
+  "default_repo": "myproject"
+}
+```
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b419336
--- /dev/null
+++ b/README.md
@@ -0,0 +1,385 @@
+# gitea-ci
+
+Command-line tool for monitoring and managing Gitea Actions workflows.
+
+## Features
+
+- List workflow runs across repositories
+- Show detailed job status with live updates
+- Stream build logs in real-time
+- Trigger workflows manually (workflow_dispatch)
+- Re-run failed jobs, cancel running workflows
+- List and download build artifacts
+- View PR check status
+- Compare workflow runs
+- Manage runners
+- Validate workflow files locally
+- Desktop notifications on completion
+- JSON output for scripting
+
+## Installation
+
+```sh
+# Clone or copy gitea-ci.py and style.py to your PATH
+cp gitea-ci.py style.py ~/.local/bin/
+chmod +x ~/.local/bin/gitea-ci.py
+
+# Or symlink
+ln -s "$(pwd)/gitea-ci.py" ~/.local/bin/gitea-ci
+```
+
+### Dependencies
+
+- Python 3.10+
+- No external packages required (uses stdlib only)
+
+## Configuration
+
+### Environment Variables
+
+```sh
+export GITEA_URL="https://gitea.example.com"
+export GITEA_TOKEN="your-api-token"
+```
+
+### Config File
+
+```sh
+gitea-ci config
+```
+
+Creates `~/.config/gitea-ci/config.json`:
+
+```json
+{
+  "url": "https://gitea.example.com",
+  "token": "your-api-token",
+  "default_owner": "myorg",
+  "default_repo": "myproject"
+}
+```
+
+### Token Permissions
+
+Required scopes for full functionality:
+
+```
+read:repository    List repos, runs, jobs
+write:repository   Trigger, cancel, delete runs
+read:user          User-level runner operations
+write:admin        Runner management (admin only)
+```
+
+Test your token:
+
+```sh
+gitea-ci config --test
+gitea-ci config token check
+```
+
+## Usage
+
+### Repository Specification
+
+Most commands accept repository in multiple formats:
+
+```sh
+gitea-ci list owner/repo           # Positional
+gitea-ci list -o owner -r repo     # Flags
+gitea-ci list                      # Uses defaults from config
+```
+
+### Commands
+
+#### list (ls, l)
+
+List recent workflow runs.
+
+```sh
+gitea-ci list                      # List runs (uses default repo)
+gitea-ci list owner/repo           # Specific repository
+gitea-ci list -n 20                # Show 20 runs
+gitea-ci list --failed             # Only failed runs
+gitea-ci list --success            # Only successful runs
+gitea-ci list --running            # Only running/waiting
+gitea-ci list -b main              # Filter by branch
+gitea-ci list -w ci.yml            # Filter by workflow
+gitea-ci list --json               # JSON output
+gitea-ci list --compact            # Single-line format
+```
+
+Without repository specified, discovers all repos with recent runs.
+
+#### status (s)
+
+Show detailed status of a workflow run.
+
+```sh
+gitea-ci status owner/repo 123     # Run #123
+gitea-ci status -R 123             # Run ID with default repo
+gitea-ci status owner/repo         # Latest run
+gitea-ci status --json             # JSON output
+```
+
+#### logs (log)
+
+View job logs.
+
+```sh
+gitea-ci logs owner/repo 123       # All logs for run #123
+gitea-ci logs -R 123               # Run ID with default repo
+gitea-ci logs -R 123 -j 456        # Specific job
+```
+
+#### watch (w)
+
+Watch workflow runs with live updates.
+
+```sh
+gitea-ci watch owner/repo          # Watch latest run
+gitea-ci watch -R 123              # Watch specific run
+gitea-ci watch -i 10               # 10 second refresh
+gitea-ci watch -t 300              # Timeout after 5 minutes
+gitea-ci watch --notify            # Desktop notification on completion
+gitea-ci watch --no-clear          # Don't clear screen
+```
+
+#### stats
+
+Show workflow statistics with visual graphs.
+
+```sh
+gitea-ci stats owner/repo          # Statistics for repo
+gitea-ci stats -n 100              # Analyze last 100 runs
+gitea-ci stats --detailed          # Per-job breakdown
+gitea-ci stats --json              # JSON output
+```
+
+#### trigger (t)
+
+Trigger a workflow manually (requires workflow_dispatch).
+
+```sh
+gitea-ci trigger owner/repo -w deploy.yml
+gitea-ci trigger -w build.yml -b develop
+gitea-ci trigger -w release.yml -i version=1.2.3 -i env=prod
+```
+
+#### rerun
+
+Re-run a workflow or specific jobs.
+
+```sh
+gitea-ci rerun -R 123              # Re-run entire workflow
+gitea-ci rerun -R 123 -f           # Re-run failed jobs only
+gitea-ci rerun -R 123 -j 456       # Re-run specific job
+```
+
+#### cancel
+
+Cancel a running workflow.
+
+```sh
+gitea-ci cancel -R 123
+```
+
+#### delete (rm)
+
+Delete a workflow run.
+
+```sh
+gitea-ci delete -R 123             # Prompts for confirmation
+gitea-ci delete -R 123 -f          # Force delete
+```
+
+#### artifacts (art)
+
+List and download build artifacts.
+
+```sh
+gitea-ci artifacts owner/repo      # List all artifacts
+gitea-ci artifacts -R 123          # Artifacts for run #123
+gitea-ci artifacts -d 456          # Download artifact #456
+gitea-ci artifacts -d 456 -O out.zip
+```
+
+#### pr
+
+Show CI status for a pull request.
+
+```sh
+gitea-ci pr owner/repo -p 42
+```
+
+#### compare (diff)
+
+Compare two workflow runs.
+
+```sh
+gitea-ci compare owner/repo 123 456   # Compare run 123 vs 456
+gitea-ci compare owner/repo 123       # Compare 123 vs previous
+gitea-ci compare owner/repo 123 --json
+```
+
+#### workflows (wf)
+
+List workflow files in a repository.
+
+```sh
+gitea-ci workflows owner/repo
+gitea-ci workflows -v              # Show triggers and details
+```
+
+#### validate (lint)
+
+Validate local workflow files.
+
+```sh
+gitea-ci validate                  # Current directory
+gitea-ci validate .gitea/workflows/
+gitea-ci validate ci.yml
+gitea-ci validate --check-runners  # Verify runs-on labels
+gitea-ci validate --strict         # Warnings as errors
+```
+
+#### runners
+
+Manage runners.
+
+```sh
+gitea-ci runners                   # List all runners
+gitea-ci runners list              # Same
+gitea-ci runners info 123          # Runner details
+gitea-ci runners jobs 123          # Jobs on runner
+gitea-ci runners delete 123        # Delete runner
+gitea-ci runners --json            # JSON output
+```
+
+#### register-token (regtoken)
+
+Get runner registration token.
+
+```sh
+gitea-ci register-token owner/repo # Repo-level token
+gitea-ci register-token --user     # User-level token
+```
+
+#### config
+
+Configure gitea-ci.
+
+```sh
+gitea-ci config                    # Interactive setup
+gitea-ci config --show             # Show current config
+gitea-ci config --test             # Test connectivity
+gitea-ci config token check        # Check token permissions
+gitea-ci config token set <token>  # Set token directly
+```
+
+#### repo
+
+Repository operations.
+
+```sh
+gitea-ci repo list                 # List accessible repos
+gitea-ci repo exists myrepo        # Check if repo exists
+gitea-ci repo check myrepo         # Detailed repo check
+gitea-ci repo create myrepo        # Create repository
+gitea-ci repo create myrepo -p     # Create private repo
+gitea-ci repo create myrepo -d "Description"
+```
+
+#### infra
+
+Show infrastructure status.
+
+```sh
+gitea-ci infra                     # Runner overview
+gitea-ci infra --jobs              # Show pending/running jobs
+```
+
+## Output Formats
+
+### Standard Output
+
+Color-coded with Unicode symbols:
+
+```
+✓  success
+✗  failure
+⊘  cancelled
+●  running
+○  pending/waiting
+◌  queued
+```
+
+### JSON Output
+
+Most commands support `--json` for scripting:
+
+```sh
+gitea-ci list --json | jq '.runs[].id'
+gitea-ci status -R 123 --json | jq '.jobs[].status'
+```
+
+### Compact Output
+
+Single-line format for scripting:
+
+```sh
+gitea-ci list --compact
+```
+
+## Environment
+
+| Variable      | Description                    | Default                    |
+|---------------|--------------------------------|----------------------------|
+| `GITEA_URL`   | Gitea instance URL             | `https://git.mymx.me`      |
+| `GITEA_TOKEN` | API token                      | (none)                     |
+| `NO_COLOR`    | Disable colored output         | (not set)                  |
+
+## Exit Codes
+
+| Code | Meaning                |
+|------|------------------------|
+| 0    | Success                |
+| 1    | General error          |
+| 2    | Authentication failure |
+
+## Examples
+
+### Watch a build after pushing
+
+```sh
+git push && gitea-ci watch --notify
+```
+
+### Check if CI passed
+
+```sh
+gitea-ci list --compact | head -1 | grep -q '✓' && echo "CI passed"
+```
+
+### Re-run failed jobs
+
+```sh
+gitea-ci rerun -R "$(gitea-ci list --compact | head -1 | awk '{print $1}')" -f
+```
+
+### Daily CI summary
+
+```sh
+gitea-ci list -n 50 --json | jq -r '
+  .runs | group_by(.conclusion) |
+  map({(.[0].conclusion // "running"): length}) | add'
+```
+
+### Validate before commit
+
+```sh
+gitea-ci validate --strict && git commit -m "feat: add feature"
+```
+
+## License
+
+MIT