refactor: restructure into src/gitea_ci package

Split monolithic gitea-ci.py (3068 lines) into modular package:
- src/gitea_ci/config.py: configuration, constants
- src/gitea_ci/api.py: GiteaAPI class
- src/gitea_ci/formatters.py: output formatting
- src/gitea_ci/utils.py: utilities, validation
- src/gitea_ci/commands/: command implementations
- src/gitea_ci/cli.py: argument parser, dispatch

gitea-ci.py now thin wrapper (16 lines)

README.md

@@ -20,12 +20,16 @@ Command-line tool for monitoring and managing Gitea Actions workflows.
 ## 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
+# Clone the repository
+git clone https://github.com/user/gitea-ci.git
+cd gitea-ci
 
-# Or symlink
+# Option 1: Symlink the wrapper script
 ln -s "$(pwd)/gitea-ci.py" ~/.local/bin/gitea-ci
+
+# Option 2: Copy files (wrapper + src/ + style.py)
+cp -r gitea-ci.py style.py src/ ~/.local/bin/gitea-ci/
+ln -s ~/.local/bin/gitea-ci/gitea-ci.py ~/.local/bin/gitea-ci
 ```
 
 ### Dependencies
@@ -33,6 +37,35 @@ ln -s "$(pwd)/gitea-ci.py" ~/.local/bin/gitea-ci
 - Python 3.10+
 - No external packages required (uses stdlib only)
 
+### Package Structure
+
+```
+gitea-ci/
+├── gitea-ci.py              Thin wrapper (entry point)
+├── style.py                 Shared styling utilities
+└── src/gitea_ci/
+    ├── __init__.py          Package metadata, public API
+    ├── __main__.py          python -m gitea_ci support
+    ├── cli.py               Argument parser, command dispatch
+    ├── config.py            Configuration, constants
+    ├── api.py               Gitea API client
+    ├── formatters.py        Output formatting
+    ├── utils.py             Utilities, validation
+    └── commands/
+        ├── runs.py          list, status, logs, watch, delete
+        ├── workflows.py     trigger, rerun, cancel, validate
+        ├── artifacts.py     artifacts
+        ├── runners.py       runners, register-token
+        └── inspect.py       stats, pr, compare, infra, config, repo
+```
+
+### Running
+
+```sh
+./gitea-ci.py list                   # Direct execution
+python3 -m gitea_ci list             # Module execution (with PYTHONPATH=src)
+```
+
 ## Configuration
 
 ### Environment Variables
@@ -380,6 +413,45 @@ gitea-ci list -n 50 --json | jq -r '
 gitea-ci validate --strict && git commit -m "feat: add feature"
 ```
 
+## Development
+
+### Module Overview
+
+| Module | Lines | Purpose |
+|--------|-------|---------|
+| `config.py` | 67 | Config dataclass, constants |
+| `api.py` | 446 | GiteaAPI class, HTTP handling |
+| `formatters.py` | 332 | Output formatting, status display |
+| `utils.py` | 143 | Filtering, validation, notifications |
+| `cli.py` | 349 | Argument parser, dispatch |
+| `commands/runs.py` | 461 | Run listing, status, logs, watch |
+| `commands/workflows.py` | 296 | Trigger, rerun, cancel, validate |
+| `commands/artifacts.py` | 62 | Artifact operations |
+| `commands/runners.py` | 188 | Runner management |
+| `commands/inspect.py` | 842 | Stats, PR, compare, infra, config, repo |
+
+### Import Structure
+
+```python
+from gitea_ci import Config, GiteaAPI, __version__
+from gitea_ci.api import GiteaAPI
+from gitea_ci.commands import cmd_list, cmd_status
+```
+
+### Validation
+
+```sh
+# Syntax check all modules
+python3 -m py_compile src/gitea_ci/*.py src/gitea_ci/commands/*.py
+
+# Test import
+python3 -c "from src.gitea_ci import Config, GiteaAPI; print('OK')"
+
+# Test CLI
+./gitea-ci.py --help
+./gitea-ci.py config --show
+```
+
 ## License
 
 MIT