devklean 1.0.0__tar.gz

devklean-1.0.0/.gitignore

@@ -0,0 +1,22 @@
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+
+# Testing / tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+AUDIT.md

devklean-1.0.0/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-06-30
+
+First stable release. No breaking changes to the CLI since `0.1.0`; this
+release marks the API and behavior as stable.
+
+### Added
+
+- A default-command shorthand: running `devklean <path>` (or `devklean` with no
+  arguments) is treated as a `scan`, so the most common operation needs no
+  subcommand.
+- Permission errors encountered while scanning are now tracked and surfaced in
+  `--json` output.
+
+### Changed
+
+- Path resolution now honors `XDG_*` environment variables consistently across
+  log, config, and deletion-metadata paths on all platforms.
+  - Note: if you previously had `XDG_*` variables set, devklean may now resolve
+    these paths to different locations than before; existing logs, config, and
+    metadata in the old locations will not be migrated automatically.
+- Console output is forced to UTF-8 on Windows to render the `✓`/`✗`/`⚠`
+  symbols without raising `UnicodeEncodeError`.
+
+### Fixed
+
+- Non-interactive commands no longer crash on Windows. The `curses` import (a
+  Unix-only module) is now loaded lazily, so `scan`, `clean`, `history`,
+  `doctor`, and `restore` import and run on Windows.
+
+### Known limitations
+
+- Interactive mode (`-i` / `--interactive`) is **Linux/macOS only** because it
+  depends on `curses`, which is unavailable on Windows. On Windows, `devklean
+  clean -i` now prints a clear message and exits cleanly instead of raising an
+  `ImportError`. All other commands work on Windows.
+
+## [0.1.0] - 2026-06-28
+
+First public pre-release.
+
+### Added
+
+- **Scanning** — discover cleanable directories (`node_modules`, `.venv`,
+  `__pycache__`, `dist`, caches, and more) with size reporting; `scan` command
+  with `--json` output.
+- **Cleaning** — `clean` command moves items to the native operating-system
+  trash (Recycle Bin on Windows, Trash on macOS, freedesktop trash on Linux) via
+  `send2trash`, with a size summary and confirmation. Supports `--dry-run`,
+  interactive selection (`-i`), `--allow-symlinks`, and `-y/--yes`.
+- **History & recovery** — `history` lists past cleanup operations (timestamp,
+  reclaimed size, strategy, item count) in text or `--json`. Recovery is done
+  through the OS trash UI (the OS owns the trash); `restore` explains how.
+- **Safety layer** — a centralized `SafetyValidator` blocks deletion of the
+  filesystem root, home directory, mounted drive roots, protected system
+  directories, and symlinks (opt in with `--allow-symlinks`); protected
+  locations reached via a symlink (e.g. macOS `/etc`) are classified as
+  protected and cannot be bypassed with `--allow-symlinks`. Large deletions
+  (≥ 1 GiB by default) require typing `DELETE`.
+- **Integrity** — `doctor` command detects corrupt metadata and removes only
+  confirmed-corrupt records after confirmation; reads degrade gracefully and
+  surface warnings.
+- **Configuration** — TOML config with precedence project (`.devklean.toml`) >
+  global (`~/.config/devklean/config.toml`) > built-in defaults; keys for
+  `exclude`, `default_yes`, `theme`, `confirm_threshold`, targets, and ignores;
+  validation warns on unknown keys / malformed TOML without crashing.
+- **Logging** — structured, rotating file logs at
+  `~/.cache/devklean/logs/latest.log`, separate from terminal output.
+- **UX** — consistent `✓`/`✗`/`⚠` messaging, color that respects `NO_COLOR`,
+  non-tty output, and a `theme` setting; polished interactive mode.
+- **Performance** — `os.scandir`-based size computation and concurrent
+  per-target sizing.
+- **Packaging** — distributable via `pip`/`pipx`; MIT licensed.
+
+[Unreleased]: https://github.com/smurftyy/devklean/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/smurftyy/devklean/compare/v0.1.0...v1.0.0
+[0.1.0]: https://github.com/smurftyy/devklean/releases/tag/v0.1.0

devklean-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 smurftyy
+
+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.

devklean-1.0.0/PKG-INFO

@@ -0,0 +1,257 @@
+Metadata-Version: 2.4
+Name: devklean
+Version: 1.0.0
+Summary: Clean up common development artifacts (node_modules, .venv, caches) to reclaim disk space
+Project-URL: Homepage, https://github.com/smurftyy/devklean
+Project-URL: Repository, https://github.com/smurftyy/devklean
+Project-URL: Issues, https://github.com/smurftyy/devklean/issues
+Project-URL: Changelog, https://github.com/smurftyy/devklean/blob/main/CHANGELOG.md
+Author-email: smurftyy <oladapooloyede185@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cleanup,cli,development,disk-space,node_modules,venv
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Requires-Dist: send2trash>=1.8.2
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# devklean
+
+[![CI](https://github.com/smurftyy/devklean/actions/workflows/ci.yml/badge.svg)](https://github.com/smurftyy/devklean/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/devklean.svg)](https://pypi.org/project/devklean/)
+[![Python versions](https://img.shields.io/pypi/pyversions/devklean.svg)](https://pypi.org/project/devklean/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/smurftyy/devklean/blob/main/LICENSE)
+
+**Reclaim disk space by safely cleaning up development artifacts** — `node_modules`, `.venv`, build caches, and other regenerable directories — with a trash-backed safety net so nothing is ever lost to a typo.
+
+<!-- TODO: insert terminal recording GIF of `devklean clean` here -->
+
+## Why
+
+Development trees accumulate gigabytes of regenerable junk. `devklean` finds it, shows you exactly what it found and how big it is, and removes it **to your native system trash** — the Recycle Bin on Windows, Trash on macOS, the freedesktop trash on Linux — not `rm -rf`, so a mistaken delete is recoverable from your trash. It refuses to touch dangerous paths, makes large deletions require an explicit typed confirmation, and keeps a history of what it removed.
+
+## Installation
+
+```bash
+# Recommended: isolated install as a standalone CLI tool
+pipx install devklean
+
+# Or into the current environment
+pip install devklean
+```
+
+Requires Python 3.8+. Runtime dependencies are `send2trash` (used for all deletions) and `tomli` (only on Python < 3.11).
+
+## Quick start
+
+```bash
+# See what could be cleaned under the current directory — no changes made
+devklean scan
+
+# Scan and delete (with confirmation), moving items to the trash
+devklean clean
+
+# Preview a clean without deleting anything
+devklean clean --dry-run
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `devklean scan [PATH]` | Find cleanable directories and report sizes. Never deletes. |
+| `devklean clean [PATH]` | Scan, then delete (to trash) after confirmation. |
+| `devklean restore` | Explain how to recover deleted items from your system trash. |
+| `devklean history` | Show previous cleanup operations (timestamp, size, strategy, item count). |
+| `devklean doctor` | Inspect and repair the deletion metadata store. |
+| `devklean --version` | Print the version. |
+
+**Default command:** running `devklean` with no subcommand defaults to `clean` — so `devklean` is `devklean clean`, and `devklean ~/code` is `devklean clean ~/code`. As a convenience, a bare `devklean --dry-run` (without `-i`) is treated as a `scan` preview.
+
+### `scan`
+
+```bash
+devklean scan                 # scan current directory
+devklean scan ~/projects      # scan a specific path
+devklean scan --json          # machine-readable output for tooling
+```
+
+### `clean`
+
+```bash
+devklean clean                  # scan + delete with a y/N confirmation
+devklean clean ~/projects       # clean a specific path
+devklean clean --dry-run        # show what *would* be deleted; delete nothing
+devklean clean -i               # interactive: pick items in a TUI (Linux/macOS only)
+devklean clean --allow-symlinks # permit deleting symlinked targets (blocked by default)
+devklean clean -y               # skip the y/N prompt (large deletions still require typing DELETE)
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--dry-run` | Report what would be deleted; make no changes. Output says "would delete". |
+| `-i`, `--interactive` | Choose items in a terminal UI (SPACE select, A all, D none, ENTER confirm, Q quit). **Linux/macOS only** — see [Platform support](#platform-support). |
+| `--allow-symlinks` | Allow deleting symbolic links. Off by default (symlinks are blocked). |
+| `-y`, `--yes` | Skip the standard confirmation. Deletions over the size threshold still require typing `DELETE`. |
+
+### `restore`
+
+devklean moves items to your operating system's own trash, which the OS owns —
+so recovery is done through your file manager's trash, not through devklean.
+This command just shows you how:
+
+```bash
+devklean restore   # explains how to recover from the Recycle Bin / Trash
+```
+
+- **Windows** — open the Recycle Bin and restore the item.
+- **macOS** — open Trash in Finder and "Put Back".
+- **Linux** — open Trash in your file manager and restore.
+
+Run `devklean history` to see what was removed and when.
+
+### `history`
+
+```bash
+devklean history          # human-readable table of past cleanups
+devklean history --json   # machine-readable
+```
+
+### `doctor`
+
+```bash
+devklean doctor        # report corrupt metadata; prompt before removing it
+devklean doctor --yes  # remove corrupt records without prompting
+```
+
+## Usage example
+
+```text
+$ devklean clean ~/code/my-app
+devklean scanning /home/me/code/my-app...
+
+TYPE                   SIZE  PATH
+──────────────────────────────────────────────────────────────────────
+Node.js              612.0 MB  /home/me/code/my-app/node_modules
+Python venv          188.0 MB  /home/me/code/my-app/.venv
+Build output          34.0 MB  /home/me/code/my-app/dist
+──────────────────────────────────────────────────────────────────────
+TOTAL                834.0 MB
+
+Delete 3 directories (~834.0 MB)? (y/N) y
+
+  ✓ /home/me/code/my-app/node_modules
+  ✓ /home/me/code/my-app/.venv
+  ✓ /home/me/code/my-app/dist
+
+✓ Cleaned 3 directories, freed ~834.0 MB.
+```
+
+<!-- TODO: insert terminal recording GIF of interactive mode (`devklean clean -i`) here -->
+
+## Platform support
+
+`devklean` runs on **Linux, macOS, and Windows**. All core commands — `scan`,
+`clean`, `history`, `doctor`, and `restore` — work on every platform.
+
+**Known limitation:** interactive mode (`-i` / `--interactive`) is **Linux/macOS
+only** for now. It is built on Python's `curses` module, which is not available
+on Windows. Running `devklean clean -i` on Windows prints a clear message and
+exits without making changes, rather than crashing — use `devklean clean`
+(non-interactive) instead. Windows support for interactive mode may come in a
+future release.
+
+## Configuration
+
+`devklean` reads TOML config with the precedence **project > global > built-in defaults**:
+
+1. A project file `.devklean.toml`, discovered by walking up from the current directory.
+2. The global file `~/.config/devklean/config.toml` (or `$XDG_CONFIG_HOME/devklean/config.toml`).
+
+```toml
+# ~/.config/devklean/config.toml or ./.devklean.toml
+
+# Directory names to never touch (merged into the ignore list)
+exclude = ["node_modules", ".git"]
+
+[defaults]
+dry_run = false
+interactive = false
+default_yes = false          # skip the y/N prompt (the large-deletion DELETE gate still applies)
+theme = "default"            # "default" or "mono"
+confirm_threshold = 1073741824   # bytes; deletions >= this require typing DELETE (default 1 GiB)
+path = "."
+
+[targets]
+exclude = ["dist"]           # remove built-in target *types*
+[targets.custom]
+".turbo" = "Turborepo cache" # add custom target directory types
+
+[ignore]
+paths = ["/keep/this/node_modules"]   # absolute paths to skip
+directories = ["vendor"]              # directory names to skip
+```
+
+Scalar keys from the project file override the global file; list keys (`exclude`, `ignore.*`) are unioned. Unknown keys and malformed TOML produce a warning rather than a crash.
+
+Color follows the `theme` setting and is automatically disabled when output is piped or `NO_COLOR` is set.
+
+## Logs
+
+`devklean` writes detailed structured logs (commands, scanned/deleted paths, sizes, errors) to:
+
+```
+~/.cache/devklean/logs/latest.log   # or $XDG_CACHE_HOME/devklean/logs/latest.log
+```
+
+Logs rotate (5 backups) and are kept entirely separate from terminal output.
+
+## FAQ
+
+**Why didn't it delete something?**
+`devklean` refuses to delete paths that should never be removed: the filesystem root, your home directory, mounted drive roots, protected system directories (`/etc`, `/usr`, …), and symbolic links. Symlinks can be allowed with `--allow-symlinks`. Each refusal prints the specific reason.
+
+**It asked me to type `DELETE` — why?**
+Deletions whose total size meets the `confirm_threshold` (default 1 GiB) require an explicit typed confirmation as an extra guard against large accidental deletes. This gate is intentionally **not** bypassed by `--yes` or `default_yes`; only `--dry-run` skips it.
+
+**Where do deleted files go? Can I get them back?**
+Items are moved to your operating system's native trash (Recycle Bin on Windows, Trash on macOS, the freedesktop trash on Linux), not permanently deleted. Recover them through your file manager's trash UI — devklean does not own that trash and can't move items back. Run `devklean history` to see what was removed, or `devklean restore` for recovery instructions.
+
+**How do I exclude a folder?**
+Add its name to `exclude` (global or project `.devklean.toml`), or an absolute path to `[ignore].paths`. See [Configuration](#configuration).
+
+**Where are the logs?**
+`~/.cache/devklean/logs/latest.log` (see [Logs](#logs)).
+
+**How do I turn off colors?**
+Set `NO_COLOR=1`, pipe the output, or set `theme = "mono"` in config.
+
+**Something looks wrong with my history data.**
+Run `devklean doctor` to detect and remove corrupt metadata records.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and PRs are welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

devklean-1.0.0/README.md

@@ -0,0 +1,221 @@
+# devklean
+
+[![CI](https://github.com/smurftyy/devklean/actions/workflows/ci.yml/badge.svg)](https://github.com/smurftyy/devklean/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/devklean.svg)](https://pypi.org/project/devklean/)
+[![Python versions](https://img.shields.io/pypi/pyversions/devklean.svg)](https://pypi.org/project/devklean/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/smurftyy/devklean/blob/main/LICENSE)
+
+**Reclaim disk space by safely cleaning up development artifacts** — `node_modules`, `.venv`, build caches, and other regenerable directories — with a trash-backed safety net so nothing is ever lost to a typo.
+
+<!-- TODO: insert terminal recording GIF of `devklean clean` here -->
+
+## Why
+
+Development trees accumulate gigabytes of regenerable junk. `devklean` finds it, shows you exactly what it found and how big it is, and removes it **to your native system trash** — the Recycle Bin on Windows, Trash on macOS, the freedesktop trash on Linux — not `rm -rf`, so a mistaken delete is recoverable from your trash. It refuses to touch dangerous paths, makes large deletions require an explicit typed confirmation, and keeps a history of what it removed.
+
+## Installation
+
+```bash
+# Recommended: isolated install as a standalone CLI tool
+pipx install devklean
+
+# Or into the current environment
+pip install devklean
+```
+
+Requires Python 3.8+. Runtime dependencies are `send2trash` (used for all deletions) and `tomli` (only on Python < 3.11).
+
+## Quick start
+
+```bash
+# See what could be cleaned under the current directory — no changes made
+devklean scan
+
+# Scan and delete (with confirmation), moving items to the trash
+devklean clean
+
+# Preview a clean without deleting anything
+devklean clean --dry-run
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `devklean scan [PATH]` | Find cleanable directories and report sizes. Never deletes. |
+| `devklean clean [PATH]` | Scan, then delete (to trash) after confirmation. |
+| `devklean restore` | Explain how to recover deleted items from your system trash. |
+| `devklean history` | Show previous cleanup operations (timestamp, size, strategy, item count). |
+| `devklean doctor` | Inspect and repair the deletion metadata store. |
+| `devklean --version` | Print the version. |
+
+**Default command:** running `devklean` with no subcommand defaults to `clean` — so `devklean` is `devklean clean`, and `devklean ~/code` is `devklean clean ~/code`. As a convenience, a bare `devklean --dry-run` (without `-i`) is treated as a `scan` preview.
+
+### `scan`
+
+```bash
+devklean scan                 # scan current directory
+devklean scan ~/projects      # scan a specific path
+devklean scan --json          # machine-readable output for tooling
+```
+
+### `clean`
+
+```bash
+devklean clean                  # scan + delete with a y/N confirmation
+devklean clean ~/projects       # clean a specific path
+devklean clean --dry-run        # show what *would* be deleted; delete nothing
+devklean clean -i               # interactive: pick items in a TUI (Linux/macOS only)
+devklean clean --allow-symlinks # permit deleting symlinked targets (blocked by default)
+devklean clean -y               # skip the y/N prompt (large deletions still require typing DELETE)
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--dry-run` | Report what would be deleted; make no changes. Output says "would delete". |
+| `-i`, `--interactive` | Choose items in a terminal UI (SPACE select, A all, D none, ENTER confirm, Q quit). **Linux/macOS only** — see [Platform support](#platform-support). |
+| `--allow-symlinks` | Allow deleting symbolic links. Off by default (symlinks are blocked). |
+| `-y`, `--yes` | Skip the standard confirmation. Deletions over the size threshold still require typing `DELETE`. |
+
+### `restore`
+
+devklean moves items to your operating system's own trash, which the OS owns —
+so recovery is done through your file manager's trash, not through devklean.
+This command just shows you how:
+
+```bash
+devklean restore   # explains how to recover from the Recycle Bin / Trash
+```
+
+- **Windows** — open the Recycle Bin and restore the item.
+- **macOS** — open Trash in Finder and "Put Back".
+- **Linux** — open Trash in your file manager and restore.
+
+Run `devklean history` to see what was removed and when.
+
+### `history`
+
+```bash
+devklean history          # human-readable table of past cleanups
+devklean history --json   # machine-readable
+```
+
+### `doctor`
+
+```bash
+devklean doctor        # report corrupt metadata; prompt before removing it
+devklean doctor --yes  # remove corrupt records without prompting
+```
+
+## Usage example
+
+```text
+$ devklean clean ~/code/my-app
+devklean scanning /home/me/code/my-app...
+
+TYPE                   SIZE  PATH
+──────────────────────────────────────────────────────────────────────
+Node.js              612.0 MB  /home/me/code/my-app/node_modules
+Python venv          188.0 MB  /home/me/code/my-app/.venv
+Build output          34.0 MB  /home/me/code/my-app/dist
+──────────────────────────────────────────────────────────────────────
+TOTAL                834.0 MB
+
+Delete 3 directories (~834.0 MB)? (y/N) y
+
+  ✓ /home/me/code/my-app/node_modules
+  ✓ /home/me/code/my-app/.venv
+  ✓ /home/me/code/my-app/dist
+
+✓ Cleaned 3 directories, freed ~834.0 MB.
+```
+
+<!-- TODO: insert terminal recording GIF of interactive mode (`devklean clean -i`) here -->
+
+## Platform support
+
+`devklean` runs on **Linux, macOS, and Windows**. All core commands — `scan`,
+`clean`, `history`, `doctor`, and `restore` — work on every platform.
+
+**Known limitation:** interactive mode (`-i` / `--interactive`) is **Linux/macOS
+only** for now. It is built on Python's `curses` module, which is not available
+on Windows. Running `devklean clean -i` on Windows prints a clear message and
+exits without making changes, rather than crashing — use `devklean clean`
+(non-interactive) instead. Windows support for interactive mode may come in a
+future release.
+
+## Configuration
+
+`devklean` reads TOML config with the precedence **project > global > built-in defaults**:
+
+1. A project file `.devklean.toml`, discovered by walking up from the current directory.
+2. The global file `~/.config/devklean/config.toml` (or `$XDG_CONFIG_HOME/devklean/config.toml`).
+
+```toml
+# ~/.config/devklean/config.toml or ./.devklean.toml
+
+# Directory names to never touch (merged into the ignore list)
+exclude = ["node_modules", ".git"]
+
+[defaults]
+dry_run = false
+interactive = false
+default_yes = false          # skip the y/N prompt (the large-deletion DELETE gate still applies)
+theme = "default"            # "default" or "mono"
+confirm_threshold = 1073741824   # bytes; deletions >= this require typing DELETE (default 1 GiB)
+path = "."
+
+[targets]
+exclude = ["dist"]           # remove built-in target *types*
+[targets.custom]
+".turbo" = "Turborepo cache" # add custom target directory types
+
+[ignore]
+paths = ["/keep/this/node_modules"]   # absolute paths to skip
+directories = ["vendor"]              # directory names to skip
+```
+
+Scalar keys from the project file override the global file; list keys (`exclude`, `ignore.*`) are unioned. Unknown keys and malformed TOML produce a warning rather than a crash.
+
+Color follows the `theme` setting and is automatically disabled when output is piped or `NO_COLOR` is set.
+
+## Logs
+
+`devklean` writes detailed structured logs (commands, scanned/deleted paths, sizes, errors) to:
+
+```
+~/.cache/devklean/logs/latest.log   # or $XDG_CACHE_HOME/devklean/logs/latest.log
+```
+
+Logs rotate (5 backups) and are kept entirely separate from terminal output.
+
+## FAQ
+
+**Why didn't it delete something?**
+`devklean` refuses to delete paths that should never be removed: the filesystem root, your home directory, mounted drive roots, protected system directories (`/etc`, `/usr`, …), and symbolic links. Symlinks can be allowed with `--allow-symlinks`. Each refusal prints the specific reason.
+
+**It asked me to type `DELETE` — why?**
+Deletions whose total size meets the `confirm_threshold` (default 1 GiB) require an explicit typed confirmation as an extra guard against large accidental deletes. This gate is intentionally **not** bypassed by `--yes` or `default_yes`; only `--dry-run` skips it.
+
+**Where do deleted files go? Can I get them back?**
+Items are moved to your operating system's native trash (Recycle Bin on Windows, Trash on macOS, the freedesktop trash on Linux), not permanently deleted. Recover them through your file manager's trash UI — devklean does not own that trash and can't move items back. Run `devklean history` to see what was removed, or `devklean restore` for recovery instructions.
+
+**How do I exclude a folder?**
+Add its name to `exclude` (global or project `.devklean.toml`), or an absolute path to `[ignore].paths`. See [Configuration](#configuration).
+
+**Where are the logs?**
+`~/.cache/devklean/logs/latest.log` (see [Logs](#logs)).
+
+**How do I turn off colors?**
+Set `NO_COLOR=1`, pipe the output, or set `theme = "mono"` in config.
+
+**Something looks wrong with my history data.**
+Run `devklean doctor` to detect and remove corrupt metadata records.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Bug reports and PRs are welcome.
+
+## License
+
+MIT — see [LICENSE](LICENSE).