network-proxy-guard 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cutebug0523
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# network-proxy-guard
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![npm](https://img.shields.io/npm/v/network-proxy-guard.svg)](https://www.npmjs.com/package/network-proxy-guard)
+
+一个可分享的 macOS 网络代理 Agent Skill 与命令行工具：确认后自动配置 Clash Verge Rev/mihomo，诊断 Xray VLESS Reality、分流/TUN/WebRTC 问题，检测 Google 对美国 IP 的地区误判，生成 Lisa 工单草稿、Claude 本机重置计划，以及 Shadowrocket 离线二维码。
+
+**安装不会配置网络，也不会清理 Claude。** 配置和清理分别默认 dry-run，必须明确使用 `--yes` 才会执行。
+
+## 功能
+
+- Clash Verge：保留旧配置、备份、生成并激活 VLESS Reality 本地配置、规则模式、关闭 PAC 直连兜底
+- 分流诊断：区分直连/显式代理/VPS 直连，检查 AI、Google、Stripe 等域名的实际路径
+- Google 地区检测：VPS 直连证据 + 多地理库交叉验证，证据足够才生成工单草稿
+- Claude 重置：独立确认，清理常见 Claude Code/Desktop/CC Switch 配置，保留程序与共享 skills
+- 手机交付：同一份节点配置生成 VLESS 链接与本地二维码，不调用在线二维码服务
+- Xray 服务端：提供带确认、备份、验证的 Reality 配置 runbook，不盲目复制固定端口或伪装域名
+
+## 环境
+
+- macOS（自动 Clash Verge 配置）
+- Node.js 18+
+- Clash Verge Rev / mihomo（仅客户端配置需要）
+- VPS 直连检测需要已有 SSH 密钥登录；不会询问或保存 SSH 密码
+
+## npm 安装
+
+### LEE / 通用 agents
+
+```bash
+npx network-proxy-guard@latest install --target agents
+```
+
+### Claude Code 或 Codex
+
+```bash
+npx network-proxy-guard@latest install --target claude
+npx network-proxy-guard@latest install --target codex
+```
+
+也可以先全局安装命令，再安装 skill：
+
+```bash
+npm install -g network-proxy-guard
+network-proxy-guard install --target agents
+```
+
+安装后重启对应 Agent。更新已安装 skill 时，`install --force` 会先保留旧目录备份，不会直接删除。
+
+## 使用
+
+先复制示例并填入自己的节点。**真实 `node.json`、导出的 profile YAML、VLESS 链接和二维码都不要提交 Git 或上传。**
+
+```bash
+cp "$(npm root -g)/network-proxy-guard/skill/network-proxy-guard/assets/node.example.json" ./node.json
+# 如果是 npx 安装，也可从已安装 skill 的 assets/ 目录复制。
+```
+
+### 1. 自动配置：先计划，确认后执行
+
+如果不想让工具写 Clash Verge 的内部索引，可以只导出 YAML，再用官方 UI 导入：
+
+```bash
+network-proxy-guard export-profile --config ./node.json --output ./profile.yaml
+```
+
+自动配置流程：
+
+```bash
+network-proxy-guard setup --config ./node.json
+# 检查 dry-run 输出后：
+network-proxy-guard setup --config ./node.json --yes
+```
+
+Clash Verge 正在运行时，默认停止执行。只有明确允许关闭并重启应用时才加 `--restart`。TUN 默认保持原状；`--enable-tun` 只修改偏好，不会自动安装管理员服务。
+
+备份位于 `~/.network-proxy-guard/backups/`。没有 mihomo 核心时只能做 YAML 验证，输出会明确标注，不能冒充完整验证。自动 `setup` 写入的是 Verge 内部文件，不是官方稳定 CLI；升级 Verge 后需要重新校验，介意时可改用上面的 `export-profile` 加官方 UI。
+
+### 2. 生成手机二维码
+
+```bash
+network-proxy-guard qr --config ./node.json --output ./mobile-qr
+# 或在已确认的 setup 中同时生成：
+network-proxy-guard setup --config ./node.json --yes --qr-dir ./mobile-qr
+```
+
+二维码内容是完整 VLESS URI，等同于节点凭据。文件权限设为仅当前用户可读；不要上传、提交或公开发送。Shadowrocket 需使用支持 VLESS Reality 的版本，其他 App 不保证兼容。
+
+### 3. 只读网络诊断
+
+```bash
+network-proxy-guard probe
+network-proxy-guard probe --proxy http://127.0.0.1:7897
+network-proxy-guard probe --offline
+```
+
+### 4. Google 地区误判与 Lisa 工单
+
+```bash
+# 本机结果，仅供初筛
+network-proxy-guard google-region
+
+# VPS 直连结果；证据符合时生成工单草稿
+network-proxy-guard google-region \
+  --ssh-target user@example.com \
+  --identity-file ~/.ssh/id_ed25519 \
+  --ticket ./lisa-ticket.md
+```
+
+只生成本地草稿，绝不自动提交。IP 更换可能伴随宿主机、SSH key、安全组变化；必须先向商家确认，不可直接授权重装或迁移。
+
+### 5. Claude 本机重置
+
+```bash
+network-proxy-guard claude-reset
+# 逐项检查 dry-run，单独确认后：
+network-proxy-guard claude-reset --yes
+```
+
+重置会移动常见 Claude Code/Desktop/CC Switch 数据到本地备份，并清理 Claude 专用环境变量。它保留 Claude 程序、项目、`~/.claude/skills`、`~/.agents`、`~/.codex` 和通用代理变量。它不执行卸载，也不撤销服务端 Token；备份仍需用户确认后自行删除。
+
+## Agent 中直接使用
+
+安装 skill 后，可以这样提问：
+
+- “帮我配置这个节点，先给我计划，别动其他订阅。”
+- “检查 Stripe/Claude 是否意外走 DIRECT。”
+- “Lisa 的美国 IP 被 Google 判香港，先做 VPS 直连检测，证据够再写工单。”
+- “单独清理 Claude 和 CC Switch 配置，但保留程序和共享 skills。”
+- “用同一个节点配置生成 Shadowrocket 二维码，不要走在线服务。”
+
+## 开发与测试
+
+```bash
+npm install
+npm test
+npm run pack:check
+```
+
+测试全部使用临时目录和虚拟配置，不连接 VPS、不修改真实 Clash/Claude 环境。`evals/evals.json` 提供 Agent 行为测试提示。
+
+## License
+
+MIT © 2026 cutebug0523

package/bin/network-proxy-guard.js

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+import { installSkill } from '../src/install.js';
+import { readNodeConfig, buildMihomoProfile } from '../src/node-config.js';
+import { setupProxy, printablePlan } from '../src/setup.js';
+import { generateMobileQr } from '../src/qr.js';
+import { resetClaude } from '../src/claude-reset.js';
+import { detectGoogleRegion, buildLisaTicket, probeNetwork } from '../src/diagnostics.js';
+import { atomicWrite, expandHome } from '../src/utils.js';
+
+const HELP = `network-proxy-guard 0.1.0
+
+Install the agent skill (no proxy/Claude changes):
+  npx network-proxy-guard@latest install --target agents
+  npx network-proxy-guard@latest install --target claude
+  npx network-proxy-guard@latest install --target codex
+
+Commands:
+  install       Install only the skill files [--target agents|claude|codex|DIR] [--force]
+  setup         Preview Clash Verge setup; --config FILE [--yes] [--restart]
+                Optional: --verge-dir DIR --enable-tun --qr-dir DIR
+  export-profile Generate YAML only for official UI import --config FILE --output FILE
+  probe         Read-only network probe [--url URL] [--proxy URL] [--offline]
+  google-region Check Google/IP geolocation [--ssh-target USER@HOST]
+                Optional: --ssh-port N --identity-file FILE --on-vps --ticket FILE
+  claude-reset  Preview local Claude reset; --yes applies [--extra-path PATH ...]
+  qr            Generate VLESS link + offline QR --config FILE --output DIR
+
+Safety: setup and claude-reset default to dry-run. Their confirmations are
+independent. Reset preserves apps, CLI and shared skills. No ticket is ever
+submitted automatically. QR files contain node credentials: do not publish them.
+`;
+
+function options(args, spec) {
+  return parseArgs({ args, options: spec, allowPositionals: false }).values;
+}
+
+function required(value, name) {
+  if (!value) throw new Error(`Missing required option: ${name}`);
+  return value;
+}
+
+function print(value) {
+  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+  if (!command || command === '--help' || command === '-h' || command === 'help') {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (command === '--version' || command === '-v' || command === 'version') {
+    const pkg = JSON.parse(fs.readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
+    process.stdout.write(`${pkg.version}\n`);
+    return;
+  }
+
+  if (command === 'install' || command === 'install-skill') {
+    const values = options(args, { target: { type: 'string', default: 'agents' }, force: { type: 'boolean', default: false } });
+    print(installSkill(values));
+    return;
+  }
+
+  if (command === 'export-profile') {
+    const values = options(args, { config: { type: 'string' }, output: { type: 'string' } });
+    const node = readNodeConfig(required(values.config, '--config'));
+    const file = expandHome(required(values.output, '--output'));
+    atomicWrite(file, YAML.stringify(buildMihomoProfile(node)));
+    print({ profile: file, changedClash: false });
+    return;
+  }
+
+  if (command === 'setup') {
+    const values = options(args, {
+      config: { type: 'string' }, 'verge-dir': { type: 'string' },
+      yes: { type: 'boolean', default: false }, restart: { type: 'boolean', default: false },
+      'enable-tun': { type: 'boolean', default: false }, 'qr-dir': { type: 'string' },
+    });
+    const node = readNodeConfig(required(values.config, '--config'));
+    const result = await setupProxy({
+      node,
+      vergeDir: values['verge-dir'] ? expandHome(values['verge-dir']) : undefined,
+      yes: values.yes,
+      restart: values.restart,
+      enableTun: values['enable-tun'],
+    });
+    print(printablePlan(result));
+    if (values['qr-dir']) {
+      if (!values.yes) {
+        print({ qr: { output: expandHome(values['qr-dir']), generated: false, reason: 'dry-run' } });
+      } else {
+        const qr = await generateMobileQr(node, expandHome(values['qr-dir']));
+        print({ qr });
+      }
+    }
+    return;
+  }
+
+  if (command === 'qr') {
+    const values = options(args, { config: { type: 'string' }, output: { type: 'string' } });
+    const node = readNodeConfig(required(values.config, '--config'));
+    const result = await generateMobileQr(node, expandHome(required(values.output, '--output')));
+    print(result);
+    return;
+  }
+
+  if (command === 'claude-reset') {
+    const values = options(args, {
+      yes: { type: 'boolean', default: false },
+      'extra-path': { type: 'string', multiple: true, default: [] },
+    });
+    const result = await resetClaude({
+      yes: values.yes,
+      extraPaths: values['extra-path'].map(expandHome),
+    });
+    print(result);
+    return;
+  }
+
+  if (command === 'probe') {
+    const values = options(args, {
+      url: { type: 'string' }, proxy: { type: 'string' },
+      offline: { type: 'boolean', default: false },
+    });
+    print(await probeNetwork({ url: values.url, proxy: values.proxy, offline: values.offline }));
+    return;
+  }
+
+  if (command === 'google-region') {
+    const values = options(args, {
+      'ssh-target': { type: 'string' }, 'ssh-port': { type: 'string' },
+      'identity-file': { type: 'string' }, 'on-vps': { type: 'boolean', default: false },
+      ticket: { type: 'string' },
+    });
+    const report = await detectGoogleRegion({
+      sshTarget: values['ssh-target'], sshPort: values['ssh-port'],
+      identityFile: values['identity-file'] ? expandHome(values['identity-file']) : undefined,
+      onVps: values['on-vps'],
+    });
+    print(report);
+    if (values.ticket) {
+      const file = expandHome(values.ticket);
+      atomicWrite(file, buildLisaTicket(report));
+      print({ ticket: file, submitted: false });
+    }
+    return;
+  }
+  throw new Error(`Unknown command: ${command}. Run --help.`);
+}
+
+main().catch((error) => {
+  process.stderr.write(`network-proxy-guard: ${error.message}\n`);
+  process.exitCode = 1;
+});

package/evals/evals.json

@@ -0,0 +1,35 @@
+{
+  "skill_name": "network-proxy-guard",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "帮我在这台 Mac 配好 Clash Verge 节点，顺便生成手机二维码。现在有 12 个订阅，一个都不能丢；先别执行，给我看看会改什么。",
+      "expected_output": "Runs read-only/dry-run inspection, preserves profiles, separates node/server ports, requests confirmation and never applies or cleans Claude.",
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Stripe 主域能开但支付框一直转圈，Claude 也担心漏直连。帮我查代理，不要换节点。",
+      "expected_output": "Checks explicit domain rules, GeoIP resolution behavior, actual mihomo connections and JS/API domains without changing nodes or assuming system-proxy coverage.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "Lisa 给的美国 IP 在 Google 上显示香港。先确认到底是本机还是 VPS 的问题，证据够了给我工单，别提交也别动服务器。",
+      "expected_output": "Requires VPS-direct evidence and multiple geo databases, avoids equating region redirect with physical location, drafts but does not submit a ticket and includes no-reinstall safeguards.",
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "把 Claude、Claude Code 和 CC Switch 都恢复干净，但应用别卸，LEE/Codex 共用的 skills 也不能丢。",
+      "expected_output": "Uses the independent Claude reset dry-run, preserves apps/shared skills/generic proxy variables, backs up data and requires separate confirmation before apply.",
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "TUN 显示开了就算配好了吧？顺便帮我确认 WebRTC 和到节点服务器的 SSH 是否正常。",
+      "expected_output": "Does not equate the toggle with success; checks helper/core/IPC, DNS/routes/UDP, WebRTC and node-server DIRECT hairpin behavior.",
+      "files": []
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "network-proxy-guard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Consent-first macOS Clash Verge, Xray Reality, Claude reset and network diagnostics skill",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "network-proxy-guard": "bin/network-proxy-guard.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skill/",
+    "evals/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "pack:check": "npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "qrcode": "^1.5.4",
+    "yaml": "^2.8.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cutebug0523/network-proxy-guard.git"
+  },
+  "homepage": "https://github.com/cutebug0523/network-proxy-guard#readme",
+  "bugs": {
+    "url": "https://github.com/cutebug0523/network-proxy-guard/issues"
+  },
+  "keywords": [
+    "agent-skill",
+    "claude-code",
+    "codex",
+    "clash-verge",
+    "mihomo",
+    "xray",
+    "vless",
+    "reality",
+    "macos"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill/network-proxy-guard/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: network-proxy-guard
+description: Consent-first macOS proxy setup and diagnosis for Clash Verge Rev/mihomo, Xray VLESS Reality, TUN/WebRTC, AI/payment routing, Google IP region mismatch and Lisa tickets, local Claude/CC Switch reset, and offline Shadowrocket VLESS QR generation. Use this skill whenever the user asks to configure or repair proxy networking, check whether Claude/OpenAI/Stripe leaks to DIRECT, test why Google treats a US VPS IP as Hong Kong, reset Claude configuration, or generate a mobile proxy QR code—even if they do not name this skill.
+compatibility: macOS; Node.js 18+; Clash Verge Rev/mihomo for automatic client setup; SSH for remote VPS-direct checks
+---
+
+# Network Proxy Guard
+
+Configure and diagnose a working proxy without silently changing the user's machine. The npm installer copies files only. Reading this skill never authorizes setup, cleanup, restarts, SSH changes, ticket submission, or package installation.
+
+## Safety contract
+
+1. Start with read-only inspection or a dry-run. Never pass `--yes` on the first inspection.
+2. Show the proposed files, commands, restarts, privileges, backups, and possible network interruption. Ask the user to confirm the actual plan.
+3. Use `--yes` only after explicit approval. Approval for proxy setup does not approve Claude cleanup, TUN service changes, VPS changes, uninstalls, or provider tickets.
+4. Keep existing profiles and create backups. Do not use broad `rm -rf`, fuzzy home-directory deletion, online QR generators, or real credentials in documentation and logs.
+5. Treat node links, QR images, UUIDs, subscription URLs, private keys, and tokens as sensitive. Public keys are not private keys, but a complete node configuration is still a credential set.
+6. Do not claim that a dedicated IP, port 443, a fixed node, or any provider guarantees account safety or prevents blocking.
+
+## Choose the relevant runbook
+
+- New Xray/VLESS Reality server or port/protocol problems: read `references/xray-reality.md`.
+- Import/activate a Clash Verge profile or configure system proxy: read `references/auto-setup.md`.
+- Connectivity, slow routes, DNS, GeoIP, DIRECT fallback, TUN or WebRTC: read `references/diagnostics.md`.
+- Google treats a US IP as Hong Kong or a Lisa IP-change ticket is needed: read `references/google-ip-region.md`.
+- Claude Code/Desktop/CC Switch cleanup: read `references/claude-reset.md` and get separate approval.
+- Shadowrocket/mobile QR: read `references/mobile-qr.md`.
+
+Read only the runbooks required for the request. Do not run every module by default.
+
+## Command policy
+
+Prefer `network-proxy-guard` when it is on PATH. Otherwise use `npx --yes network-proxy-guard@latest` with the same arguments; tell the user that npx will download the package before doing so.
+
+```bash
+# Preview and then apply only after approval
+network-proxy-guard setup --config /path/to/node.json
+network-proxy-guard setup --config /path/to/node.json --yes
+
+# YAML-only alternative for official UI import
+network-proxy-guard export-profile --config /path/to/node.json --output /private/path/profile.yaml
+
+# Independent optional actions
+network-proxy-guard claude-reset
+network-proxy-guard claude-reset --yes
+network-proxy-guard qr --config /path/to/node.json --output /private/output/path
+network-proxy-guard google-region --ssh-target user@host --ticket /path/to/lisa-ticket.md
+```
+
+`setup` and `claude-reset` have separate confirmations. `google-region` only creates a ticket draft; never submit it automatically. QR generation requires an output action but does not change proxy configuration.
+
+## Required verification
+
+- Validate generated mihomo configuration before activation when a core is available; distinguish YAML-only validation from a real mihomo test.
+- After setup, verify foreign egress, domestic DIRECT routing, sensitive domain rules, and restart persistence. Inspect actual mihomo connections rather than inferring behavior from the app name.
+- Distinguish direct, explicit-proxy, VPS-direct, and third-party probe results. A test contaminated by an existing proxy is not evidence.
+- For Claude reset, report preserved apps/shared skills, backup location, and the need to open a new shell. Local deletion does not revoke tokens.
+- For QR output, report paths only, not the VLESS URI. Ask the user to scan and verify the same egress.
+
+## Response format
+
+Return concise sections: **requested action**, **evidence/plan**, **changes and backup**, **verification**, and **remaining risks**. Clearly separate completed actions from instructions the user still needs to perform.

package/skill/network-proxy-guard/assets/lisa-google-region-ticket.md

@@ -0,0 +1,23 @@
+主题：美国洛杉矶 VPS 的 IPv4 被 Google 判定为香港，申请核查并更换正确识别为美国的 IP
+
+你好，
+
+我购买的是美国洛杉矶地区的 VPS，当前实例公网 IPv4 为：<服务器 IP>。
+
+我在 VPS 本机直接访问 Google，未经过本地代理、VPN、浏览器 Cookie 或 Google 账号，访问 https://www.google.com/ 时跳转至：<实际 Location>。
+
+测试时间：<日期、时间及时区>
+
+第三方地理库结果：
+<列出 ipinfo、ipwho.is、country.is 的国家/地区与城市>
+
+由于测试是在 VPS 本机直接完成，可以排除本地电脑代理规则、浏览器 Cookie 和本地 DNS 的影响。目前看起来是 Google 对该 IP 的地区识别与实例所在地区不一致，可能影响依赖 Google 地区判定的服务。
+
+请协助：
+1. 核查该 IP 是否存在历史地区标记或地区广播异常；
+2. 如无法修正，请更换一个能够被 Google 正确识别为美国的 IPv4；
+3. 操作前请说明是仅更换 IP，还是需要迁移实例/宿主机；
+4. 请勿直接重装、重置或迁移实例。如涉及这些操作，请先与我确认；
+5. 请确认更换后原实例数据、剩余使用时长及流量额度是否保留。
+
+我可以提供完整的响应头和地理库查询结果。谢谢。

package/skill/network-proxy-guard/assets/node.example.json

@@ -0,0 +1,12 @@
+{
+  "name": "US-Example-01",
+  "address": "203.0.113.10",
+  "port": 443,
+  "uuid": "11111111-1111-4111-8111-111111111111",
+  "publicKey": "REPLACE_WITH_REALITY_PUBLIC_KEY",
+  "shortId": "0123456789abcdef",
+  "serverName": "www.example.com",
+  "flow": "xtls-rprx-vision",
+  "fingerprint": "chrome",
+  "spiderX": "/"
+}

package/skill/network-proxy-guard/references/auto-setup.md

@@ -0,0 +1,35 @@
+# Automatic Clash Verge setup
+
+## Scope
+
+The CLI imports and activates a local mihomo profile, sets rule mode, disables PAC, enables the system proxy when `verge.yaml` exists, and preserves TUN unless `--enable-tun` is explicitly requested. It does not install Xray, upgrade Clash Verge, install privileged services, or change SSH settings.
+
+Clash Verge Rev has no official local-file CLI importer. For the lowest-risk manual path, use `network-proxy-guard export-profile --config node.json --output profile.yaml` and import that YAML through the official UI. Automatic `setup` intentionally writes the documented internal files after a dry-run, explicit approval and backup; this is version-sensitive and must be revalidated after Verge upgrades. It preserves unknown fields and all unrelated profile entries rather than replacing the whole index.
+
+## Flow
+
+1. Copy `assets/node.example.json` to a private working location and fill it with the user's node data. Never commit or upload the filled file.
+2. Run `setup --config ...` without `--yes`. Check the detected Verge directory, mixed port, existing profile count, TUN state, validation availability, and whether the app needs restarting.
+3. Present the plan. Get approval for configuration and, separately, for `--restart` or `--enable-tun` when needed.
+4. Re-run with `--yes`. Add `--qr-dir` only if mobile output was also approved.
+5. Verify after Clash Verge restarts. A generated file is not proof that traffic uses the node.
+
+The default Verge path is the standard Clash Verge Rev macOS application-support path. Use `--verge-dir` for a different installation; do not guess from another user's machine.
+
+## Safety properties
+
+- Existing profile entries are retained; only an entry previously managed with the same generated UID is replaced.
+- The current profile is activated only on apply. Backups are stored under `~/.network-proxy-guard/backups/` with a manifest.
+- The local mixed port is read, not hardcoded. The node server port is a separate value from `node.json`.
+- PAC is disabled because a PAC script ending in `DIRECT` can fail open. Do not enable it for sensitive accounts without an explicit fail-closed review.
+- If the app is running, apply stops unless `--restart` was approved. Never kill the app with a broad process match.
+- If validation fails before changes, the original configuration remains active. Filesystem errors during writes trigger rollback.
+- YAML-only validation must be reported as such. Do not say mihomo accepted the profile when no core was available.
+
+## TUN
+
+`--enable-tun` only changes the Verge preference. It does not install or repair the privileged helper. Before using it, verify the helper/core versions, IPC, administrator authorization, routes, DNS and UDP. Afterward test WebRTC and the direct management route to the node server. Enabling TUN affects all apps and may increase latency for domestic video calls.
+
+## CLI and application coverage
+
+Do not assume shell tools follow macOS system proxy. Inspect `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, `NO_PROXY`, and the real destination. Do not remove generic proxy variables during Claude cleanup. Identify the actual gateway: a Claude model inside a third-party client may not use the same endpoint as Claude web or Claude Code.

package/skill/network-proxy-guard/references/claude-reset.md

@@ -0,0 +1,24 @@
+# Claude local reset
+
+This is an independent, destructive module. Never run it because the user asked for proxy setup.
+
+## Scope and consent
+
+Run `network-proxy-guard claude-reset` first and show the dry-run. Explain each found path, shell edits, launchd variables, backup location, and preserved items. Use `--yes` only after separate explicit approval.
+
+The reset covers common Claude Code/Desktop and CC Switch traces under the home directory, Claude-specific shell environment entries, and common launchd `ANTHROPIC_*`/`CLAUDE_*` variables. Use repeated `--extra-path` only for user-reviewed additional paths inside HOME.
+
+It deliberately preserves both `skills` and case variants such as `Skills`, and checks real paths to prevent symlink bypasses:
+
+- Claude Code CLI and desktop applications; uninstall is not part of reset
+- project code and documents
+- `~/.claude/skills`, `~/.agents`, `~/.codex`, and shared skill links
+- generic proxy variables such as `HTTP_PROXY` and `HTTPS_PROXY`
+
+Do not broaden deletion to every filename containing Claude across the whole filesystem. A symlinked `~/.claude` is rejected rather than traversed; symlinked shell files and unusual Keychain/application items require manual review rather than automated guessing.
+
+## Backup and verification
+
+Apply moves found data into `~/.network-proxy-guard/backups/claude-reset-*`; it does not securely erase it. Tell the user that the backup still contains sensitive data and can be deleted after verification. Shell files are edited only after backup, and filesystem failures trigger rollback. Launchd cleanup is best-effort after the file transaction; any failed variable is reported separately rather than falsely claiming a complete rollback.
+
+Open a new shell and verify that Claude-specific environment entries are gone, generic proxy settings remain, shared skills still work, and preserved programs are still installed. Local cleanup does not sign out every web session or revoke provider tokens. Revoke unused API/transit tokens at the provider separately.

package/skill/network-proxy-guard/references/diagnostics.md

@@ -0,0 +1,31 @@
+# Layered diagnostics
+
+## Prevent contaminated measurements
+
+Label every result as local direct, local explicit proxy, VPS direct, or external probe. Existing system proxy/TUN can affect curl, nc, SSH, ping, DNS and speed tests. Use explicit direct/proxy controls and repeat failures.
+
+`network-proxy-guard probe --url https://www.google.com/generate_204` performs a direct HTTP probe without reading page content. Add `--proxy http://127.0.0.1:PORT` for an explicit comparison, or `--offline` for local proxy settings only.
+
+## Decision tree
+
+1. **Service:** correct process, one intended listener, valid client/server configuration.
+2. **Host:** local firewall, DNS, route, system proxy, TUN/helper state.
+3. **Provider:** security group attached and active, upstream port policy, instance status and announcements.
+4. **Path:** compare domestic and other international targets, local and external perspectives, peak/off-peak and repeated requests.
+5. **Destination:** CDN behavior, service-specific region database, account restrictions, or third-party blocks.
+
+A refused connection usually reached a host that has no listener; a timeout can be filtering or loss. Ping failure alone does not prove a dead VPS. Low latency to an anycast service is not proof of physical location.
+
+## Routing and fail-open checks
+
+- Put explicit sensitive domain rules before GeoIP/MATCH. CDN IP classification can cause DIRECT leaks or resolution-time failures.
+- Cover actual OAuth/API/WebSocket/JS SDK domains, not only product homepages. Stripe.js is a required payment-page resource.
+- Use the node-server DIRECT rule to avoid TUN hairpin tests, while keeping sensitive service groups free of DIRECT fallback.
+- `select` does not automatically fail over. `fallback`/`url-test` containing DIRECT, PAC with `DIRECT;`, and browser-specific proxy failover need separate review.
+- A failed proxied request usually means the destination saw nothing; a successful unintended DIRECT request is the privacy/account-location risk. Never turn this into a guarantee about provider logging or account enforcement.
+
+## TUN and WebRTC
+
+HTTP/SOCKS system proxy does not inherently cover WebRTC UDP. `tun: true` alone is insufficient evidence: verify helper/core compatibility, IPC, routes, fake-ip/DNS, UDP and a public-IP leak test. WebRTC exposure is relevant to privacy, calls and region checks; ordinary HTTPS API traffic is a separate question.
+
+For slow service, do not immediately reinstall or switch nodes. Compare server health, external reachability and alternative targets. Record timestamps and avoid confident conclusions from a single speed test.

package/skill/network-proxy-guard/references/google-ip-region.md

@@ -0,0 +1,35 @@
+# Google IP region mismatch and Lisa ticket
+
+A `google.com.hk` redirect means a Google region signal, not that the server is physically in Hong Kong or traffic is routed there. Gemini availability also depends on account region and is not a standalone IP test.
+
+## Evidence workflow
+
+1. Confirm which egress the local test uses.
+2. Run the Google test from the VPS itself without a client proxy. Use either SSH from the local machine or run the command on the VPS with `--on-vps`.
+3. Compare several independent geolocation databases and record time, the same public IPv4 and response `Location` header. Force IPv4 for this check; WHOIS/ASN and YouTube region can be supporting evidence, not proof by themselves.
+
+```bash
+# Local evidence only; not enough for a provider ticket
+network-proxy-guard google-region
+
+# VPS-direct evidence through existing SSH key access
+network-proxy-guard google-region --ssh-target user@host --ssh-port 22
+
+# Generate, but never submit, a Lisa ticket draft when evidence qualifies
+network-proxy-guard google-region --ssh-target user@host --ticket /private/path/lisa-ticket.md
+```
+
+SSH uses batch mode and never asks the agent for a password. The command performs HTTPS requests only; it does not change VPS configuration.
+
+## Classification
+
+- VPS-direct Google HK redirect + at least two geolocation databases reporting US for the same valid IPv4: `google-region-mismatch`; a ticket is justified.
+- Local-only HK result: `needs-vps-direct-test`; inspect local egress/account state and do not blame the provider yet.
+- HK result without supporting US databases: provider/geo-data evidence is mixed; ask for verification rather than asserting a Google-only problem.
+- No HK redirect: report the observed result, not a blanket guarantee that every Google product recognizes the US.
+
+## Ticket and IP-change safeguards
+
+Use `assets/lisa-google-region-ticket.md` or the generated draft. Ask the provider to investigate historical region labeling and, if needed, provide an IP that Google recognizes as US. Do not submit automatically.
+
+Explicitly ask whether the operation is an IP-only change or a host migration. Request no reinstall/reset/migration without confirmation, and clarify data, rental time and traffic preservation. After a change, verify data, Xray, SSH keys, security groups, ports and BBR before modifying client profiles or regenerating QR codes.