From ba94b46f11c33da27a40ca44b3b346fa52bdfeeb Mon Sep 17 00:00:00 2001
From: wp <wp@stu.jiangnan.edu.cn>
Date: Tue, 28 Jul 2026 16:33:45 +0800
Subject: [PATCH] docs: add troubleshooting for proxy/TLS, timeouts, and
 Homebrew fallback

- Add timeout tips for pull/pdf/compile/output commands
- Document TLS/proxy issue with VPN apps (Shadowrocket, Clash, Surge)
- Add Homebrew failure workaround (npm install -g)
- Add connectivity verification tip (curl check)
---
 README.md | 22 +++++++++++++++++++++-
 SKILL.md  | 27 +++++++++++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 283876e..27816d0 100644
--- a/README.md
+++ b/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
+```
diff --git a/SKILL.md b/SKILL.md
index a13be29..0b59fc4 100644
--- a/SKILL.md
+++ b/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
+```