diff --git a/forgejo-instance-setup.md b/forgejo-instance-setup.md
new file mode 100644
index 0000000..14579ef
--- /dev/null
+++ b/forgejo-instance-setup.md
@@ -0,0 +1,218 @@
+# Forgejo Instance Setup Guide
+
+This document describes how to set up and work with a Forgejo instance from scratch.
+
+## 1. Create an Account
+
+### Via Web UI
+1. Go to your Forgejo instance URL (e.g., `https://vmd185580.tailf38284.ts.net`)
+2. Click **Sign Up** or **Register**
+3. Fill in:
+   - Username (e.g., `nazim`)
+   - Email address
+   - Password
+4. Complete CAPTCHA if required
+5. Check email for verification link (if email is enabled)
+
+### Via API (Admin-only)
+Regular users cannot create accounts via API. Contact an admin or use the web UI.
+
+## 2. Install `tea` CLI
+
+### macOS
+```bash
+brew install tea-org/tea/tea
+```
+
+### Linux (amd64)
+```bash
+# Download latest release
+curl -sL https://github.com/tea-org/tea/releases/latest/download/tea-linux-amd64.tar.gz | tar xz -C /tmp
+sudo mv /tmp/tea /usr/local/bin/
+sudo chmod +x /usr/local/bin/tea
+```
+
+### Linux (arm64)
+```bash
+curl -sL https://github.com/tea-org/tea/releases/latest/download/tea-linux-arm64.tar.gz | tar xz -C /tmp
+sudo mv /tmp/tea /usr/local/bin/
+sudo chmod +x /usr/local/bin/tea
+```
+
+### Verify Installation
+```bash
+tea --version
+# Expected: Version: [1m0.12.0[0m  golang: 1.25.7  go-sdk: v0.23.2
+```
+
+## 3. Configure Login
+
+### Get a Personal Access Token
+
+1. Log in to your Forgejo instance via web UI
+2. Go to **Settings** → **Application**
+3. Click **Add Access Token**
+4. Fill in:
+   - Token name: e.g., `tea-cli`
+   - Select scopes (minimum required):
+     - `read:user` — View user profile
+     - `write:repository` — Create and manage repos
+   - Click **Generate Token**
+5. Copy the generated token (you won't see it again!)
+
+### Save to `tea` Config
+
+The config file is at:
+- Linux/macOS: `~/.config/tea/config.yml`
+- Windows: `%AppData%\tea\config.yml`
+
+#### Example Config
+```yaml
+logins:
+- name: vmd185580
+  url: https://vmd185580.tailf38284.ts.net
+  token: <your-generated-token-here>
+  default: true
+  ssh_host: vmd185580.tailf38284.ts.net
+  ssh_key: ""
+  insecure: false
+  user: nazim
+  created: <unix-timestamp>
+preferences:
+  editor: false
+  flag_defaults:
+    remote: ""
+```
+
+#### Get Current Unix Timestamp
+```bash
+date +%s
+# Example output: 1776359800
+```
+
+### Test Connection
+```bash
+tea whoami
+# Expected output:
+# # nazim                                                                     
+# Follower Count: 0, Following Count: 0, Starred Repos: 0
+```
+
+## 4. Common Tasks
+
+### List Logins
+```bash
+tea login list
+```
+
+### Create a Repository
+```bash
+tea repos create --name my-repo \
+  --description "My project" \
+  --init \
+  --license mit
+```
+
+### Clone a Repository
+```bash
+tea clone nazim/my-repo
+# or
+git clone https://vmd185580.tailf38284.ts.net/nazim/my-repo.git
+```
+
+### List Repositories
+```bash
+tea repos list --mine
+```
+
+### Create an Issue
+```bash
+tea issues create --repo nazim/my-repo \
+  --title "Bug: Something is wrong" \
+  --body "Steps to reproduce..."
+```
+
+### Create a Pull Request
+```bash
+tea pr create --repo nazim/my-repo \
+  --title "Fix: Something was wrong" \
+  --body "This PR fixes the issue." \
+  --head feature-branch
+```
+
+## 5. SSH Access (Optional)
+
+If you want to use SSH instead of HTTPS:
+
+### Generate SSH Key
+```bash
+ssh-keygen -t ed25519 -C "nazim@openclaw.ai" -f ~/.ssh/vmd185580
+```
+
+### Add Public Key to Forgejo
+```bash
+cat ~/.ssh/vmd185580.pub
+# Copy output to Forgejo → Settings → SSH Keys
+```
+
+### Configure Git SSH Host
+```bash
+# Add to ~/.ssh/config
+Host vmd185580.tailf38284.ts.net
+  HostName vmd185580.tailf38284.ts.net
+  User git
+  Port 222
+  IdentityFile ~/.ssh/vmd185580
+```
+
+### Clone via SSH
+```bash
+git clone ssh://git@vmd185580.tailf38284.ts.net:222/nazim/my-repo.git
+```
+
+## 6. Troubleshooting
+
+### Token Scope Errors
+If you see `token does not have at least one of required scope(s)`, add more scopes to your token via Forgejo web UI → Settings → Application.
+
+### Connection Timeouts
+- Check if the instance is reachable: `ping vmd185580.tailf38284.ts.net`
+- Check TLS: `curl -v https://vmd185580.tailf38284.ts.net`
+- Check API: `curl https://vmd185580.tailf38284.ts.net/api/v1/version`
+
+### Wrong Login Used
+Set the default login in config or use `--login` flag:
+```bash
+tea whoami --login vmd185580
+```
+
+## 7. Scope Reference
+
+| Scope | Description |
+|-------|-------------|
+| `read:user` | View user profile and followers |
+| `write:repository` | Create, update, delete repositories |
+| `read:repository` | Read repository contents (public) |
+| `write:organization` | Manage organizations |
+| `admin:org` | Admin-level org access |
+
+## 8. Example Workflow
+
+```bash
+# 1. Create repo
+tea repos create --name krallen-skills \
+  --description "Forgejo instance skills" \
+  --init
+
+# 2. Clone locally
+git clone https://vmd185580.tailf38284.ts.net/nazim/krallen-skills.git
+
+# 3. Add content
+cd krallen-skills
+echo "# Krallen Skills" > README.md
+
+# 4. Push changes
+git add .
+git commit -m "Initial commit"
+git push origin main
+```