docs: add troubleshooting for proxy/TLS, timeouts, and Homebrew fallback

README.md

@@ -48,10 +48,12 @@ olcli list                             # See all projects
 olcli pull "My Paper"                  # Download project
 cd My_Paper && vim main.tex            # Edit locally
 olcli sync                             # Push changes
-olcli pdf                              # Download PDF
+olcli pdf --timeout 120000             # Download PDF (large papers need higher timeout)
 olcli output bbl                       # Get .bbl for arXiv
 ```
 
+> 💡 **Timeouts:** Commands like `pull`, `pdf`, `compile`, and `output` default to a 10-second timeout. For large projects, increase it with `--timeout 120000` (2 minutes) or higher.
+
 ## arXiv Submission Workflow
 
 Complete workflow for submitting to arXiv:
@@ -81,3 +83,21 @@ zip arxiv-submission.zip *.tex main.bbl figures/*
 ## License
 
 MIT
+
+## Troubleshooting
+
+### TLS / proxy issues
+
+If you see `Client network socket disconnected before secure TLS connection was established`, it's likely because you're behind a VPN or proxy app (Shadowrocket, Clash, Surge, etc.). Node.js does **not** automatically use system proxy settings. Add `overleaf.com` to your proxy's **DIRECT** routing rule.
+
+Verify connectivity first:
+```bash
+curl -sI https://www.overleaf.com/project
+```
+
+### Homebrew install fails
+
+If `brew install olcli` fails with npm cache errors, install via npm instead:
+```bash
+npm install -g @aloth/olcli
+```

SKILL.md

@@ -149,3 +149,30 @@ zip arxiv.zip *.tex main.bbl figures/*.pdf
 - **Force overwrite**: Use `olcli pull --force` to overwrite local changes
 - **Project ID**: You can use project ID instead of name (24-char hex from URL)
 - **Debug auth**: Run `olcli check` to see where credentials are loaded from
+- **Timeouts**: For large projects or slow connections, increase the timeout: `olcli pdf --timeout 120000` (default 10s). This applies to `pull`, `pdf`, `compile`, and `output`.
+
+## Troubleshooting
+
+### "Client network socket disconnected before secure TLS connection was established"
+
+This often happens when running behind a VPN or proxy app (Shadowrocket, Clash, Surge, etc.). Node.js's `https` module does **not** automatically use the system proxy settings.
+
+**Fix:** Add `overleaf.com` to the **DIRECT** routing rule in your proxy app.
+
+To verify connectivity before debugging the tool itself:
+```bash
+curl -sI https://www.overleaf.com/project
+```
+
+### Homebrew installation fails with npm cache errors
+
+If `brew install olcli` fails due to corrupted npm caches, use npm directly:
+```bash
+npm install -g @aloth/olcli
+```
+
+### Verify the CLI is correctly installed
+```bash
+olcli --version
+olcli check
+```