docs: PyPI badge, quick-links nav, roadmap; harden release workflow

.github/workflows/release.yml

@@ -1,10 +1,12 @@
 name: release
 
-# Publishes to PyPI when a GitHub Release is published.
-# One-time setup on pypi.org → Publishing → add a Trusted Publisher:
-#   PyPI project: deepcloak · owner: Mrbaeksang · repo: deepcloak
-#   workflow: release.yml · environment: pypi
-# No API token needed (OIDC trusted publishing).
+# Publishes to PyPI when a GitHub Release is published. No API token needed (OIDC).
+# One-time setup:
+#   1. pypi.org → Publishing → add a Trusted Publisher:
+#      PyPI project: deepcloak · owner: Mrbaeksang · repo: deepcloak
+#      workflow: release.yml · environment: pypi
+#   2. Repo → Settings → Secrets and variables → Actions → Variables:
+#      add PUBLISH_TO_PYPI = true   (until then this job stays skipped)
 
 on:
   release:
@@ -16,6 +18,10 @@ permissions:
 jobs:
   pypi:
     name: Build and publish to PyPI
+    # Stays skipped until the Trusted Publisher is configured and the repo
+    # variable PUBLISH_TO_PYPI is set to "true" — so publishing a release before
+    # then is a no-op, never a red ✗.
+    if: ${{ vars.PUBLISH_TO_PYPI == 'true' }}
     runs-on: ubuntu-latest
     environment: pypi
     permissions:
@@ -29,3 +35,5 @@ jobs:
       - run: python -m build
       - name: Publish
         uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

README.ko.md

@@ -6,15 +6,19 @@
 
 **Cloudflare · Datadome · Turnstile · reCAPTCHA — 그냥 통과해서 본문을 가져옵니다.**
 
+[![PyPI](https://img.shields.io/pypi/v/deepcloak?color=a855f7&label=pypi)](https://pypi.org/project/deepcloak/)
 [![CI](https://github.com/Mrbaeksang/deepcloak/actions/workflows/ci.yml/badge.svg)](https://github.com/Mrbaeksang/deepcloak/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-a855f7.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
 [![MCP native](https://img.shields.io/badge/MCP-native-22d3ee.svg)](#-ai-에이전트에서-쓰기)
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-34d399.svg)](CONTRIBUTING.md)
 [![GitHub stars](https://img.shields.io/github/stars/Mrbaeksang/deepcloak?style=social)](https://github.com/Mrbaeksang/deepcloak/stargazers)
+[![Watch on YouTube](https://img.shields.io/badge/▶_demo-YouTube-FF0000.svg)](https://youtu.be/p5ompjDLzaI)
 
 [English](README.md) · **한국어** · [简体中文](README.zh-CN.md)
 
+[빠른 시작](#-빠른-시작) · [작동 방식](#-작동-방식) · [에이전트에 연결 (MCP)](#-에이전트에-연결-mcp) · [왜 만들었나](#-왜-만들었나) · [변경 이력](CHANGELOG.md)
+
 ### [▶ 라이브 데모 — deepcloak.vercel.app](https://deepcloak.vercel.app)  ·  [▶ 유튜브로 보기](https://youtu.be/p5ompjDLzaI)
 
 [![DeepCloak 실행: Cloudflare Turnstile 감지 → 에스컬레이트 → 우회 → 인용 리포트 작성](docs/media/demo.gif)](https://youtu.be/p5ompjDLzaI)
@@ -114,6 +118,15 @@ args = ["mcp"]
 
 DeepCloak은 봇 감지를 Bypass합니다. **가져오는 콘텐츠에 접근할 권리는 너의 책임입니다.** robots.txt는 **기본 무시**되며, `--respect-robots`로 존중할 수 있어요 ([ADR-0002](docs/adr/0002-ignore-robots-by-default.md)). 사이트 약관·법을 어기는 데 쓰지 마세요.
 
+## 🗺️ 로드맵
+
+- Bot Wall 시그니처 추가 + 더 똑똑한 Escalation 휴리스틱
+- DuckDuckGo / SearXNG 외 검색 백엔드 추가
+- Bypass한 페이지 런 간 캐싱
+- Evidence Record 내보내기 강화 (HTML / JSON 스키마)
+
+아이디어 환영 — [Discussion](https://github.com/Mrbaeksang/deepcloak/discussions) 열거나 [기능 제안](https://github.com/Mrbaeksang/deepcloak/issues/new/choose) 주세요.
+
 ## 🛠️ 기반
 
 [`local-deep-research`](https://github.com/LearningCircuit/local-deep-research)(MIT) + [`CloakBrowser`](https://github.com/CloakHQ/CloakBrowser)(MIT), pip 의존 — 코드 벤더링 X. 용어집 [CONTEXT.md](CONTEXT.md), 설계 결정 [docs/adr/](docs/adr/), 기여 가이드 [CONTRIBUTING.md](CONTRIBUTING.md).

README.md

@@ -6,6 +6,7 @@
 
 **Cloudflare · Datadome · Turnstile · reCAPTCHA — it walks straight through them.**
 
+[![PyPI](https://img.shields.io/pypi/v/deepcloak?color=a855f7&label=pypi)](https://pypi.org/project/deepcloak/)
 [![CI](https://github.com/Mrbaeksang/deepcloak/actions/workflows/ci.yml/badge.svg)](https://github.com/Mrbaeksang/deepcloak/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-a855f7.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
@@ -16,6 +17,8 @@
 
 **English** · [한국어](README.ko.md) · [简体中文](README.zh-CN.md)
 
+[Quickstart](#-quickstart) · [How it works](#-how-it-works) · [Use from an agent (MCP)](#-connect-it-to-your-agent-mcp) · [Why we built it](#-why-we-built-this) · [Changelog](CHANGELOG.md)
+
 ### [▶ Live demo — deepcloak.vercel.app](https://deepcloak.vercel.app)  ·  [▶ Watch on YouTube](https://youtu.be/p5ompjDLzaI)
 
 [![DeepCloak running: it detects a Cloudflare Turnstile, escalates, and bypasses it — then writes a cited report](docs/media/demo.gif)](https://youtu.be/p5ompjDLzaI)
@@ -115,6 +118,15 @@ Then your agent can call `deep_research` and read bot-walled sources directly. P
 
 DeepCloak Bypasses bot-detection. **You are responsible for having the right to access whatever you fetch.** robots.txt is **ignored by default**; pass `--respect-robots` to honor it ([ADR-0002](docs/adr/0002-ignore-robots-by-default.md)). Don't use it to violate sites' terms or the law.
 
+## 🗺️ Roadmap
+
+- More Bot Wall signatures + smarter Escalation heuristics
+- More search backends beyond DuckDuckGo / SearXNG
+- Cache Bypassed pages across runs
+- Richer Evidence Record export (HTML / JSON schema)
+
+Ideas welcome — start a [Discussion](https://github.com/Mrbaeksang/deepcloak/discussions) or open a [feature request](https://github.com/Mrbaeksang/deepcloak/issues/new/choose).
+
 ## 🛠️ Built on
 
 [`local-deep-research`](https://github.com/LearningCircuit/local-deep-research) (MIT) + [`CloakBrowser`](https://github.com/CloakHQ/CloakBrowser) (MIT), via pip — no vendored code. Domain glossary in [CONTEXT.md](CONTEXT.md); design decisions in [docs/adr/](docs/adr/); contributing guide in [CONTRIBUTING.md](CONTRIBUTING.md).

README.zh-CN.md

@@ -6,15 +6,19 @@
 
 **Cloudflare · Datadome · Turnstile · reCAPTCHA —— 直接穿过它们，把正文带回来。**
 
+[![PyPI](https://img.shields.io/pypi/v/deepcloak?color=a855f7&label=pypi)](https://pypi.org/project/deepcloak/)
 [![CI](https://github.com/Mrbaeksang/deepcloak/actions/workflows/ci.yml/badge.svg)](https://github.com/Mrbaeksang/deepcloak/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-a855f7.svg)](LICENSE)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
 [![MCP native](https://img.shields.io/badge/MCP-native-22d3ee.svg)](#-在-ai-智能体中使用)
 [![PRs welcome](https://img.shields.io/badge/PRs-welcome-34d399.svg)](CONTRIBUTING.md)
 [![GitHub stars](https://img.shields.io/github/stars/Mrbaeksang/deepcloak?style=social)](https://github.com/Mrbaeksang/deepcloak/stargazers)
+[![Watch on YouTube](https://img.shields.io/badge/▶_demo-YouTube-FF0000.svg)](https://youtu.be/p5ompjDLzaI)
 
 [English](README.md) · [한국어](README.ko.md) · **简体中文**
 
+[快速开始](#-快速开始) · [工作原理](#-工作原理) · [接入智能体 (MCP)](#-接入你的智能体-mcp) · [我们为何要做它](#-我们为何要做它) · [更新日志](CHANGELOG.md)
+
 ### [▶ 在线演示 — deepcloak.vercel.app](https://deepcloak.vercel.app)  ·  [▶ 在 YouTube 观看](https://youtu.be/p5ompjDLzaI)
 
 [![DeepCloak 运行：检测 Cloudflare Turnstile → 升级 → 绕过 → 生成带引用的报告](docs/media/demo.gif)](https://youtu.be/p5ompjDLzaI)
@@ -114,6 +118,15 @@ args = ["mcp"]
 
 DeepCloak 会绕过机器人检测。**你有责任确保自己有权访问所抓取的内容。** robots.txt **默认被忽略**，可用 `--respect-robots` 遵守（[ADR-0002](docs/adr/0002-ignore-robots-by-default.md)）。请勿用于违反网站条款或法律。
 
+## 🗺️ 路线图
+
+- 更多 Bot Wall 特征 + 更智能的 Escalation 启发式
+- 除 DuckDuckGo / SearXNG 外的更多搜索后端
+- 跨运行缓存已绕过的页面
+- 更丰富的 Evidence Record 导出（HTML / JSON schema）
+
+欢迎想法 —— 发起 [Discussion](https://github.com/Mrbaeksang/deepcloak/discussions) 或提交 [功能请求](https://github.com/Mrbaeksang/deepcloak/issues/new/choose)。
+
 ## 🛠️ 构建于
 
 [`local-deep-research`](https://github.com/LearningCircuit/local-deep-research)（MIT）+ [`CloakBrowser`](https://github.com/CloakHQ/CloakBrowser)（MIT），通过 pip 依赖 —— 不内嵌代码。术语表 [CONTEXT.md](CONTEXT.md)，设计决策 [docs/adr/](docs/adr/)，贡献指南 [CONTRIBUTING.md](CONTRIBUTING.md)。