smart-drive-os 1.4.2__tar.gz

smart_drive_os-1.4.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DuongNAD and SmartDrive-OS Contributors
+
+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.

smart_drive_os-1.4.2/PKG-INFO

@@ -0,0 +1,537 @@
+Metadata-Version: 2.4
+Name: smart-drive-os
+Version: 1.4.2
+Summary: Organize a drive without breaking your coding agents and IDEs: move folders and relink the paths they remember, clean junk safely, and search files instantly. Zero-dependency CLI and MCP server.
+Author-email: DuongNAD <smartdrive.os@proton.me>, SmartDrive Team <smartdrive.os@proton.me>
+Maintainer-email: DuongNAD <smartdrive.os@proton.me>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/DuongNAD/smart-drive-os
+Project-URL: Documentation, https://github.com/DuongNAD/smart-drive-os#readme
+Project-URL: Repository, https://github.com/DuongNAD/smart-drive-os
+Project-URL: Issues, https://github.com/DuongNAD/smart-drive-os/issues
+Project-URL: Changelog, https://github.com/DuongNAD/smart-drive-os/releases
+Project-URL: Privacy, https://github.com/DuongNAD/smart-drive-os/blob/main/PRIVACY.md
+Keywords: ssd,exfat,cluster-slack,fts5,mcp,mcp-server,model-context-protocol,duongnad,autonomous-agent,ai-agents,claude-code,antigravity,cursor-ide,storage-audit,junk-cleaner,privacy,zero-telemetry,zero-dependency,local-first,air-gapped,sha256-snapshot,ntfs-junction,cache-offload,ssd-health,relink,file-organizer,vscode,jetbrains,file-search
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: System :: Archiving
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: Utilities
+Classifier: Topic :: Security
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Vietnamese
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+<p align="center"><img src="https://raw.githubusercontent.com/DuongNAD/smart-drive-os/main/docs/banner.jpg" alt="SmartDrive-OS — Saturn and its orderly rings in deep space" width="100%"></p>
+<!-- mcp-name: io.github.DuongNAD/smart-drive-os -->
+
+# SmartDrive-OS
+
+*Saturn's rings as orderly storage lanes: every file in its lane, across the whole drive.*
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+[![Zero Pip Dependencies](https://img.shields.io/badge/dependencies-0%20external%20pip-success.svg)](pyproject.toml)
+[![Privacy: 100% Local](https://img.shields.io/badge/Privacy-100%25%20Local-success?style=flat-square&logo=shield)](PRIVACY.md)
+[![CI](https://github.com/DuongNAD/smart-drive-os/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/DuongNAD/smart-drive-os/actions/workflows/tests.yml)
+[![M8ven Score](https://m8ven.ai/badge/mcp/duongnad-smart-drive-os-1kxkwu)](https://m8ven.ai/mcp/duongnad-smart-drive-os)
+[![Release: v1.4.2](https://img.shields.io/badge/release-v1.4.2-blue.svg)](https://github.com/DuongNAD/smart-drive-os/releases/tag/v1.4.2)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+SmartDrive-OS is a zero-dependency drive operating suite and sub-10ms SQLite FTS5 search engine for external portable SSDs (exFAT 512 KB clusters) and internal secondary workstation drives (NTFS 4 KB clusters). It is built for developers, university students, and AI coding agents (Claude Code, Claude Desktop, Antigravity, Cursor, Codex, Windsurf) to organize drives without breaking agent paths, govern `.gitignore` rules, offload `C:` caches, and verify file integrity with SHA-256 snapshots. Everything runs 100% locally on the Python 3.9+ standard library (`dependencies = []`) with zero telemetry.
+
+> 🇻🇳 **Tiếng Việt**: [README_VN.md](README_VN.md) · 🚀 **Internal NTFS Drive & C-Drive Cache Offload Guide**: [README_INTERNAL.md](README_INTERNAL.md)
+
+---
+
+## Table of Contents
+
+- [Quickstart](#quickstart)
+- [Everyday Use](#everyday-use)
+- [Why exFAT Needs This](#why-exfat-needs-this)
+- [Features at a Glance](#features-at-a-glance)
+  - [CLI Command Reference](#cli-command-reference)
+  - [Folder Moves and Coding Agents](#folder-moves-and-coding-agents)
+  - [MCP Server & AI Coding Agents](#mcp-server--ai-coding-agents)
+  - [Search Syntax](#search-syntax)
+  - [Learning Materials (Aurora Slides and Polaris)](#learning-materials-aurora-slides-and-polaris)
+  - [Gitignore Governance](#gitignore-governance)
+  - [Safe Junk Cleaner](#safe-junk-cleaner)
+  - [Snapshots and Backup](#snapshots-and-backup)
+  - [Workstation Hybrid and C-Drive Offload](#workstation-hybrid-and-c-drive-offload)
+  - [Launchers](#launchers)
+  - [Profiles](#profiles)
+- [Testing](#testing)
+- [Privacy, Security & Data Isolation](#privacy-security--data-isolation)
+- [Contributing & License](#contributing--license)
+
+---
+
+## Quickstart
+
+### 1. Install (or run without installing)
+**uvx** (after the first PyPI release): needs only [uv](https://docs.astral.sh/uv/), which also downloads a Python when the machine has none.
+```bash
+uvx smart-drive-os <subcommand>        # runs any subcommand, installs nothing
+uvx smart-drive-os mcp register --all  # registers `uvx smart-drive-os mcp` with your coding agents
+```
+**pipx** (after the first PyPI release; Python 3.9+):
+```bash
+pipx install smart-drive-os
+smart-drive <subcommand>
+smart-drive mcp register --all         # registers this install with your coding agents
+```
+`pip install smart-drive-os` works too.
+
+**From source**:
+```bash
+git clone https://github.com/DuongNAD/smart-drive-os.git
+cd smart-drive-os
+pip install -e .                    # editable install (`smart-drive` CLI)
+python -m smart_drive <subcommand>  # or run directly from the checkout
+py -m smart_drive <subcommand>      # Windows Python Launcher (when `python` is not on PATH)
+smart-drive self-path-check         # check PATH and print 1-click shell setup
+```
+Editable installs (`pip install -e .`) need pip 21.3 or newer: with an older pip (the Python 3.9 that ships with Xcode on macOS has pip 21.2), run `python -m pip install -U pip` first.
+
+### 2. Initialise the drive
+Run `Setup_SSD.bat` / `Setup_SSD.ps1` (Windows), `Setup_SSD.command` (macOS), `./Setup_SSD.sh` (Linux), or `smart-drive init --profile <name>` (see [Profiles](#profiles)):
+- `workstation-hybrid`: your secondary drive (`D:`, `E:`, …) with games, Windows apps, and coursework.
+- `internal-developer-vault`: internal NVMe/SATA SSD receiving offloaded `C:` dev and AI caches.
+- `ai-developer`: portable external SSD for LLM weights, checkpoints, datasets, and AI agents.
+- `data-science`: data engineering pipelines, raw data, and EDA notebooks.
+- `general-workspace` *(default)*: universal active/archive code, learning notes, and utilities.
+```bash
+python -m smart_drive init --profile workstation-hybrid
+python -m smart_drive init --profile ai-developer
+```
+
+### 3. Set up the MCP ecosystem (one command)
+Fetch Constellation, Polaris, Aurora Slides, Vega, Orion, Sirius, and Mira into `~/.smart-drive/mcp` (off the exFAT drive), register them with SmartDrive in every installed coding agent (Claude Code, Antigravity, Cursor, Codex), and health-check them. It lists the servers and asks which ones you want before it downloads or registers anything; safe to repeat:
+```bash
+python3 -m smart_drive setup  # macOS / Linux (Windows: python -m smart_drive setup or py -m smart_drive setup)
+```
+Answer `a` (all), `n` (none, the default), or numbers/names such as `1,3` or `polaris,vega`; Constellation, the control plane, always comes with the others while it is not installed yet. A server that is already downloaded is listed too when it would be added to an agent's config, with the agents named. `--yes` skips the question (`--only polaris,vega --yes` installs just those). A coding agent has no terminal to answer in: its run installs nothing, exits with code `4` and lists the servers, and the agent asks you in its own chat before it runs `setup --only <your picks> --yes`.
+
+Needs Node.js >= 22.4 and git. `--dry-run` previews; `--check --json` reports state (exit code `3` = setup needed); `--no-clone` stays offline; `--agents claude,cursor` limits targets. Registered servers are reused, never cloned twice (`mcp-agy` is separate: own venv, Python >= 3.10, API key).
+
+### 4. Register SmartDrive MCP standalone
+```bash
+smart-drive mcp register --all  # Antigravity, Claude, Cursor, Codex, Windsurf, .mcp.json
+```
+Or add the entry yourself. For Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), Antigravity (`~/.gemini/antigravity/mcp_config.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`) and a project's `.mcp.json`:
+```json
+{
+  "mcpServers": {
+    "smart-drive": {
+      "command": "uvx",
+      "args": ["smart-drive-os", "mcp"],
+      "env": { "PYTHONIOENCODING": "utf-8", "PYTHONUTF8": "1" }
+    }
+  }
+}
+```
+Claude Code:
+```bash
+claude mcp add --scope user smart-drive -- uvx smart-drive-os mcp
+```
+Codex (`~/.codex/config.toml`):
+```toml
+[mcp_servers.smart-drive]
+command = "uvx"
+args = ["smart-drive-os", "mcp"]
+```
+With pipx use `"command": "smart-drive", "args": ["mcp"]` instead. Apps started from the desktop (Claude Desktop on macOS, for example) may not see `~/.local/bin`: if `uvx` or `smart-drive` is not found, put its full path in `command` (`which uvx` or `where uvx`); `smart-drive mcp register` writes full paths by itself. To pin a drive add `"--root", "E:\\"` to `args` or set `SMART_DRIVE_ROOT`; otherwise it looks for a SmartDrive root above the folder the agent starts it in, then on attached drives.
+
+---
+
+## Everyday Use
+
+**Checkup (1-screen health score & next steps)** — Get a `0–100` (`A–F`) health score with plain-language status and copy-pasteable commands:
+```bash
+smart-drive checkup
+smart-drive checkup --lang vi
+```
+
+**Search (<10ms)** — Query the SQLite FTS5 index with BM25 ranking instead of recursive `find`/`grep`:
+```bash
+smart-drive search "llama cat:ai_models"
+smart-drive search "exam ext:pdf size:>1MB dir:DBI202"
+smart-drive search --kind slide "vòng lặp"
+```
+
+**Organize & Undo** — Auto-zone root folders into the 6 taxonomies, route coursework, and rebalance slack (or run `Smart_Organize.bat` / `./Smart_Organize.sh` for a guided flow):
+```bash
+smart-drive organize --dry-run
+smart-drive organize --apply
+smart-drive undo --apply        # revert the latest organize/classify batch & relink back
+```
+
+**Moving folders without breaking coding agents, IDEs, or shortcuts** — `organize --apply` and `classify --apply` relink automatically. After moving folders by hand (or via menu option `[8]` in `SmartDrive`), run:
+```bash
+smart-drive relink --find --apply --ask --wait
+smart-drive relink "E:\Old\proj" "E:\New\proj" --wait
+smart-drive paths --broken      # scan for broken IDE entries, agent configs, and .lnk shortcuts
+```
+
+**Clean (with quarantine & restore)** — Preview junk first (mandatory dry-run default). `--apply` deletes regenerable OS metadata and build caches (Tier 1-2) at once; only logs, temp files, and dumps (Tier 3) go to a restorable `.smart_drive/quarantine/`:
+```bash
+smart-drive clean                      # dry-run preview (Tier 1 by default)
+smart-drive clean --tier 2             # dry-run preview of Tier 1-2: what --apply would delete permanently
+smart-drive clean --apply --tier 3     # delete Tier 1-2 junk, quarantine Tier 3 junk
+smart-drive clean --list-quarantine
+smart-drive clean --restore latest
+```
+
+**Audit & HTML Treemap** — Inspect storage and cluster slack using actual volume cluster geometry, or export a self-contained offline HTML treemap:
+```bash
+smart-drive audit
+smart-drive audit --html
+```
+
+**Health (Sentinel)** — Verify mount, filesystem geometry, shields (auto-healed), index, and Git status:
+```bash
+smart-drive sentinel
+smart-drive health
+```
+
+**Snapshot and backup** — Create streaming SHA-256 manifests to detect bit rot and run incremental backups:
+```bash
+smart-drive snapshot create pre_release
+smart-drive snapshot verify pre_release
+smart-drive backup --target E:\Backups\SSD_Mirror --dry-run
+```
+
+---
+
+## Why exFAT Needs This
+
+High-capacity external SSDs (such as the Kingston XS2000 2 TB) format exFAT with **512 KB (524,288-byte) clusters**:
+- Physical allocation is $\lceil \text{File Size} / 524,288 \rceil \times 524,288\text{ B}$ (0 B $\rightarrow$ 0 B; 1 B $\rightarrow$ 512 KB / 99.9998% slack; 10 KB $\rightarrow$ 512 KB / 98.05% slack; 100 KB $\rightarrow$ 512 KB / 80.47% slack; 512 KB + 1 B $\rightarrow$ 1,024 KB / 50% slack).
+- A repo with **10,000 source files** (15 MB nominal) consumes **>5.12 GB** on exFAT (>99% cluster slack waste).
+- OS indexers (macOS Spotlight `mds`, Windows Search) write hidden metadata (`.DS_Store`, `Thumbs.db`, `.fseventsd`), causing I/O wear and battery drain.
+- Internal secondary SSDs (`D:`, `E:`, … on NTFS 4 KB) face `C:` exhaustion from 50–200 GB AI/dev caches while your secondary drive (`D:`, `E:`, …) hosts Windows apps, games, and active SQL Server databases that must never be moved or deleted.
+
+| Dimension | External Portable SSD (exFAT) | Internal Secondary SSD (NTFS) |
+|---|---|---|
+| **Typical Mount** | `/Volumes/KINGSTON` or `E:\` | `D:\` or `E:\` (Fixed Disk) |
+| **Cluster Size** | **512 KB** (524,288 bytes) | **4 KB** (4,096 bytes) |
+| **Primary Bottleneck** | Catastrophic cluster slack on small files | C-drive disk exhaustion & cache fragmentation |
+| **Symlink Support** | ❌ Unsupported (corrupts cross-platform) | ⚡ Supported via NTFS Junctions (`mklink /J`) |
+| **Specialized Strategy** | Bundling, anti-slack auto-zoning, anti-indexing shields | 7-Phase transactional cache offload, service protection |
+| **Protected Assets** | Root manifests, scripts, 6 core taxonomies | Windows apps, game libraries, active SQL Server databases |
+
+---
+
+## Features at a Glance
+
+| Capability | One-Line Summary | Main Command | Section |
+|---|---|---|---|
+| **Unified CLI & Storage Audit** | 25 commands for checkup, setup, FTS5 indexing, real-cluster slack math, HTML treemap, and drive governance | `smart-drive checkup` / `smart-drive audit --html` | [CLI Command Reference](#cli-command-reference) |
+| **Agent, IDE & Shortcut Relinking** | Keeps coding agents, VS Code/JetBrains/Obsidian, `.lnk` shortcuts, worktrees, and `.venv` working after moves (plus `undo` & `paths --broken`) | `smart-drive relink --find --apply --ask --wait` | [Folder Moves and Coding Agents](#folder-moves-and-coding-agents) |
+| **MCP Server & Setup** | 9 JSON-RPC 2.0 stdio tools (M8ven Grade A 100/100) and 1-command ecosystem setup | `python -m smart_drive setup` | [MCP Server & AI Coding Agents](#mcp-server--ai-coding-agents) |
+| **Sub-10ms FTS5 Search** | SQLite FTS5 `unicode61` BM25 search with extension, binary size, category, dir filters | `smart-drive search "<query>"` | [Search Syntax](#search-syntax) |
+| **Learning Materials** | Indexes Aurora Slides & Polaris (`slide`, `fact`, `capture`) and pins learning units | `smart-drive search --kind slide "<q>"` | [Learning Materials](#learning-materials-aurora-slides-and-polaris) |
+| **Gitignore Governance** | Stack-aware `.gitignore` blocks, Constellation `personal-data` guard, secret/leak audits | `smart-drive gitignore audit` | [Gitignore Governance](#gitignore-governance) |
+| **3-Tier Safe Cleaner & Quarantine** | Dry-run-first junk cleaner with reversible quarantine, restore, and inviolable system/app whitelist | `smart-drive clean` | [Safe Junk Cleaner](#safe-junk-cleaner) |
+| **Snapshots, Backup & Repos** | Streaming SHA-256 bit-rot verification, incremental backup, duplicate & clone audits | `smart-drive snapshot create` | [Snapshots and Backup](#snapshots-and-backup) |
+| **Workstation Hybrid & Offload** | Adaptive exFAT/NTFS geometry, `AcademicClassifier` (FPTU), `protected_by_system` guard, `C:` offload | `smart-drive offload --scan` | [Workstation Hybrid and C-Drive Offload](#workstation-hybrid-and-c-drive-offload) |
+| **24 Portable Launchers** | Zero-Git 1-click `.bat`, `.ps1`, `.command`, `.sh` scripts (including `Smart_Organize`) plus `self-path-check` | `Smart_Organize.bat` / `SmartDrive.bat` | [Launchers](#launchers) |
+| **5 Preset Profiles** | Layouts for hybrid workstations, C-drive vaults, AI, data science, and general use | `smart-drive init --profile <name>` | [Profiles](#profiles) |
+
+---
+
+## CLI Command Reference
+
+All commands run via `smart-drive <command>`, `python -m smart_drive <command>`, or `py -m smart_drive <command>` (Windows when `python` is not on `PATH`):
+
+| Command | Key Arguments | Description |
+|---|---|---|
+| `self-path-check` | *(none)* | Inspects Python CLI script paths on system `PATH` and outputs 1-click setup commands. |
+| `checkup` | `--root <path>`, `--dup`, `--lang {en,vi}`, `--json` | 1-screen drive health score (`0–100`), comparison against previous run, and prioritized next-step commands. |
+| `init` | `--profile <name>`, `--root <path>`, `--force`, `--json` | 1-touch drive setup, taxonomy creation, anti-indexing shield installation, and FTS5 DB seeding. |
+| `status` | `--root <path>`, `--json` | Inspect SSD mount point, detected filesystem, geometry, shield health, and taxonomy status. |
+| `audit` | `--root <path>`, `--html [file]`, `--json`, `--markdown`, `--export <file>` | Storage & cluster slack audit using the drive's real cluster size (4 KB NTFS, 512 KB exFAT, etc.). `--html` exports a self-contained offline treemap report (default `<root>/.smart_drive/reports/audit.html`). Hard links counted once; symlinks/junctions skipped and counted. |
+| `clean` | `--dry-run` *(default)*, `--apply`, `--tier {1,2,3}`, `--only-tier {1,2,3}`, `--no-quarantine`, `--list-quarantine`, `--restore <batch\|latest>`, `--purge-quarantine`, `--older-than <days>` *(default 30, `0` = every batch)*, `--log`, `--json` | Junk cleaner with mandatory dry-run and inviolable whitelist; it skips installed packages, folders the system depends on and git-tracked entries, and reports what it kept. `--apply` deletes regenerable Tier 1-2 junk permanently and at once (preview first) and quarantines only Tier 3 junk to `<root>/.smart_drive/quarantine/<batch_id>/` (restorable via `--restore`; `--no-quarantine` deletes Tier 3 too). |
+| `search` | `<query>`, `--ext <ext>`, `--size <spec>`, `--category <cat>`, `--kind <k>`, `--limit <n>`, `--json` | Sub-10ms SQLite FTS5 multi-criteria query parser with BM25 ranking. |
+| `organize` | `--dry-run`, `--apply`, `--clean`, `--json` | Auto-zoning, loose-file relocation, `AcademicClassifier` routing, `protected_by_system` guard, and agent/IDE/shortcut relinking; logs move batches to `.smart_drive/moves.jsonl`. |
+| `undo` | `--apply`, `--dry-run`, `--root <path>`, `--json` | Reverses the latest `organize`/`classify` move batch that has not been undone yet, skips items instead of overwriting when the original place is taken, and relinks agents/IDEs/shortcuts back to the original paths (dry-run default). |
+| `relink` | `[OLD NEW]`, `--find`, `--apply`, `--ask`, `--wait [MIN]`, `--root <path>`, `--dry-run`, `--json` | Rewrites project/MCP paths in coding agents, VS Code/Cursor/Windsurf/Antigravity (`storage.json` & `state.vscdb`), JetBrains (`recentProjects.xml`), Obsidian (`obsidian.json`), Windows `.lnk` shortcuts, Claude Code history, git worktrees, and `.venv`. |
+| `paths` | `--broken`, `--fix`, `--dry-run`, `--root <path>`, `--json` | Scans IDE histories, coding agent configs, Obsidian vaults, Windows `.lnk` shortcuts, and `PATH` for broken paths; suggests where moved folders went and repairs sure matches with `--fix`. |
+| `sentinel` | `--root <path>`, `--auto-heal`, `--no-heal`, `--json` | 1-touch health audit (detected filesystem, git repo status) and shield self-healing (alias: `agent-check`). |
+| `mcp` | `[{serve,register}]`, `--root <path>`, `--all`, `--auth-token <token>`, `--require-auth` | Starts the JSON-RPC 2.0 stdio MCP server (`serve`) or registers configs for AI agents (`register`). |
+| `mcp-config` | `--all`, `--antigravity`, `--claude`, `--cursor`, `--windsurf`, `--workspace`, `--json` | Auto-registers SmartDrive MCP Server in AI coding agent config files. |
+| `setup` | `--check`, `--dry-run`, `--json`, `--agents <list>`, `--only <list>`, `--dest <dir>`, `--no-clone`, `--no-health`, `--repair`, `--yes` | Asks which MCP servers to install (Constellation, Polaris, Aurora Slides, Vega, Orion, Sirius, Mira), then fetches them, registers them with installed coding agents (Claude Code, Antigravity, Cursor, Codex), and health-checks them. `--yes` skips the question. Exit code `3` from `--check` = setup needed; `4` = without a terminal and without `--yes`, user approval is needed (nothing installed). |
+| `snapshot create` | `[name]`, `--partitions <list>`, `--include-hidden`, `--root <path>`, `--json` | Generates a point-in-time manifest with 64KB-chunk streaming SHA-256 hashes. |
+| `snapshot list` | `--root <path>`, `--json` | Lists recorded point-in-time snapshots with sizes and file counts. |
+| `snapshot verify` | `<name>`, `--no-untracked`, `--root <path>`, `--json` | Validates file integrity against snapshot manifest to detect tampering or bit rot. |
+| `backup` | `--target <path>`, `--dry-run`, `--hash`, `--partitions <list>`, `--include-hidden`, `--json` | Safe incremental backup copying only modified/new files to target directory. |
+| `classify` | `[path]`, `--suggest`, `--dry-run`, `--apply`, `--recursive`, `--json` | Deep content inspection (magic bytes & markers) for AI models, datasets, docs, and code repos. Looks only at the files directly in the scanned folder; `--recursive` also visits subfolders. It never takes apart an app, library or project folder (programs, launcher scripts, manifests, `.git`) or a folder holding a program folder, so a document tree with an installer subfolder is skipped too; each is listed as `skipped_bundles`, and a folder you name gets the same check (only the drive root is exempt; `--no-recursive` is still accepted). Never follows/moves symlinks or junctions, or moves SmartDrive scripts/system files. |
+| `offload` | `--scan`, `--move <name>`, `--target <drive>`, `--revert <name>`, `--wait [MIN]`, `--force`, `--dry-run`, `--json` | Developer/AI cache discovery and transactional offloading to your secondary drive (`D:`, `E:`, …) via NTFS junction (Windows) or symlink (macOS/Linux); refuses when cache-using processes are running, or when the list of running programs cannot be read, unless `--wait` or `--force` is passed. |
+| `health` | `[drive]`, `--root <path>`, `--json` | SSD health, TRIM check (Windows), partition geometry, and utilization monitor (drive letter on Windows or `/Volumes/MySSD` on macOS/Linux). |
+| `dup` | `--root <path>`, `--min-size <bytes>`, `--json` | 3-phase SHA-256 duplicate detector with real-cluster slack reclamation preview: the slack is worked out at the volume's allocation unit (512 KB when it cannot be read) and `--json` says which as `cluster_size`. Hard links to the same data are one file, never offered for deletion. Dependency, environment and cache trees (`node_modules`, `site-packages`, virtualenvs, folders tagged `CACHEDIR.TAG` such as Cargo's `target`, `__pycache__`, `.git`, …) and folders Windows or installed apps depend on (`protected_by_system`) are not scanned; the plan counts what was skipped. Files are opened only when another file has their size, several at a time, and progress goes to stderr every ~2 s so `--json` on stdout stays parseable. |
+| `repos` | `[paths...]`, `--root <ssd>`, `--portable <path>`, `--max-depth <n>`, `--json` | Read-only report of git clones: duplicates in the same place (keep / remove / worktree suggestions) and sync state of SSD-vs-machine mirrors. |
+| `gitignore audit` | `[repo]`, `--root <path>`, `--all`, `--owner <name>`, `--keep <pat>`, `--json` | Audit repos for missing `.gitignore` patterns, tracked junk (`.agents`, pycache), and tracked personal learning data in public repos. |
+| `gitignore apply` | `<repo>`, `--yes`, `--untrack`, `--keep <pat>`, `--json` | Apply SmartDrive-managed `.gitignore` block for repo stack (dry-run default; `--yes` to apply; `--untrack` to remove matching files from git index). |
+| `index` | `--root <path>`, `--db <path>`, `--batch <n>` | Full SQLite FTS5 index creation (>15,000 files/sec). |
+| `update` | `[path]`, `--root <path>`, `--db <path>`, `--quiet`, `--json` | Fast $O(1)$ incremental search index synchronization (<2s). |
+
+---
+
+## Folder Moves and Coding Agents
+
+Coding agents, IDEs, and desktop shortcuts remember projects and MCP servers by absolute path, and exFAT cannot leave a link at the old place. When `organize` or `classify` moves a folder, SmartDrive protects system-referenced folders first and rewrites paths everywhere else:
+- **System & App Protection (`protected_by_system`)**: Before planning any move, SmartDrive scans Windows User/System `PATH`, Windows Services (`ImagePath`), Installed Apps (`Uninstall` registry `InstallLocation` / `DisplayIcon` / `UninstallString`), Startup (`Run`), `.lnk` shortcuts (Desktop, Start Menu, Quick Launch, drive root), folders containing `unins000.exe` / `uninstall.exe`, and game libraries (`SteamLibrary`, `Riot Games`, `Epic Games`, `XboxGames`, `GOG Galaxy`, `Battle.net`, `Ubisoft Game Launcher`, `EA Games`, `HoYoPlay`, `Genshin Impact`, `LDPlayer`). Any matching folder is pinned in place with its exact reason in `protected_by_system`.
+- **Keeping a folder of your own in place**: `organize` only moves what lies directly in the drive root, so a folder you keep inside one of the taxonomy folders (for example `03_Development_Projects\my-app`) stays where it is. On Windows, a folder is also `protected_by_system` when a shortcut (`.lnk`) on the Desktop, in the Start Menu or on the taskbar points at it or at something inside it: `organize`, `classify`, `clean` and `dup` leave it alone, and `organize --dry-run` lists it as skipped. A shortcut in the drive root counts too, but `classify --apply` files loose root files, `.lnk` included, and the protection leaves with the shortcut.
+- **Agent, IDE & Shortcut Settings**: Claude Code (`~/.claude.json`), Claude desktop (config, sessions, worktrees, including Microsoft Store MSIX), Codex (`config.toml`), Gemini CLI, Antigravity, Cursor, Windsurf, VS Code, VSCodium, Positron (`storage.json` and SQLite `state.vscdb`), JetBrains IDEs (`recentProjects.xml` including `$USER_HOME$` macros), Obsidian (`obsidian.json`), Windows `.lnk` shortcuts, Constellation manifest, and the drive's `.mcp.json`. Each file is backed up to `<file>.bak.smart-drive` before writing; SQLite `state.vscdb` is skipped with a warning (`busy_apps`) if the IDE currently holds it open.
+- **History and repositories**: Claude Code history and memory move to the new project folder, git worktrees are repaired, and editable installs in a moved `.venv` point at the new place.
+- **Locked folders (git fsmonitor)**: Windows refuses to rename a folder while a process holds a handle inside it, and a repository with `core.fsmonitor=true` gets a background `git fsmonitor--daemon` that does exactly that after its first `git status` (`[WinError 5] Access is denied`). SmartDrive's own git commands run with `-c core.fsmonitor=false`, so they never start one, and every move stops the daemons of the repositories inside the folder first (`--dry-run` lists them as `fsmonitor_to_stop`, `--apply` reports `fsmonitor_stopped`; git starts a daemon again by itself at the next `git status`). If a move is still refused, the error says what may be holding the folder: a program, a terminal, an Explorer window or a daemon that is still running, and on Windows the processes that have files of the folder open. Windows also refuses to rename a folder while anything *below* it is open, so a read-only probe (at most 8 levels, 20,000 entries and 5 seconds; it renames and keeps open nothing) tries to open every folder and file exclusively and names the deepest ones that are in use (`in use: E:\project\...\Images`, and `in_use` in the `--json` output of `organize`, `undo`, `classify` and the MCP tool `ssd_auto_organize`). When a folder inside is pinned in Explorer's Quick Access, the hint says so (Explorer keeps a handle on every pinned folder and opens it again at each logon, so restarting Windows alone does not help): unpin it, then restart Windows Explorer from Task Manager. When no process can be named for what is in use, the hint points at `explorer.exe` (an open Explorer window or Quick Access) and at Resource Monitor as administrator (`resmon` → CPU → Associated Handles).
+- **Reversible Journal (`undo`)**: Every batch of moves is recorded in `.smart_drive/moves.jsonl` (identified by its `time`) so `smart-drive undo --apply` can move the latest `organize`/`classify` batch back and relink agents/IDEs/shortcuts to the original paths. Moves logged by `relink` and `paths` are not undoable.
+
+How to run it:
+```bash
+smart-drive organize --dry-run                           # preview moves, protected folders, and which agents/IDEs follow
+smart-drive organize --apply                             # move, then relink agents, IDEs, Obsidian, and shortcuts
+smart-drive undo                                         # preview reversing the latest move batch
+smart-drive undo --apply                                 # undo the latest batch and relink back to original paths
+smart-drive relink                                       # re-apply latest batch (after closing an open IDE/agent)
+smart-drive relink "E:\Old\proj" "E:\New\proj" --dry-run # a folder moved by hand: preview
+smart-drive relink "E:\Old\proj" "E:\New\proj"           # ...then apply
+smart-drive relink --find                                # list stale agent/IDE paths and where folders went
+smart-drive relink --find --apply --wait                 # relink sure (?) matches after open apps close
+smart-drive relink --find --apply --ask --wait           # ...and ask y/N for each ? match first
+smart-drive paths --broken                               # inspect broken shortcuts, IDE entries, PATH, and agent configs
+smart-drive paths --broken --fix                         # repair sure matches via relink
+```
+Menu option `[8]` in `SmartDrive` (or `[10]` / `Smart_Organize.*` for the guided organizer with 1-key `U` undo) handles this interactively, and `[11]` re-applies the latest `organize`/`classify` batch: it previews `smart-drive relink --dry-run`, asks `[y/N]`, then runs `smart-drive relink --wait`. Use `[11]` after running `organize --apply` from inside a coding agent: quit the agent first (a running one may write its old paths back), then open `SmartDrive` and pick `[11]`. Close open coding agents and IDEs before relinking, or pass `--wait` so SmartDrive waits for them to close, then reopen them. If a command in a moved `.venv` still points at the old place, run `uv sync --reinstall` in that project.
+
+`--find` marks a folder ✓ only when the move journal, or what the agents remember inside the old folder, shows where it went. A folder found by its name alone is marked `?` and never relinked by `--apply` on its own, since it may be another project and the old one deleted: check it, then run the `smart-drive relink "OLD" "NEW"` command printed next to it. Or add `--ask` (menu option `[8]` does): it asks `Relink OLD -> NEW? [y/N]` for each `?` folder with one candidate, and relinks the ones you answer `y` together with the ✓ ones. Enter means no. It asks only in a terminal: with `--json` or piped input it asks nothing.
+
+---
+
+## MCP Server & AI Coding Agents
+
+SmartDrive-OS exposes a JSON-RPC 2.0 `stdio` MCP server with **9 tools**:
+
+1. `ssd_search`: Instant FTS5 search returning compact tokens (<2,000 tokens/query). *(read-only)*
+2. `ssd_audit`: Storage breakdown and cluster slack waste analytics with compact formatting. *(read-only)*
+3. `ssd_clean`: Whitelist-protected safe junk cleaner with dry-run support. A `sub_dir` is judged like the whole-drive scan, folders above it included: inside an installed app nothing is scanned and `scan_skipped` names the folder and why; the result also lists what was `kept` and the `protected_by_system` folders. *(destructive)*
+4. `ssd_find_duplicates`: 3-phase SHA-256 duplicate detection with pagination and preview capping. `min_size` drops small files before anything is hashed, slack is worked out at the drive's real allocation unit (`cluster_size`), and a `sub_dir` inside an installed app or a dependency tree is not scanned (`scan_skipped`). *(read-only)*
+5. `ssd_update_index`: Fast incremental index synchronization (<2s). *(idempotent)*
+6. `ssd_check_safety`: exFAT compatibility validator (9 Win32 forbidden chars, 22 DOS stems, symlinks). *(read-only)*
+7. `ssd_status`: SSD mount root status, shield health, and taxonomy status. *(read-only)*
+8. `ssd_auto_organize`: Autonomous drive auto-zoning and anti-slack relocation with `AcademicClassifier`. *(destructive)*
+9. `ssd_gitignore`: Stack-aware `.gitignore` governance, personal data defense, secrets audit, and safe untracking. *(idempotent)*
+
+Register across all agents via `smart-drive mcp register --all` (or `smart-drive mcp-config --all`). A pipx or pip install registers its own Python, a `uvx smart-drive-os` run registers `uvx smart-drive-os mcp`, and from a source checkout (without `pip install`) each entry sets `PYTHONPATH` to the checkout so clients can launch from any folder. Templates in `configs/`: `.mcp.json` (workspace), `mcp_config.json` (Antigravity), `claude_desktop_config.json` (Claude Desktop & Code), `cursor_mcp.json` (Cursor / Codex), `windsurf_mcp.json` (Windsurf).
+
+<details>
+<summary>M8ven MCP Directory Certification (Grade A 100/100) & Token Efficiency</summary>
+
+Certified on the [M8ven MCP Directory](https://m8ven.ai/mcp/duongnad-smart-drive-os) with a **Grade A (100/100) Trust Score** (token: `duongnad-smart-drive-os-1kxkwu`):
+- **Static AST Handler Isolation**: Mapped via `SmartDriveMCPServer.TOOL_HANDLERS` without dynamic reflection.
+- **Paged Compact JSON**: Paginated (`limit`, `offset`, `total_groups`, `returned_group_count`, `has_more`, `next_offset`) with duplicate previews capped at 10 paths/group (`truncated_files_count`).
+- **HMAC Auth & Rate Limiting**: `hmac.compare_digest` via `auth/handshake` (`--auth-token`, `--require-auth`, `SMART_DRIVE_MCP_AUTH_TOKEN`) and thread-safe `SlidingWindowRateLimiter` (`-32000` with `Retry-After`).
+- **Path Sanitizers, Loopback & Tool Hints**: `_resolve_safe_path` blocks `../`, `\0`, and cross-drive jumps; web helpers enforce `ALLOWED_LOOPBACK_HOSTS = ("127.0.0.1", "localhost")`; all 9 tools declare `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`.
+- **Zero Hidden Outbound Calls**: 100% offline `stdio`; only explicit opt-in `git clone` in `smart-drive setup` accesses the network (skipped with `--no-clone`).
+
+</details>
+
+---
+
+## Search Syntax
+
+The SQLite FTS5 engine (`unicode61` + BM25) executes multi-criteria queries in <10ms:
+
+- **Free Text**: `smart-drive search "machine learning"`
+- **File Extension**: `smart-drive search "weights ext:gguf"`
+- **Size Filter**: `smart-drive search "dataset size:>100MB"` (`size:<1MB`, `size:0`). `>`/`<` exclude the bound, `>=`/`<=` include it; binary units (`1KB = 1024` bytes). Unreadable filters (`size:>abc`, `size:>10 MB`) emit a warning (CLI stderr, MCP `warnings`) instead of being ignored silently.
+- **Taxonomy Category**: `smart-drive search "llama cat:ai_models"`
+- **Directory Constraint**: `smart-drive search "assignment dir:FPTU"`
+- **Learning Kind**: `smart-drive search --kind slide "vòng lặp"` (or `kind:fact`, `--kind capture`, `--kind lesson`)
+- **Compound Query**: `smart-drive search "exam ext:pdf size:>1MB dir:DBI202"`
+
+---
+
+## Learning Materials (Aurora Slides and Polaris)
+
+SmartDrive-OS integrates with [Aurora Slides MCP](https://github.com/DuongNAD/aurora-slides-mcp) and [Polaris MCP](https://github.com/DuongNAD/polaris-mcp) across the DuongNAD learning ecosystem:
+
+| Project | Role | Repository |
+| :--- | :--- | :--- |
+| **Polaris** | Course architect: sources, facts with locators, roadmap, schedule, error log | [polaris-mcp](https://github.com/DuongNAD/polaris-mcp) |
+| **Aurora Slides** | Keynote-style lessons: quizzes, predict and trace slides, progress events | [aurora-slides-mcp](https://github.com/DuongNAD/aurora-slides-mcp) |
+| **Vega** | FSRS memory engine and the single review queue (card inbox) | [vega-mcp](https://github.com/DuongNAD/vega-mcp) |
+| **Orion** | Practice labs with real tests, tutoring ladder and PRIMM warm-up | [orion-mcp](https://github.com/DuongNAD/orion-mcp) |
+| **Mira** | Code-tracing lab: real Python traces, line-by-line players with prediction gates | [mira-mcp](https://github.com/DuongNAD/mira-mcp) |
+| **Rigel** | Grounded tutor: answers from the learner's lesson materials with [ref] citations | [rigel-mcp](https://github.com/DuongNAD/rigel-mcp) |
+| **Sirius** | Execution loop: deadlines, triage, today router, session timer, weekly review | [sirius-mcp](https://github.com/DuongNAD/sirius-mcp) |
+| **Constellation** | MCP registration, health checks and shared contracts | [constellation-mcp](https://github.com/DuongNAD/constellation-mcp) |
+| **SmartDrive-OS** | SSD governance, index and learning search | [smart-drive-os](https://github.com/DuongNAD/smart-drive-os) |
+
+SmartDrive-OS serves Polaris (learning search), Sirius, and Rigel (file discovery), receives post-write updates (`smart-drive update <dir> --quiet`) from Aurora ($\ge$ 0.6.2), Polaris ($\ge$ 0.3.2), and Mira, and enforces the `personal-data` ignore rules of [Constellation's contracts](https://github.com/DuongNAD/constellation-mcp/tree/main/contracts).
+
+<details>
+<summary>Indexed learning artifact kinds & Atomic Learning-Unit Protection</summary>
+
+| Kind | Target Artifact | Extracted Content |
+|---|---|---|
+| `slide` | `deck.json` (Aurora Slides) | Slide titles, bullets, speaker notes, key takeaways |
+| `lesson` | `course.json` (Aurora Courses) | Lesson syllabus, objectives, prerequisites, modules |
+| `module` | `polaris/roadmap.json` (Polaris) | Roadmap modules, milestones and prerequisites |
+| `fact` | `polaris/facts.json` (Polaris) | Atomic facts, statements, concepts, confidence scores |
+| `source` | `polaris/sources.json` (Polaris) | Bibliographic citations, URLs, author notes, digests |
+| `capture` | `polaris/captures/` (Polaris) | Extracted excerpts, highlights, study pages, quotes |
+| `outline` | `polaris/lessons/*.outline.md` (Polaris) | Lesson outlines (headings) |
+| `research` | `polaris/research/*.md` (Polaris) | Deep research syntheses, literature summaries, analyses |
+| `error` | `polaris/errorlog.md` (Polaris) | Bug retrospectives, misconceptions, fixes |
+| `learning` | All learning artifacts | Consolidated search across all educational kinds |
+
+Aurora deck/course folders and Polaris subject dirs (`polaris/brief.json`) are pinned as atomic **Learning Units** (`pinned: Aurora course/deck or Polaris subject`): AutoZoner never splits/moves them, Cleaner and Duplicate Detector never delete their files, and legacy `polaris/.cache/**` files are cleaned as Tier-2 dev-cache junk (*"Polaris regenerable API cache (Polaris 0.3.2+ keeps it on C:)"*).
+
+</details>
+
+---
+
+## Gitignore Governance
+
+`smart-drive gitignore` audits and applies stack-aware `.gitignore` rules across Git repos on the drive (<5ms shallow detection for Python, Node.js, Jupyter, Java, Rust, .NET, LaTeX, AI Models, Learning). It maintains an idempotent block between `# >>> smart-drive managed (do not edit inside) >>>` and `# <<< smart-drive managed <<<`, preserving user rules and CRLF/LF line endings:
+- **exFAT Cluster Slack Defense**: Ignores `**/.agents/*` (500+ scratch files waste >260 MB on 512 KB clusters; `.agents/skills/`, `.agents/workflows/`, `.agents/rules/` stay tracked), `.claude/settings.local.json`, `__pycache__/`, `.pytest_cache/`, `node_modules/`, `target/`/`dist/`/`bin/`/`obj/`.
+- **Constellation `personal-data` Protection**: Locks down `.vega/`, `**/progress.jsonl`, `aurora-progress-*.jsonl`, `orion-attempts.jsonl`, `**/polaris/.cache/`, `**/polaris/captures/`, `.polaris/`, and `.sirius/`, alerting if tracked in public or unconfigured remotes.
+
+```bash
+smart-drive gitignore audit                                 # audit own & local repos (--all includes third-party)
+smart-drive gitignore apply D:\teamwork_projects\my_project # dry-run preview
+smart-drive gitignore apply D:\teamwork_projects\my_project --yes --untrack
+```
+
+<details>
+<summary>Ownership classes, GitHub CLI visibility, intentional build outputs, secrets & safe untracking</summary>
+
+- **Ownership Classes**: `own` (matches `--owner`, `SMART_DRIVE_GIT_OWNER`, `smartdrive.owner`, or drive consensus), `third-party` (`open_source/`, `vendor/`, `third_party/`, or external owner—upstream `dist/`/`build/` respected), and `local` (no remote).
+- **Live GitHub Visibility (`gh`)**: Queries `public`, `private`, `internal`, or `missing` ("remote not found on GitHub") with per-run caching so private/deleted remotes never trigger false public-leak alarms.
+- **Intentional Build Outputs & Keep Lists**: Files in `package.json` (`bin`, `main`, `module`, `types`, `exports`), `.gitignore` negations (`!dist/bundle.mjs`), or `smartdrive.keep` / `--keep <pattern>` are never flagged or untracked. Direct intentional files in `dist/` emit `<dir>/*` plus `!<file>` lines (or omit the pattern if nested).
+- **High-Severity Secrets & Safe Untracking**: Tracked `.env`, `.env.*`, `*.pem`, `*.key`, and `credentials*.json` alert with **variable/key names only** (no secret values). `--untrack` runs `git rm -r --cached` (keeping disk files) and refuses when uncommitted staged changes exist.
+
+</details>
+
+---
+
+## Safe Junk Cleaner
+
+Purgeable files are grouped into 3 tiers with a mandatory dry-run default (`--apply` required to move or delete):
+1. **Tier 1 (Safe OS Metadata & Bytecode)**: macOS `.DS_Store`, `._*` AppleDouble, `.Spotlight-V100`, `.Trashes`, `.TemporaryItems`; Windows `Thumbs.db`, `desktop.ini`, `ehthumbs.db`, `ehthumbs_vista.db`, `$RECYCLE.BIN`; Python `__pycache__`, `*.pyc`, `*.pyo`.
+2. **Tier 2 (Developer Caches)**: `.pytest_cache`, `.ruff_cache`, `.mypy_cache`, `.tox`, `.nox`, `.coverage`, `htmlcov`, `*.egg-info`; `build`, `dist` and `.cache` folders next to a project file; legacy `polaris/.cache/**`.
+3. **Tier 3 (Transient & Dumps)**: `*.tmp`, `*.temp`, `*.swp`, `*.swo`, `*~`, `*.dmp`, `core` and `core.<pid>` (a Unix core dump; `core.py` or `core.js` is a source file and never matches), `hs_err_pid*.log`.
+
+`clean` lists only what is really regenerable. It never lists anything of Tier 2-3 inside a dependency folder (`node_modules`, `bower_components`, `site-packages`, `.venv`, `vendor`...): that is installed package code, and `npm install` does not notice a deleted `dist/`. It never lists anything inside a folder that Windows or an installed app depends on (the same `protected_by_system` index `organize` uses: PATH, Services, Installed Apps, shortcuts, uninstallers). A `build`, `dist` or `.cache` folder counts only when a project file (`package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `*.csproj`...) lies beside it, and a Tier 2-3 entry that git tracks (or sits in a repository git cannot be asked about) is kept. The report says how many look-alikes were kept and why (`kept` and `protected_by_system` in `--json`).
+
+`smart-drive clean --apply` permanently deletes Tier 1 and Tier 2 items at once: they are regenerable (OS metadata, build caches), so they are never quarantined, and nothing can bring them back. Preview with `smart-drive clean --tier 2` first (`smart-drive checkup` recommends the same order). Only Tier 3 items (`--tier 3`: temp files, swap files, crash dumps) move into a reversible quarantine batch under `<root>/.smart_drive/quarantine/<batch_id>/` (with `manifest.json`) instead of being unlinked:
+- Quarantine Tier 3 junk alone and delete nothing else (`--tier 3 --apply` also deletes every Tier 1-2 item permanently): preview with `smart-drive clean --only-tier 3`, then run `smart-drive clean --only-tier 3 --apply`
+- Inspect quarantined batches: `smart-drive clean --list-quarantine`
+- Restore a batch to its original paths: `smart-drive clean --restore latest` (or `--restore <batch_id>`)
+- Permanently purge old quarantine batches: preview with `smart-drive clean --purge-quarantine`, then `smart-drive clean --purge-quarantine --apply` permanently deletes the batches older than 30 days (`--older-than <days>` sets another age, and `--older-than 0` purges every batch)
+- Delete Tier 3 items outright instead of quarantining them (for example when free space is critically low): `smart-drive clean --apply --tier 3 --no-quarantine`
+
+> **Inviolable Whitelist**: Root manifests (`AGENTS.md`, `GEMINI.md`, `CLAUDE.md`, `README.md`, `PRIVACY.md`), launcher scripts (`Setup_*`, `Quick_*`, `Smart_Organize.*`, `SmartDrive.*`), the 6 taxonomies, Windows folders (`WindowsApps`, `Program Files`, `DumpStack.log.tmp`), system-referenced folders (`protected_by_system`: Windows `PATH`, Services, Installed Apps, Startup, `.lnk` targets, uninstallers), game libraries (`SteamLibrary`, `Riot Games`, `Epic Games`, `XboxGames`, `GOG Galaxy`, `Battle.net`, `Ubisoft Game Launcher`, `EA Games`, `HoYoPlay`, `Genshin Impact`, `LDPlayer`), active SQL Server databases (`Microsoft SQL Server 2022`), and `smart-drive-os` are permanently protected.
+
+---
+
+## Snapshots and Backup
+
+- **SHA-256 Snapshots (`smart-drive snapshot`)**: Streaming 64 KB-chunk ($O(1)$ memory) point-in-time manifests in `.smart_drive/snapshots/<name>.json` to detect bit rot or tampering.
+- **Incremental Backup (`smart-drive backup`)**: Copies modified/new files while excluding OS junk. Default coverage: `02_Learning_Knowledge`, `03_Development_Projects`, `05_Dev_Toolbox` (override with `--partitions`); hidden dirs (`.git`, `.github`, `.vscode`) are skipped unless `--include-hidden` is passed, and every run lists what was not covered.
+- **Duplicates (`smart-drive dup`) & Git Clones (`smart-drive repos`)**: 3-phase SHA-256 duplicate finder (hard links counted once; `node_modules`, virtualenvs, caches and installed apps are never scanned) and read-only Git clone auditor checking SSD-vs-machine **mirrors** (`commit`, `push`, `pull`, `fetch to compare`) and same-drive **duplicates** (newest commit to keep, redundant same-branch copies, or `git worktree` with `--relative-paths` on git 2.48+; dirty/unpushed/stashed clones are blocked from removal).
+
+---
+
+## Workstation Hybrid and C-Drive Offload
+
+`FilesystemAdapter` and `DriveDetectorBackend` adapt between **exFAT 512 KB** (slack guard, anti-symlink rules, Spotlight/FSEvents shields) and **NTFS 4 KB** (4,096-byte math, `fsutil` TRIM check, `C:` cache offload). `smart-drive offload` migrates heavy caches (HuggingFace, Ollama, PyTorch, Docker WSL2, pip, uv, npm, Conda, Gradle, Cargo) from `C:` to `<target>\04_System_Offload_Caches\<name>` on your secondary drive (`D:`, `E:`, …) in a **7-phase transactional workflow** with running-process detection (`--wait`, `--force`), rollback safety, and unprivileged NTFS Directory Junctions (`mklink /J`). See [README_INTERNAL.md](README_INTERNAL.md).
+
+<details>
+<summary>AcademicClassifier (FPTU), Non-Code Routing & AutoZoner Self-Defense</summary>
+
+- **AcademicClassifier (FPTU)**: Extracts course codes (`DBI202`, `WED201c`, `SWE202c`, `PRN211`, `PRJ301`, `OSG`), detects exams/labs (`PE`, `de thi`, `on luyen`, `lab1_sp26`, `sp26`, `fa25`, `su25`), zones into `02_Learning_Knowledge/FPTU/Ky_1/` .. `Ky_7/`, and repairs ZIP mojibake (`h?c k? 3 fptu` $\rightarrow$ `Hoc_Ky_3_fptu`, `n luy?n pe dbi202` $\rightarrow$ `On_Luyen_pe_dbi202`, `k 1 fptu` $\rightarrow$ `Ky_1_fptu`, `dich truyen` $\rightarrow$ `Dich_Truyen`).
+- **Non-Code Routing**: `dich truyen` $\rightarrow$ `02_Learning_Knowledge/Personal_Books/dich truyen`, `lenovo` $\rightarrow$ `05_Dev_Toolbox/OEM_Drivers/LENOVO`, `sql2022` $\rightarrow$ `05_Dev_Toolbox/Installers/SQL2022`.
+- **AutoZoner Self-Defense & System Reference Guard (`protected_by_system`)**: Anchors `_CURRENT_FILE` through `_SMART_DRIVE_REPO_DIR` and ancestors so `smart-drive-os` never moves itself; pre-filters Windows folders (`WindowsApps`, `Program Files`, `Program Files (x86)`, `$Recycle.Bin`, `System Volume Information`, `WpSystem`, `DeliveryOptimization`, `WUDownloadCache`, `DumpStack.log.tmp`), folders referenced by Windows `PATH`, Services, Installed Apps (`Uninstall` registry), Startup (`Run`), `.lnk` shortcuts, folders with `unins000.exe`/`uninstall.exe`, game libraries (`SteamLibrary`, `Riot Games`, `Epic Games`, `XboxGames`, `GOG Galaxy`, `Battle.net`, `Ubisoft Game Launcher`, `EA Games`, `HoYoPlay`, `Genshin Impact`, `LDPlayer`, `fo4`, `32837`, `Downloads`), and active SQL Server (`MSSQL16.MSSQLSERVER`, `MSSQLSERVER`, `MSSQL`).
+
+</details>
+
+---
+
+## Launchers
+
+All 24 portable launchers reside in both the repo root and `launchers/` (zero Git required):
+
+| Workflow | Windows CMD | PowerShell | macOS App | Linux/POSIX | Purpose |
+|---|---|---|---|---|---|
+| **Drive Setup** | `Setup_SSD.bat` | `Setup_SSD.ps1` | `Setup_SSD.command` | `Setup_SSD.sh` | Interactive 1-touch initialization & profile selector |
+| **Quick Search** | `Quick_Search.bat` | `Quick_Search.ps1` | `Quick_Search.command` | `Quick_Search.sh` | Instant interactive SQLite FTS5 search prompt |
+| **Quick Clean** | `Quick_Clean.bat` | `Quick_Clean.ps1` | `Quick_Clean.command` | `Quick_Clean.sh` | Dry-run junk preview followed by confirmed Tier 1 deletion |
+| **Quick Audit** | `Quick_Audit.bat` | `Quick_Audit.ps1` | `Quick_Audit.command` | `Quick_Audit.sh` | Instant storage breakdown and cluster slack audit |
+| **Safe Guided Organizer** | `Smart_Organize.bat` | `Smart_Organize.ps1` | `Smart_Organize.command` | `Smart_Organize.sh` | Step-by-step dry-run preview, busy-app wait, `YES` confirmation, post-move verification, and 1-key `U` undo (EN/VI) |
+| **Interactive Menu** | `SmartDrive.bat` | `SmartDrive.ps1` | `SmartDrive.command` | `SmartDrive.sh` | Full interactive TUI menu (including `[8]` Relink Agents after hand moves, `[9]` Checkup, `[10]` Safe Guided Organizer, `[11]` Relink to the latest move) |
+
+`smart-drive self-path-check` checks the running Python environment (venv, pyenv, user scripts) and prints the PowerShell `SetEnvironmentVariable`, `~/.bashrc`/`~/.zshrc` export, or `pyenv rehash` command if `smart-drive` is not on `PATH`.
+
+---
+
+## Profiles
+
+| Profile | Target Architecture | Included Taxonomies & Subdirectories |
+|---|---|---|
+| **`workstation-hybrid`** *(Recommended)* | Your secondary drive (`D:`, `E:`, …) with games, apps, coursework | `01_AI_Models`, `02_Learning_Knowledge` (`FPTU/`, `Personal_Books/`, `Notes/`), `03_Development_Projects` (`active/`, `archive/`), `04_System_Workspaces`, `05_Dev_Toolbox` (`OEM_Drivers/`, `Installers/`, `scripts/`), `06_Archives_Storage` |
+| **`internal-developer-vault`** | Internal NVMe/SATA SSD (`D:`, `E:`, …) for offloaded `C:` caches | `01_AI_Models`, `02_Development_Workspaces`, `03_Data_Vault`, `04_System_Offload_Caches` (`huggingface/`, `ollama/`, `pip/`, `uv/`), `05_Dev_Toolbox`, `06_Archives_Storage` |
+| **`ai-developer`** | External SSD for LLMs, fine-tuning, AI agents | `01_AI_Models` (`checkpoints/`, `gguf/`, `safetensors/`, `datasets/`), `02_Learning_Knowledge`, `03_Development_Projects` (`ai_agents/`), `04_System_Workspaces`, `05_Dev_Toolbox`, `06_Archives_Storage` |
+| **`data-science`** | Data engineering, pipelines, EDA notebooks | `01_AI_Models`, `02_Learning_Knowledge`, `03_Development_Projects` (`notebooks/`, `data_raw/`, `pipelines/`), `04_System_Workspaces`, `05_Dev_Toolbox`, `06_Archives_Storage` |
+| **`general-workspace`** *(Default)* | Universal code, docs, notes, utilities | Standard 6 taxonomies with `Notes/`, `References/`, `active/`, `archive/`, `scripts/` |
+
+---
+
+## Testing
+
+1,150+ automated tests run in CI on Windows, macOS and Linux with Python 3.9 and 3.13 using `unittest`:
+
+```bash
+python -m unittest discover tests -v
+```
+
+Coverage spans gitignore governance (ownership, intentional build outputs, negations, keep lists, `gh` visibility, secret variable names, CRLF preservation, staged-change guard), atomic learning units, system reference protection (`protected_by_system`), agent/IDE/Obsidian/shortcut relinking (`storage.json`, `state.vscdb`, `recentProjects.xml`, `.lnk`, MSIX Claude desktop, `--find`, `--wait`), `undo`, `checkup`, `paths --broken`, `clean` quarantine/restore, HTML treemap audit, `Smart_Organize` (`SD_SELFTEST=1`), cluster geometry (512 B–32 MB), self-defense, and `AcademicClassifier`.
+
+---
+
+## Privacy, Security & Data Isolation
+
+SmartDrive-OS is engineered with a **local-first, zero-trust** architecture:
+- **100% Local-Only Operations**: All scanning, SQLite FTS5 indexing, and SHA-256 snapshotting run exclusively on local storage.
+- **Zero Telemetry & Zero PII Logging**: No analytics, network beacons, or harvesting of file contents/secrets; only basic metadata is stored in `.smart_drive/index.db`.
+- **Air-Gap Ready & Defensive Safeguards**: Zero external pip dependencies (`dependencies = []`), local `stdio` MCP transport, offline `setup --no-clone`, mandatory dry-run cleanup defaults, and an inviolable whitelist (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `README.md`, `PRIVACY.md`).
+
+For full details and compliance specifications, read [PRIVACY.md](PRIVACY.md).
+
+---
+
+## Contributing & License
+
+- 🌟 **Star & Fork** on GitHub: [DuongNAD/smart-drive-os](https://github.com/DuongNAD/smart-drive-os) · 🐛 [GitHub Issues](https://github.com/DuongNAD/smart-drive-os/issues) · 🔀 [Pull Requests](https://github.com/DuongNAD/smart-drive-os/pulls) · 📖 [CONTRIBUTING.md](CONTRIBUTING.md)
+- 📄 Licensed under the **MIT License** — see [LICENSE](LICENSE).