diff --git a/README.md b/README.md
new file mode 100644
index 0000000..33d8d58
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# gitea-connector
+
+A Claude Code plugin for connecting to Seth's Gitea instance at `git.sethpc.xyz`. Sets up your credentials, installs a CLI, and teaches Claude Code your commit conventions — so you can focus on writing code instead of remembering how to push it.
+
+## Install
+
+Add this plugin to your Claude Code setup:
+
+```bash
+claude plugin add /path/to/gitea-connector
+```
+
+Or clone it:
+
+```bash
+git clone https://git.sethpc.xyz/Seth/gitea-connector.git
+claude plugin add ./gitea-connector
+```
+
+## Setup
+
+Run `/gitea-setup` in Claude Code. It'll walk you through everything:
+
+1. Checks you have `curl`, `jq`, and `git` (the holy trinity)
+2. Guides you through generating an API token on git.sethpc.xyz
+3. Stores your credentials securely in `~/.config/gitea/`
+4. Installs the `gitea` CLI to `~/bin/`
+5. Validates your connection
+
+The whole thing takes about 2 minutes. Less if you type fast.
+
+## CLI Usage
+
+After setup, you have the `gitea` command:
+
+```bash
+gitea create my-project --private --description "Top secret stuff"
+gitea remote my-project    # wire up git origin
+gitea push                 # push current branch
+gitea list                 # see your repos
+gitea delete old-project   # delete (with confirmation)
+```
+
+## Commit Conventions
+
+The plugin teaches Claude Code these conventions (override in your project's CLAUDE.md):
+
+- **Conventional commits:** `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- **Commit immediately** — don't hoard changes
+- **Always push** — unpushed commits are just elaborate local notes
+- **No squashing** — history is sacred
+- **One concern per commit** — no bundling unrelated changes
+
+## Push Reminder Hook (opt-in)
+
+Want a nudge after every commit? Edit `hooks/hooks.json` in the plugin directory:
+
+```json
+{
+  "description": "Gitea connector hooks — push reminder after commits",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/push-reminder.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Config Files
+
+All stored in `~/.config/gitea/`:
+
+| File | Purpose |
+|------|---------|
+| `token` | Your Gitea API token |
+| `username` | Your Gitea username |
+| `host` | (Optional) Host override, defaults to `git.sethpc.xyz` |
+
+## Requirements
+
+- `curl`, `jq`, `git`
+- A Gitea account on `git.sethpc.xyz` (talk to Seth)
+- Claude Code