z-clean 0.1.1 → 0.3.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 whynowlab
+Copyright (c) 2026 thestack-ai
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.ko.md

@@ -0,0 +1,118 @@
+# zclean
+
+**Claude Code, Codex, Cursor, Windsurf, MCP 서버, agent browser, 로컬 개발 캐시를 위한 AI 코딩 런타임 위생 CLI입니다.**
+
+[English](README.md) | [한국어](README.ko.md) | [中文](README.zh.md)
+
+## zclean이 해결하는 문제
+
+AI 코딩 도구는 작업 중 많은 임시 런타임을 만듭니다.
+
+- MCP 서버
+- Claude Code sub-agent
+- Codex sandbox
+- headless browser / Playwright
+- `npm exec`, `tsx`, `bun`, `deno`, Python helper
+- Vite, Next.js, webpack, esbuild 같은 개발 서버와 watcher
+
+세션이 종료되거나 강제 종료되면 일부 프로세스가 orphan/zombie처럼 남아 메모리, 포트, 파일 핸들을 계속 잡을 수 있습니다. `zclean`은 이런 잔재를 찾아 설명하고, 안전 조건을 통과한 경우에만 정리합니다.
+
+## zclean이 하는 일
+
+1. **AI 런타임 zombie process 정리**
+   - Claude Code, Codex, Cursor/Windsurf 계열 agent, MCP server, agent browser 잔재를 탐지합니다.
+   - 기본은 dry-run입니다.
+   - 실제 kill은 `--yes`가 있어야 합니다.
+
+2. **안전한 workspace cache 정리**
+   - `.next/cache`
+   - `.turbo`
+   - `.vite`
+   - `.parcel-cache`
+   - `node_modules/.cache`
+   - `.pytest_cache`
+   - `.ruff_cache`
+   - `.mypy_cache`
+   - `__pycache__`
+
+3. **리포트와 자동화용 JSON**
+   - `zclean report --json`
+   - `zclean history --json`
+   - `zclean cache --json`
+   - `zclean doctor --json`
+
+## zclean이 하지 않는 일
+
+`zclean`은 일반적인 시스템 클리너가 아닙니다.
+
+- 앱을 삭제하지 않습니다.
+- 전체 디스크를 훑지 않습니다.
+- 문서/다운로드/사진 같은 사용자 파일을 건드리지 않습니다.
+- 텔레메트리를 보내지 않습니다.
+- 임의 폴더를 추측해서 지우지 않습니다.
+
+목표는 좁고 명확합니다. **AI 코딩 런타임 정리와 개발 workspace cache hygiene**입니다.
+
+## 설치
+
+```bash
+npm install -g z-clean
+zclean init
+```
+
+설치 없이 1회 실행:
+
+```bash
+npx --yes z-clean
+```
+
+## 자주 쓰는 명령
+
+```bash
+zclean                  # zombie process dry-run scan
+zclean --yes            # 검증된 zombie process 정리
+zclean report           # 읽기 전용 hygiene report
+zclean report --json    # 자동화용 JSON report
+zclean cache            # workspace cache dry-run scan
+zclean cache --yes      # 지원되는 cache directory 삭제
+zclean cache --json     # cache 후보 JSON 출력
+zclean history --json   # 정리 이력 JSON
+zclean protect list     # 보호 목록 확인
+zclean protect add mcp-server-keep
+zclean doctor --json    # 설치/탐지/스케줄러 상태 점검
+```
+
+다른 workspace cache를 확인하려면:
+
+```bash
+zclean cache --path=/path/to/project
+```
+
+## 안전 설계
+
+- 기본은 dry-run입니다.
+- 실제 정리는 `--yes`가 있어야 합니다.
+- 살아 있는 parent process가 있으면 건드리지 않습니다.
+- tmux, screen, PM2, Forever, Docker, VS Code child process는 보호합니다.
+- kill 직전 PID identity를 다시 확인합니다.
+- 프로세스 탐지 실패는 “깨끗함”으로 숨기지 않고 오류로 표시합니다.
+- JSON 출력은 raw command와 로컬 절대경로 노출을 피합니다.
+
+## 지원 플랫폼
+
+| 플랫폼 | 상태 |
+|--------|------|
+| macOS | launchd scheduler, Claude Code hook, dry-run/cleanup |
+| Linux | systemd user timer, Claude Code hook, dry-run/cleanup |
+| Windows | Task Scheduler installer, 비파괴 CI coverage, `zclean doctor` 권장 |
+
+## 제거
+
+```bash
+zclean uninstall
+npm uninstall -g z-clean
+```
+
+## 라이선스
+
+MIT - [LICENSE](LICENSE)

package/README.md

@@ -1,120 +1,240 @@
+# zclean
+
 <div align="center">
 
 <pre>
-███████  ██████ ██      ███████  █████  ███    ██
-╚══███  ██      ██      ██      ██   ██ ████   ██
-  ███   ██      ██      █████   ███████ ██ ██  ██
- ███    ██      ██      ██      ██   ██ ██  ██ ██
-███████  ██████ ███████ ███████ ██   ██ ██   ████
+zclean
+AI coding runtime hygiene
 </pre>
 
-**Stop AI coding tools from eating your RAM.**
+**AI coding runtime hygiene for Claude Code, Codex, Cursor, Windsurf, MCP servers, agent browsers, and local dev caches.**
 
-[![npm version](https://img.shields.io/npm/v/@thestackai/zclean?style=flat-square&color=blue)](https://www.npmjs.com/package/@thestackai/zclean)
+[![npm version](https://img.shields.io/npm/v/z-clean?style=flat-square&color=blue)](https://www.npmjs.com/package/z-clean)
+[![npm downloads](https://img.shields.io/npm/dm/z-clean?style=flat-square&color=brightgreen)](https://www.npmjs.com/package/z-clean)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square)](#)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white)](#)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square)](#platform-status)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-blue?style=flat-square)](#)
+[![Tests](https://img.shields.io/badge/tests-101%20passing-brightgreen?style=flat-square)](#)
+[![GitHub stars](https://img.shields.io/github/stars/TheStack-ai/zclean?style=flat-square)](https://github.com/TheStack-ai/zclean)
+[![Mentioned in Awesome Claude Code Toolkit](https://awesome.re/mentioned-badge.svg)](https://github.com/rohitg00/awesome-claude-code-toolkit)
+
+[English](README.md) | [한국어](README.ko.md) | [中文](README.zh.md)
 
 </div>
 
 <p align="center">
-  <img src="assets/demo.gif" alt="zclean demo" width="600">
+  <img src="assets/zclean-hero.png" alt="zclean AI coding runtime hygiene banner" width="960">
 </p>
 
 ---
 
-## Quick Demo
+## What zclean is
+
+`zclean` is a zero-dependency CLI that keeps AI coding sessions from leaving runtime mess behind.
+
+It helps with two local hygiene problems:
+
+1. **Zombie AI runtime processes**.
+   Orphaned MCP servers, sub-agents, headless browsers, package runners, sandboxes, and dev servers left behind by Claude Code, Codex, Cursor-style agents, Windsurf, and other AI coding tools.
+
+2. **Safe workspace cache cleanup**.
+   Common project cache directories such as `.next/cache`, `.turbo`, `.vite`, `.parcel-cache`, `node_modules/.cache`, `.pytest_cache`, `.ruff_cache`, `.mypy_cache`, and Python `__pycache__`.
+
+It is local-only, dry-run first, and requires `--yes` before destructive cleanup.
+
+## What zclean is not
+
+`zclean` is not an app uninstaller, system optimizer, disk map, telemetry agent, or whole-disk cleaner. It does not crawl your entire Mac, delete documents, remove applications, or touch arbitrary folders.
+
+The goal is narrower: **AI coding cleanup and developer workspace hygiene**.
+
+## Quick Start
+
+```bash
+npm install -g z-clean
+zclean init
+```
+
+One-off dry run without installation:
 
-AI coding tools spawn child processes — MCP servers, sub-agents, headless browsers, build watchers. When the session ends or crashes, those children don't always exit. They pile up silently, draining RAM until your machine grinds to a halt.
+```bash
+npx --yes z-clean
+```
+
+Review before cleaning:
+
+```bash
+zclean report
+zclean report --json
+```
 
-**Before**
+Clean only when you decide:
 
+```bash
+zclean --yes
+zclean cache --yes
 ```
-$ zclean
 
-  zclean — scanning for zombie processes...
+## Why developers use it
+
+AI coding tools spawn many short-lived runtimes while they work:
+
+- MCP servers
+- Claude Code sub-agents
+- Codex sandboxes
+- headless Chromium or Playwright sessions
+- `npm exec`, `tsx`, `bun`, `deno`, and Python helpers
+- build watchers such as Vite, Next.js, webpack, and esbuild
+
+When an agent crashes, a terminal closes, or a session ends abruptly, those child processes can keep running. They hold memory, ports, file handles, and CPU. zclean finds them, explains why they are candidates, and cleans them only when the safety checks pass.
+
+## Core commands
+
+| Command | What it does |
+|---------|--------------|
+| `zclean` | Dry-run scan for AI runtime zombie processes |
+| `zclean --yes` | Kill verified zombie runtime processes |
+| `zclean report` | Human-readable AI runtime hygiene report |
+| `zclean report --json` | Machine-readable report for CI, local dashboards, or agents |
+| `zclean audit` | Alias for `zclean report` |
+| `zclean cache` | Dry-run scan for supported workspace cache directories |
+| `zclean cache --yes` | Remove supported workspace cache directories |
+| `zclean cache --json` | Machine-readable cache hygiene report |
+| `zclean history` | Recent cleanup history |
+| `zclean history --json` | Sanitized cleanup history and cumulative stats |
+| `zclean protect list` | Show protected process patterns |
+| `zclean protect add <entry>` | Add a protected process pattern |
+| `zclean protect remove <entry>` | Remove a protected process pattern |
+| `zclean protect remove --index=N` | Remove a protected entry by index |
+| `zclean doctor` | Check hook, scheduler, config, and process enumeration health |
+| `zclean doctor --json` | Structured health check output |
+| `zclean init` | Install Claude Code hook and OS scheduler |
+| `zclean status` | Show current zombie status and recent cleanup |
+| `zclean logs` | Show detailed cleanup log |
+| `zclean config` | Show current configuration |
+| `zclean uninstall` | Remove hooks and schedulers |
+
+## Runtime cleanup
+
+Dry run:
+
+```bash
+zclean
+```
+
+Example output:
+
+```text
+zclean - scanning for zombie processes...
 
-  Found 12 zombie processes:
+Found 12 zombie processes:
 
-    PID 26413  node         367 MB  (orphan, 18h)  was: claude mcp-server
-    PID 62830  chrome       200 MB  (orphan, 3h)   was: agent-browser
-    PID 26221  npm          142 MB  (orphan, 2d)   was: npm exec task-master-ai
-    PID 23096  node         355 MB  (orphan, 6h)   was: claude sub-agent
-    ... 8 more
+  PID 26413  node      367 MB  18h  claude mcp-server
+  PID 62830  chrome    200 MB   3h  agent-browser
+  PID 26221  npm       142 MB   2d  npm exec task-master-ai
 
-  Total: 12 zombies, ~2.4 GB reclaimable
+Total memory reclaimable: 2.4 GB
+Run zclean --yes to clean up these processes.
+```
+
+Actual cleanup:
 
-  Run `zclean --yes` to clean.
+```bash
+zclean --yes
 ```
 
-**After**
+Safety rules:
+
+- Manual scans are dry-run by default.
+- Cleanup requires `--yes`.
+- Active parent sessions are protected.
+- tmux, screen, PM2, Forever, Docker, and VS Code child processes are skipped.
+- PID identity is re-verified before every kill to avoid PID recycling accidents.
+- Process enumeration failures are reported as errors, not as a fake "clean" state.
 
+## Workspace cache cleanup
+
+Dry run:
+
+```bash
+zclean cache
 ```
-$ zclean --yes
 
-  zclean — scanning for zombie processes...
+Clean supported cache directories:
 
-  Cleaned 12 zombie processes. Reclaimed ~2.4 GB.
+```bash
+zclean cache --yes
+```
+
+Scan another workspace:
 
-  zclean status:
-    Protection: active
-    SessionEnd hook: registered
-    Hourly scheduler: running
+```bash
+zclean cache --path=/path/to/project
 ```
 
-## Why zclean?
+Supported default cache targets:
 
-Claude Code, Codex, and other AI coding tools spawn dozens of child processes per session: MCP servers, sub-agents, headless Chromium instances, esbuild watchers, and more. When the parent session exits — especially on crash or force-quit — these children become orphans.
+| Cache path | Common source |
+|------------|---------------|
+| `.next/cache` | Next.js |
+| `.nuxt` | Nuxt |
+| `.turbo` | Turborepo |
+| `.vite` | Vite |
+| `.parcel-cache` | Parcel |
+| `node_modules/.cache` | JavaScript tooling |
+| `.pytest_cache` | pytest |
+| `.ruff_cache` | Ruff |
+| `.mypy_cache` | mypy |
+| `__pycache__` | Python bytecode |
 
-They keep running. They keep consuming RAM. Your machine gets slower day by day, and you blame the AI tool when the real culprit is zombie processes nobody cleaned up.
+`zclean cache --json` emits relative paths only. It does not expose absolute local paths and does not remove anything unless `--yes` is present.
 
-`zclean` fixes this automatically. Install once, forget about it.
+## Report and JSON surfaces
 
-## Install
+`zclean report --json` is designed for scripts, CI notes, local dashboards, and other agents:
 
 ```bash
-npx zclean init
+zclean report --json
 ```
 
-That's it. This command:
-1. Detects your OS (macOS / Linux / Windows)
-2. Registers a Claude Code `SessionEnd` hook for instant cleanup
-3. Sets up an hourly background scan as a safety net
-4. Creates your config at `~/.zclean/config.json`
+The report includes:
 
-## How it works
+- `schemaVersion: 1`
+- AI runtime hygiene status
+- candidate count and reclaimable memory
+- top candidates by risk
+- scan warnings and errors
+- cleanup history summary
+- safety guardrails
+- recommended next actions
 
-**Layer 1 — SessionEnd Hook**
-When a Claude Code session ends, `zclean` immediately cleans up that session's orphaned children. Fast and targeted.
+Raw command lines and local filesystem paths are omitted from public JSON surfaces.
 
-**Layer 2 — Hourly Scheduler**
-A lightweight background scan catches anything the hook missed: crash leftovers, Codex orphans, stale browser daemons, and processes from tools that don't support hooks.
+## History, protection, and doctor
 
-Together, these two layers keep your system clean without you ever thinking about it.
+Machine-readable history:
 
-## Safety
+```bash
+zclean history --json
+```
 
-`zclean` follows one rule: **if the parent is alive, don't touch it.**
+Protection list management:
 
-- Scans are **dry-run by default** — you see what would be cleaned before anything happens
-- Only targets **known AI tool process patterns** (MCP servers, agent browsers, sub-agents, build zombies)
-- **Whitelist support** — protect any process you want to keep
-- **Skips** tmux/screen sessions, PM2/Forever daemons, Docker containers, VS Code children
-- **Re-verifies** PID identity before every kill (prevents PID recycling accidents)
-- Logs every action with full command line for manual recovery
+```bash
+zclean protect list
+zclean protect add "mcp-server-keep"
+zclean protect remove "mcp-server-keep"
+```
 
-Your `node server.js` running in a terminal tab? Untouched. Your `vite dev` in tmux? Untouched. Only true orphans from dead AI sessions get cleaned.
+Health checks:
 
-## Commands
+```bash
+zclean doctor
+zclean doctor --json
+```
 
-| Command | Description |
-|---------|-------------|
-| `zclean` | Scan for zombies (dry-run, shows what would be cleaned) |
-| `zclean --yes` | Scan and clean zombie processes |
-| `zclean init` | Install SessionEnd hook + hourly scheduler |
-| `zclean status` | Show protection status and cleanup history |
-| `zclean logs` | View detailed cleanup log |
-| `zclean config` | Show current configuration |
-| `zclean uninstall` | Remove all hooks and schedulers |
+`doctor --json` exits `0` only when the setup is healthy. Warnings and errors exit `1` so automation can treat non-healthy states honestly.
 
 ## Configuration
 
@@ -125,62 +245,86 @@ Your `node server.js` running in a terminal tab? Untouched. Your `vite dev` in t
   "whitelist": [],
   "maxAge": "24h",
   "memoryThreshold": "500MB",
-  "schedule": "hourly",
+  "maxKillBatch": 20,
   "sigterm_timeout": 10,
   "dryRunDefault": true,
-  "logRetention": "30d"
+  "logRetention": "30d",
+  "customAiDirs": []
 }
 ```
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `whitelist` | `[]` | Process name patterns to never kill |
-| `maxAge` | `"24h"` | Kill orphan `node`/`esbuild` only after this age |
-| `memoryThreshold` | `"500MB"` | Flag orphans above this RAM usage regardless of age |
+| `whitelist` | `[]` | Process name patterns to never kill; manage with `zclean protect` |
+| `maxAge` | `"24h"` | Flag orphaned AI-path runtime processes only after this age |
+| `memoryThreshold` | `"500MB"` | Flag AI-path runtime orphans above this memory usage |
+| `maxKillBatch` | `20` | Maximum process kills per invocation |
 | `sigterm_timeout` | `10` | Seconds to wait after SIGTERM before SIGKILL |
-| `dryRunDefault` | `true` | Manual `zclean` runs in dry-run mode |
+| `dryRunDefault` | `true` | Manual scans stay dry-run by default; cleanup still requires `--yes` |
+| `logRetention` | `"30d"` | Cleanup history retention |
+| `customAiDirs` | `[]` | Additional AI tool directories to detect, such as `[".mytool"]` |
+
+## Supported tools
+
+| Tool or runtime | Coverage |
+|-----------------|----------|
+| Claude Code | MCP servers, sub-agents, sessions, agent browsers, Playwright |
+| Codex | `codex exec`, Codex sandboxes |
+| Cursor and Windsurf-style agents | AI-path runtime leftovers and browser helpers |
+| Aider | Orphaned Aider/Python processes |
+| Gemini CLI | Orphaned Gemini processes |
+| MCP servers | `mcp-server-*` patterns |
+| JavaScript runtimes | `node`, `tsx`, `ts-node`, `bun`, `deno` on AI paths |
+| Build tools | Vite, Next.js, webpack, esbuild on AI paths |
+| Workspace caches | Next.js, Nuxt, Turborepo, Vite, Parcel, Python, JS tooling caches |
+
+## Platform status
+
+| Platform | Status |
+|----------|--------|
+| macOS | launchd scheduler, Claude Code hook, dry-run and cleanup paths |
+| Linux | systemd user timer, Claude Code hook, dry-run and cleanup paths |
+| Windows | Task Scheduler installer and non-destructive CI coverage; run `zclean doctor` after install to confirm local scheduler and process enumeration health |
 
 ## FAQ
 
-### Will this kill my running Claude Code session?
-No. `zclean` checks if the parent process is alive. Active sessions and their children are always protected.
+### Will zclean kill my running Claude Code session?
+
+Manual and scheduled scans protect active sessions by checking whether the parent process is alive. The Claude Code `SessionEnd` hook passes `--session-pid` so cleanup is scoped to descendants of the session that just ended.
+
+### Will zclean delete my project files?
+
+No. Runtime cleanup kills verified zombie processes. Cache cleanup only removes supported cache directories and only with `zclean cache --yes`.
+
+### Is zclean a general Mac cleaner?
+
+No. zclean focuses on AI coding runtime cleanup and safe developer workspace cache cleanup. It does not uninstall apps, draw disk maps, or scan the whole disk.
 
-### What about my `vite dev` / `next dev` server?
-If you started it in a terminal, tmux, or VS Code — it has a living parent and won't be touched. Only orphaned dev servers (parent process dead for 24h+) are candidates.
+### Does the scheduler slow my machine?
 
-### Does the hourly scheduler slow my machine?
-No. It runs a single process scan (~100ms), cleans if needed, and exits. No persistent daemon.
+No. The scheduler runs a single scan and exits. There is no persistent background daemon.
+
+### How do I remove zclean?
 
-### How do I stop zclean completely?
 ```bash
 zclean uninstall
-npm uninstall -g zclean
+npm uninstall -g z-clean
 ```
 
-## Supported Tools
-
-| Tool | Cleanup Coverage |
-|------|-----------------|
-| Claude Code | MCP servers, sub-agents, agent-browser, playwright |
-| Codex | codex exec, background node workers |
-| Build tools | esbuild, vite, webpack, next dev (orphaned only) |
-| MCP servers | Any `mcp-server-*` pattern |
-| Runtimes | node, tsx, ts-node, bun, deno, python (AI tool paths only) |
+If you only used `npx --yes z-clean`, there is no global package to uninstall.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
-Adding a new process pattern? Edit `src/detector/patterns.js` and open a PR.
+Adding a process pattern? Edit `src/detector/patterns.js`.
+
+Adding a cache target? Keep it deterministic, workspace-scoped, and dry-run first.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT - see [LICENSE](LICENSE).
 
 ---
 
-<div align="center">
-
-Built by [whynowlab](https://github.com/whynowlab) — the team behind [Swing](https://github.com/whynowlab/swing-skills).
-
-</div>
+Built by [TheStack-ai](https://github.com/TheStack-ai).

package/README.zh.md

@@ -0,0 +1,118 @@
+# zclean
+
+**面向 Claude Code、Codex、Cursor、Windsurf、MCP server、agent browser 和本地开发缓存的 AI 编程运行时清理 CLI。**
+
+[English](README.md) | [한국어](README.ko.md) | [中文](README.zh.md)
+
+## zclean 解决什么问题
+
+AI 编程工具在工作时会启动很多临时运行时：
+
+- MCP server
+- Claude Code sub-agent
+- Codex sandbox
+- headless browser / Playwright
+- `npm exec`、`tsx`、`bun`、`deno`、Python helper
+- Vite、Next.js、webpack、esbuild 等开发服务器和 watcher
+
+当会话崩溃、终端关闭或 agent 强制退出时，一些子进程可能会继续运行，占用内存、端口、CPU 和文件句柄。`zclean` 会找出这些候选项，解释原因，并且只在你明确确认后清理。
+
+## zclean 可以做什么
+
+1. **清理 AI 运行时 zombie process**
+   - 覆盖 Claude Code、Codex、Cursor/Windsurf 类 agent、MCP server、agent browser 等遗留进程。
+   - 默认只做 dry-run。
+   - 只有传入 `--yes` 才会真正清理。
+
+2. **安全清理 workspace cache**
+   - `.next/cache`
+   - `.turbo`
+   - `.vite`
+   - `.parcel-cache`
+   - `node_modules/.cache`
+   - `.pytest_cache`
+   - `.ruff_cache`
+   - `.mypy_cache`
+   - `__pycache__`
+
+3. **提供报告和自动化 JSON**
+   - `zclean report --json`
+   - `zclean history --json`
+   - `zclean cache --json`
+   - `zclean doctor --json`
+
+## zclean 不是什么
+
+`zclean` 不是通用系统清理器。
+
+- 不卸载应用。
+- 不扫描整个磁盘。
+- 不删除文档、下载、照片等用户文件。
+- 不发送遥测数据。
+- 不猜测并删除任意文件夹。
+
+它的定位很明确：**AI 编程运行时清理和开发 workspace cache hygiene**。
+
+## 安装
+
+```bash
+npm install -g z-clean
+zclean init
+```
+
+无需安装的一次性运行：
+
+```bash
+npx --yes z-clean
+```
+
+## 常用命令
+
+```bash
+zclean                  # zombie process dry-run scan
+zclean --yes            # 清理已验证的 zombie process
+zclean report           # 只读 hygiene report
+zclean report --json    # 自动化 JSON report
+zclean cache            # workspace cache dry-run scan
+zclean cache --yes      # 删除支持的 cache directory
+zclean cache --json     # 输出 cache 候选 JSON
+zclean history --json   # 清理历史 JSON
+zclean protect list     # 查看保护列表
+zclean protect add mcp-server-keep
+zclean doctor --json    # 检查安装、调度器和进程枚举状态
+```
+
+扫描另一个 workspace：
+
+```bash
+zclean cache --path=/path/to/project
+```
+
+## 安全设计
+
+- 默认 dry-run。
+- 真正清理需要 `--yes`。
+- 如果父进程仍然存在，不会触碰该进程。
+- 保护 tmux、screen、PM2、Forever、Docker、VS Code child process。
+- kill 前会重新验证 PID identity，降低 PID recycling 风险。
+- 进程枚举失败会报告错误，不会伪装成“系统干净”。
+- JSON 输出避免暴露 raw command 和本地绝对路径。
+
+## 平台状态
+
+| 平台 | 状态 |
+|------|------|
+| macOS | launchd scheduler、Claude Code hook、dry-run/cleanup |
+| Linux | systemd user timer、Claude Code hook、dry-run/cleanup |
+| Windows | Task Scheduler installer、非破坏性 CI coverage，建议运行 `zclean doctor` |
+
+## 卸载
+
+```bash
+zclean uninstall
+npm uninstall -g z-clean
+```
+
+## 许可证
+
+MIT - [LICENSE](LICENSE)