yowtf 0.1.0 → 0.1.1

package/README.md

@@ -1,1605 +1,355 @@
 <p align="center">
-  <img src="images/white-logo.png" alt="YOWTF — Your Operating Workstation Trouble Finder" width="500">
+  <img src="images/white-logo.png" alt="YOWTF — Your Operating Workstation Trouble Finder" width="460">
 </p>
 
 <p align="center">
- <strong>Your Operating Workstation Trouble Finder
+  <strong>A local-first, read-only developer workstation and project health diagnostic CLI.</strong><br>
+  <em>"Yo, WTF is happening?"</em>
 </p>
 
-> **Yo, WTF is happening?**
-
-YOWTF is a **local-first, read-only developer workstation and project health diagnostic CLI**.
-
-It looks at your machine, development environment, project configuration, runtimes, tools, ports, dependencies, Git state, storage, and other developer-facing signals — then explains what may be wrong, why it matters, and where to look next.
-
-No telemetry.  
-No cloud dashboard.  
-No AI required.  
-No automatic fixes.  
-No modifying your project.
-
-Just run it.
-
-```bash
-yowtf
-```
-
----
-
-## Why YOWTF?
-
-Every developer eventually hits one of these:
-
-- "Why is Node using the wrong version?"
-- "Why is this port already occupied?"
-- "Why does this project work on my machine but not theirs?"
-- "Why is my disk suddenly full?"
-- "Which Node/Python/Git installation is actually being used?"
-- "Why does this command work in one terminal but not another?"
-- "Why is this project using a different package manager?"
-- "Why did this build suddenly become painfully slow?"
-- "What the hell is wrong with this machine?"
-
-Usually, the answer is buried somewhere between:
-
-```text
-PATH
-environment variables
-runtime versions
-duplicate installations
-ports
-processes
-disk usage
-project configuration
-dependency metadata
-lockfiles
-Git state
-developer caches
-```
-
-YOWTF brings those signals together into one deterministic diagnostic workflow.
-
----
-
-# ✨ What YOWTF Does
-
-YOWTF follows a structured diagnostic pipeline:
-
-```text
-DISCOVER
-   ↓
-COLLECT
-   ↓
-DETECT
-   ↓
-EVALUATE
-   ↓
-SCORE
-   ↓
-EXPLAIN
-   ↓
-REPORT
-```
-
-It doesn't just dump system information.
-
-It turns collected evidence into **findings**.
-
-Each finding can contain:
-
-- rule ID
-- category
-- status
-- severity
-- confidence
-- explanation
-- evidence
-- impact
-- remediation hint
-
-The goal is simple:
-
-> **Don't just tell the developer what exists. Tell them what deserves attention and why.**
-
----
-
-# 🚀 Features
-
-## 🖥️ Workstation Diagnostics
-
-Inspect developer-facing system health:
-
-- operating system
-- architecture
-- memory
-- CPU pressure
-- uptime
-- disk space
-- developer storage
-
----
-
-## ⚙️ Process Diagnostics
-
-Identify potentially problematic development processes:
-
-- high CPU processes
-- high memory processes
-- zombie/defunct processes where supported
-- suspicious duplicate development processes
-
-YOWTF **never kills processes**.
-
----
-
-## 🔌 Port Diagnostics
-
-Understand what is listening on your machine:
-
-- development port conflicts
-- duplicate listeners
-- unexpected development-service exposure
-- ports whose owning process cannot be identified
-
-YOWTF does not terminate anything.
-
----
-
-## 🌐 Network Diagnostics
-
-Inspect local network configuration relevant to development:
-
-- network interface availability
-- DNS configuration
-- proxy configuration
-- route information
-
-YOWTF does not require a remote monitoring service.
-
----
-
-## 🔐 Environment Diagnostics
-
-Inspect environment metadata without dumping sensitive values.
-
-Examples:
-
-- empty PATH entries
-- duplicate PATH entries
-- shell/PATH mismatches
-- suspicious secret-like environment variable names
-
-### Privacy by default
-
-YOWTF does **not** need to print:
-
-```text
-API_KEY=...
-DATABASE_PASSWORD=...
-TOKEN=...
-SECRET=...
-```
-
-When environment inspection is required, YOWTF works primarily with **names and metadata**, not secret values.
-
----
-
-## 🧩 Runtime Diagnostics
-
-Detect runtime-related problems across applicable projects:
-
-- Node.js
-- Python
-- Java
-- other supported runtime contexts defined by the V1 rule set
-
-Examples:
-
-```text
-runtime.version.mismatch
-runtime.node.unpinned
-runtime.python.unpinned
-```
-
----
-
-## 🛠️ Developer Tool Diagnostics
-
-Inspect important developer tooling:
-
-- Git
-- package managers
-- Docker when relevant
-- executable resolution
-- tool conflicts
-
-This is particularly useful when your machine has accumulated multiple installations over time.
-
----
-
-## 🛣️ PATH Diagnostics
-
-PATH problems are classic developer-machine problems.
-
-YOWTF can identify:
-
-- missing expected executables
-- multiple executable installations
-- invalid PATH entries
-- PATH-order shadowing
-
-For example:
-
-```text
-node
- ├── C:\Program Files\nodejs\node.exe
- └── C:\Users\you\AppData\Roaming\npm\node.exe
-```
-
-If PATH ordering means the wrong executable wins, YOWTF can surface that relationship.
-
----
-
-## 📦 Project Diagnostics
-
-YOWTF can inspect a project for issues involving:
-
-- project manifests
-- lockfiles
-- runtime policies
-- project-root ambiguity
-- package-manager expectations
-- environment configuration
-
-Run against the current directory:
-
-```bash
-yowtf project
-```
-
-Or explicitly target another directory:
-
-```bash
-yowtf --path ./my-project project
-```
-
----
-
-## 📚 Dependency Diagnostics
-
-YOWTF can detect problems such as:
-
-- missing lockfiles
-- dependency metadata mismatches
-- package-manager mismatches
-- inconsistent local dependency state
-
-YOWTF does **not** reinstall dependencies for you.
-
----
-
-## 🌿 Git Diagnostics
-
-Inspect local Git state:
-
-- repository availability
-- dirty working tree
-- untracked files
-- branch divergence
-
-YOWTF does not:
-
-```text
-commit
-reset
-stash
-checkout
-pull
-push
-```
-
-It observes.
-
----
-
-## 🧹 Cache & Storage Diagnostics
-
-Find developer storage pressure caused by recognized:
-
-- caches
-- build artifacts
-- dependency-related directories
-- other supported developer storage locations
-
-The `clean` command is intentionally diagnostic.
-
-It helps you decide what is safe to review.
-
-It does **not** silently delete things.
-
----
-
-# 📊 Health Score
-
-YOWTF produces a health score from:
-
-```text
-0 → 100
-```
-
-Higher is better.
-
-The V1 scoring model starts at:
-
-```text
-100
-```
-
-and applies penalties based on finding severity.
-
-| Severity | Penalty |
-| -------- | ------: |
-| CRITICAL |      25 |
-| HIGH     |      15 |
-| MEDIUM   |       8 |
-| LOW      |       3 |
-| INFO     |       0 |
-
-A `FAIL` finding receives its full severity penalty.
-
-A `WARN` finding receives 50% of its severity penalty.
-
-`PASS`, `SKIPPED`, `UNAVAILABLE`, and `ERROR` findings do not directly reduce the score.
-
-The score is clamped to:
-
-```text
-0–100
-```
-
-### Score bands
-
-|  Score | Health       |
-| -----: | ------------ |
-| 90–100 | 🟢 EXCELLENT |
-|  75–89 | GOOD         |
-|  60–74 | FAIR         |
-|  40–59 | POOR         |
-|   0–39 | CRITICAL     |
-
-### Important
-
-The score is **not** a security rating.
-
-It is a deterministic diagnostic health indicator for the scope YOWTF evaluated.
-
-Coverage and score are separate concepts.
-
-A partial scan may still have a valid score for its evaluated scope.
-
----
-
-# 🔎 Findings
-
-A typical diagnostic finding is conceptually represented as:
-
-```text
-Rule
- ├── ID
- ├── Category
- ├── Status
- ├── Severity
- ├── Confidence
- ├── Title
- ├── Summary
- ├── Evidence
- ├── Impact
- └── Remediation Hint
-```
-
-Example:
-
-```text
-[HIGH] runtime.version.mismatch
-
-Node.js 18.x is active, but the project requires Node.js >=20.
-
-Why it matters:
-The project may fail to build or behave differently from
-environments using the required runtime.
-
-What to do:
-Use the project's documented Node.js version.
-```
-
-The exact terminal presentation is defined by the CLI/reporting specifications.
-
----
-
-# 🧠 Deterministic by Design
-
-YOWTF does not ask an AI model:
-
-> "Does this machine look healthy?"
-
-The diagnostic engine uses explicit rules.
-
-That means the same evidence should produce the same result.
-
-```text
-Evidence
-   ↓
-Rule
-   ↓
-Finding
-   ↓
-Score
-```
-
-No hidden model.
-
-No probabilistic health score.
-
-No remote recommendation engine.
-
----
-
-# 🔒 Privacy
-
-YOWTF is designed around data minimization.
-
-### By default
-
-YOWTF:
-
-- runs locally
-- does not require an account
-- does not require a backend
-- does not send telemetry
-- does not upload scan results
-- does not require a cloud dashboard
-- does not intentionally expose environment secret values
-
-### YOWTF does not silently collect:
-
-```text
-telemetry
-analytics
-usage tracking
-cloud diagnostics
-remote machine inventory
-```
-
-The product is intentionally local-first.
-
----
-
-# 🧱 Read-Only by Default
-
-YOWTF is a diagnostic tool, not a repair tool.
-
-It does not automatically:
-
-```text
-delete files
-install software
-uninstall software
-modify PATH
-modify environment variables
-kill processes
-modify project files
-modify dependencies
-modify Git state
-commit changes
-reset repositories
-```
-
-If YOWTF tells you:
-
-```text
-Your cache is huge.
-```
-
-it doesn't immediately delete the cache.
-
-If it tells you:
-
-```text
-Your Node version is wrong.
-```
-
-it doesn't change your Node installation.
-
-You stay in control.
-
----
-
-# 🌍 Cross-Platform
-
-YOWTF is designed for multi-platform developer workstations:
-
-- **Windows** (native PowerShell and cmd command execution)
-- **macOS** (Darwin process and system introspection)
-- **Linux** (POSIX and `/proc`-compatible metric gathering)
-
-Not every operating system exposes identical diagnostic APIs or system utilities. YOWTF therefore distinguishes between:
-
-```text
-PASS         Condition verified healthy
-FAIL         Definite issue identified
-WARN         Condition requires developer attention
-SKIPPED      Diagnostic not applicable to this project or platform
-UNAVAILABLE  Platform metric or tool not available in this environment
-ERROR        Unexpected internal error during individual rule evaluation
-```
-
-An unavailable platform capability is never treated as an execution failure. On unsupported platforms (e.g. BSD or Solaris), YOWTF gracefully skips platform-specific collectors and executes generic project diagnostics safely.
-
----
-
-# 📦 Installation
-
-YOWTF is distributed through npm.
-
-### Run instantly with npx
-
-You can run YOWTF without installing it globally:
-
-```bash
-npx yowtf
-```
-
-### Or install globally
-
-With npm:
-
-```bash
-npm install -g yowtf
-```
-
-Or with pnpm:
-
-```bash
-pnpm add -g yowtf
-```
-
-> **Note:** Public npm publication will occur in Phase 11. Until published to the npm registry, you can clone and run YOWTF locally from source (see [Development](#-development)).
-
-Check the installed version:
-
-```bash
-yowtf --version
-```
-
----
-
-# ⚡ Quick Start
-
-From a project directory:
-
-```bash
-yowtf
-```
-
-For the full health-oriented diagnostic workflow:
-
-```bash
-yowtf doctor
-```
-
-Check the score:
-
-```bash
-yowtf score
-```
-
-Understand the findings:
-
-```bash
-yowtf explain
-```
-
-Inspect a specific area:
-
-```bash
-yowtf runtimes
-yowtf ports
-yowtf processes
-yowtf env
-yowtf git
-yowtf deps
-```
-
----
-
-# 🧰 Commands
-
-YOWTF V1 exposes 20 canonical entry points (default full scan + 19 focused subcommands):
-
-```text
-yowtf
-yowtf doctor
-yowtf score
-yowtf explain
-
-yowtf system
-yowtf disk
-yowtf processes
-yowtf ports
-yowtf network
-yowtf env
-yowtf runtimes
-yowtf tools
-yowtf paths
-yowtf versions
-
-yowtf project
-yowtf deps
-yowtf git
-yowtf config
-
-yowtf caches
-yowtf clean
-```
-
----
-
-# 📖 Command Overview
-
-| Command           | Category    | Purpose                                                                              |
-| :---------------- | :---------- | :----------------------------------------------------------------------------------- |
-| `yowtf`           | Core        | Full workstation and project diagnostic scan                                         |
-| `yowtf doctor`    | Core        | Health-oriented diagnostic scan highlighting issues requiring attention              |
-| `yowtf score`     | Core        | Calculate and display the 0–100 workstation/project health score                     |
-| `yowtf explain`   | Core        | Provide detailed explanations and next steps for detected findings                   |
-| `yowtf system`    | Workstation | Inspect OS, CPU architecture, memory pressure, and system uptime                     |
-| `yowtf disk`      | Workstation | Inspect disk space, storage pressure, and volume limits                              |
-| `yowtf processes` | Workstation | Detect process resource hogs and duplicate dev processes (read-only)                 |
-| `yowtf ports`     | Workstation | Detect development port conflicts and listening sockets (read-only)                  |
-| `yowtf network`   | Workstation | Inspect network interfaces, DNS configuration, and proxy settings                    |
-| `yowtf env`       | Environment | Inspect environment variables, PATH entries, and configuration metadata safely       |
-| `yowtf runtimes`  | Environment | Inspect installed and active runtimes (Node.js, Python, Java, etc.)                  |
-| `yowtf tools`     | Environment | Inspect developer tools (Git, package managers, Docker, etc.)                        |
-| `yowtf paths`     | Environment | Detect PATH-order shadowing, empty entries, and executable conflicts                 |
-| `yowtf versions`  | Environment | Diagnose version conflicts and requirement mismatches                                |
-| `yowtf project`   | Project     | Diagnose project type, manifest health, and configuration                            |
-| `yowtf deps`      | Project     | Diagnose project dependency health, lockfiles, and package manager consistency       |
-| `yowtf git`       | Project     | Inspect Git repository health, branch status, and working tree (read-only)           |
-| `yowtf config`    | Project     | Inspect project configuration files and environment definitions                      |
-| `yowtf caches`    | Maintenance | Identify developer caches and large storage consumers (read-only)                    |
-| `yowtf clean`     | Maintenance | Diagnostic cleanup candidate finder; `--preview` reports candidates without deleting |
-
-> **Important:** `yowtf clean` (and `yowtf clean --preview`) is **strictly diagnostic**. It reports identified cleanup candidates and estimated sizes. It **never deletes any files**.
-
----
-
-# 🎛️ Global Options
-
-All commands support the documented global options:
-
-| Option          | Purpose          | Description                                                                 |
-| :-------------- | :--------------- | :-------------------------------------------------------------------------- |
-| `-h, --help`    | Help             | Display help and usage information for YOWTF or a subcommand                |
-| `-V, --version` | Version          | Display current version number                                              |
-| `--verbose`     | Verbose mode     | Enable detailed diagnostic output (without exposing secrets)                |
-| `--no-color`    | Color toggle     | Disable ANSI terminal colors for raw text pipelines                         |
-| `--json`        | Machine output   | Output pure machine-readable JSON (suppresses spinners and decorations)     |
-| `--quiet`       | Quiet mode       | Reduce output noise; show only essential findings and summaries             |
-| `--path <dir>`  | Target directory | Target a specific project directory (defaults to current working directory) |
-
-### Examples
-
-JSON output:
-
-```bash
-yowtf --json
-```
-
-Verbose output:
-
-```bash
-yowtf --verbose
-```
-
-Disable colors:
-
-```bash
-yowtf --no-color
-```
-
-Quiet mode:
-
-```bash
-yowtf --quiet
-```
-
-Analyze another project:
-
-```bash
-yowtf --path ./some-project
-```
-
----
-
-# 🤖 JSON Output
-
-YOWTF supports pure machine-readable output:
-
-```bash
-yowtf --json
-```
-
-When `--json` is enabled:
-
-- Interactive spinners and progress bars are disabled.
-- ANSI color formatting sequences are suppressed.
-- Informational banners and decoration are omitted.
-- The output can be piped directly to tools like `jq` or captured by CI automation.
-
----
-
-# 🚦 Exit Codes
-
-YOWTF defines strict, predictable exit code semantics:
-
-| Exit Code | Classification          | Meaning                                                                                                                           |
-| :-------: | :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
-|    `0`    | **Success**             | Successful command execution. Findings with `FAIL`, `WARN`, or `PASS` status are valid diagnostic results and exit with code `0`. |
-|    `1`    | **Application Failure** | Internal or fatal application error preventing completion of the diagnostic run.                                                  |
-|    `2`    | **CLI Usage Error**     | Unknown command, unrecognized option, missing required argument, or inaccessible project directory path.                          |
-
----
-
-# 🧪 Example Workflow
-
-Imagine a project requiring Node.js 20.
-
-Your machine resolves:
-
-```text
-Node.js 18.20.x
-```
-
-YOWTF might identify:
-
-```text
-runtime.version.mismatch
-```
-
-and explain:
-
-```text
-Project requirement:
-Node.js >= 20
-
-Resolved runtime:
-Node.js 18.20.x
-
-Impact:
-The project may fail to build or behave differently
-from environments using the required runtime.
-```
-
-Instead of blindly changing your environment, YOWTF gives you enough evidence to investigate.
-
----
-
-# 🧩 V1 Rule Catalogue
-
-YOWTF V1 defines **60 diagnostic rules** across 15 categories.
-
-```text
-System
-Disk
-Processes
-Ports
-Network
-Environment
-Runtimes
-Tools
-Paths
-Versions
-Project
-Dependencies
-Git
-Configuration
-Caches
-```
-
-Examples include:
-
-```text
-system.memory.pressure
-disk.space.low
-process.resource.hog
-port.development.conflict
-environment.path.empty-entry
-runtime.node.unpinned
-tool.executable.shadowing
-path.order.shadowing
-version.runtime.conflict
-project.lockfile.missing
-dependency.lockfile.mismatch
-git.working-tree.dirty
-config.required.value.missing
-cache.storage.large
-```
-
-The complete authoritative rule inventory is maintained in:
-
-```text
-docs/RULE-CATALOGUE.md
-```
-
----
-
-# 🏗️ Architecture
-
-YOWTF is structured as a layered diagnostic system.
-
-```text
-┌──────────────────────────────┐
-│             CLI              │
-├──────────────────────────────┤
-│        Application           │
-├──────────────────────────────┤
-│           Domain             │
-├──────────────────────────────┤
-│         Collection           │
-├──────────────────────────────┤
-│          Platform            │
-├──────────────────────────────┤
-│         Detection            │
-├──────────────────────────────┤
-│          Scoring             │
-├──────────────────────────────┤
-│         Reporting            │
-└──────────────────────────────┘
-```
-
-The conceptual flow is:
-
-```text
-Discover
-   ↓
-Collect
-   ↓
-Detect
-   ↓
-Evaluate
-   ↓
-Score
-   ↓
-Explain
-   ↓
-Report
-```
-
-The architecture is designed so that:
-
-- collectors collect evidence
-- rules evaluate evidence
-- scoring calculates health
-- reporting renders results
-- CLI handles user interaction
-
-These concerns remain separated.
-
----
-
-# 🛠️ Technology
-
-YOWTF V1 uses:
-
-- Node.js 20+
-- TypeScript
-- pnpm
-- Commander
-- Chalk
-- Ora
-- Boxen
-- cli-table3
-- tsup
-- Vitest
-- ESLint
-- Prettier
-- Git
-- GitHub Actions
-- npm
-
-The project intentionally does **not** require:
-
-- a database
-- a backend
-- a frontend framework
-- a cloud service
-- an AI service
-- telemetry infrastructure
-- a mandatory network service
+<p align="center">
+  <a href="https://github.com/isthatpratham/yowtf/actions/workflows/ci.yml"><img src="https://github.com/isthatpratham/yowtf/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
+  <a href="https://www.npmjs.com/package/yowtf"><img src="https://img.shields.io/npm/v/yowtf.svg" alt="npm version"></a>
+  <a href="https://github.com/isthatpratham/yowtf/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen" alt="Node >= 20.0.0">
+</p>
 
 ---
 
-# 📁 Project Structure
-
-The implementation follows the architecture specification.
-
-Conceptually:
-
-```text
-yowtf/
-├── docs/
-│   ├── PRD.md
-│   ├── ARCHITECTURE.md
-│   ├── TECH-STACK.md
-│   ├── CLI-SPEC.md
-│   ├── DETECTION-ENGINE.md
-│   ├── SCORING.md
-│   ├── COMMANDS.md
-│   └── RULE-CATALOGUE.md
-│
-├── src/
-│   ├── cli/
-│   ├── application/
-│   ├── domain/
-│   ├── collection/
-│   ├── platform/
-│   ├── detection/
-│   ├── scoring/
-│   └── reporting/
-│
-├── tests/
-├── package.json
-├── tsconfig.json
-├── tsup.config.ts
-└── README.md
-```
-
-The exact implementation structure is governed by:
+YOWTF inspects your developer machine, environment configuration, runtimes, tooling, ports, processes, dependencies, Git state, and storage pressure — then explains what may be wrong, why it matters, and where to look next.
 
-```text
-docs/ARCHITECTURE.md
-```
+- **Local-first**: runs entirely on your machine.
+- **Read-only**: observes and explains; never alters your files, system, or Git history.
+- **Deterministic**: explicit rules produce predictable results without probabilistic guessing or AI.
+- **Zero telemetry**: no analytics, no external tracking, no cloud dependencies.
+- **Private by default**: inspects configuration metadata; never dumps secret values.
 
 ---
 
-# 🔧 Troubleshooting
-
-### Unknown command or unrecognized option (Exit Code 2)
-
-```text
-error: unknown command 'foo'
-error: unknown option '--bar'
-```
-
-**Cause:** Typographical error in command or option name.  
-**Resolution:** Run `yowtf --help` to list all 20 valid commands, or `yowtf <command> --help` to inspect command-specific flags.
-
-### Invalid or inaccessible path (Exit Code 2)
-
-```text
-CLI Usage Error: Directory does not exist or is not accessible: ./non-existent-dir
-```
-
-**Cause:** The directory passed to `--path <dir>` does not exist or lacks read permissions.  
-**Resolution:** Verify the target directory path spelling and ensure your user account has read access.
-
-### Tool or runtime shows `UNAVAILABLE` or `SKIPPED`
-
-```text
-[SKIPPED] runtime.python.unpinned (Python not detected)
-```
-
-**Cause:** The specified runtime (e.g. Python, Java, Docker) is not installed or not present in your system `PATH`.  
-**Resolution:** This is normal diagnostic behavior. YOWTF never crashes when an optional tool is absent; it records the evidence as unavailable and skips dependent checks.
-
-### Permission or access issues during collection
-
-**Cause:** Certain system statistics (e.g. processes belonging to other users or privileged network sockets) may be restricted by the host OS.  
-**Resolution:** YOWTF runs without requiring root/administrator permissions. Restricted metrics are safely captured as `FAILED` or `UNAVAILABLE` collection evidence without halting the scan.
-
-### Scripting with JSON output
-
-**Cause:** Automated scripts encountering unexpected formatting in `--json` mode.  
-**Resolution:** When `--json` is supplied, all interactive spinners, ANSI color escape sequences, and decorative banners are suppressed. The stdout output is strictly valid JSON:
-
-```bash
-yowtf --json | jq .healthScore
-```
+## 🧭 Quick Navigation
 
-### Unsupported platform handling
-
-**Cause:** Executing YOWTF on an operating system outside Windows, macOS, or Linux (e.g. BSD or Solaris).  
-**Resolution:** YOWTF safely handles unsupported platforms by skipping platform-specific collectors and running generic project-level diagnostics.
+- [Quick Start](#-quick-start)
+- [What YOWTF Does](#-what-yowtf-does)
+- [What It Checks](#-what-it-checks)
+- [Scoring](#-scoring)
+- [Command Reference](#-command-reference)
+- [Global Options](#-global-options)
+- [Exit Codes](#-exit-codes)
+- [Safe by Design](#-safe-by-design)
+- [Example Output](#-example-output)
+- [Development](#-development)
+- [FAQ](#-faq)
+- [Project Links](#-project-links)
+- [License](#-license)
 
 ---
 
-# 🧪 Development
-
-### Prerequisites
-
-- **Node.js**: `>= 20.0.0`
-- **pnpm**: `>= 9.0.0`
-- **Git**
-
-### Setup
-
-Clone the repository and install dependencies:
+## ⚡ Quick Start
 
-```bash
-git clone https://github.com/isthatpratham/yowtf.git
-cd yowtf
-pnpm install
-```
-
-### Build & Run Locally
-
-Compile TypeScript with `tsup`:
+Run YOWTF instantly without global installation:
 
 ```bash
-pnpm run build
-node dist/cli.js --help
+npx yowtf
 ```
 
-To run continuously in watch mode:
+Or install globally:
 
 ```bash
-pnpm dev
+npm install -g yowtf
+# or
+pnpm add -g yowtf
 ```
 
-### Testing & Validation
-
-YOWTF enforces strict quality gates across testing, type safety, linting, and formatting:
+### Basic Commands
 
 ```bash
-# Run the complete test suite
-pnpm test
-
-# Run tests in interactive watch mode
-pnpm run test:watch
-
-# Verify TypeScript types without emitting
-pnpm run typecheck
-
-# Check code with ESLint
-pnpm run lint
+# Run full workstation and project diagnostic scan
+yowtf
 
-# Format code and verify formatting with Prettier
-pnpm run format
-pnpm run format:check
-```
+# Health-oriented diagnostic scan highlighting issues requiring attention
+yowtf doctor
 
-### Mandatory Quality Gates
+# Calculate and display workstation health score (0–100)
+yowtf score
 
-Before submitting any changes, ensure all 5 verification gates pass:
+# Deep explanation of detected findings (problem -> evidence -> impact -> next action)
+yowtf explain
 
-```bash
-pnpm test
-pnpm run typecheck
-pnpm run lint
-pnpm run format:check
-pnpm run build
+# Inspect specific categories
+yowtf system
+yowtf runtimes
+yowtf ports
+yowtf env
 ```
 
-For complete architectural rules, contribution workflows, and rule authoring guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
-
 ---
 
-# 🧬 Documentation
-
-The `/docs` directory is the project's technical source of truth.
-
-### Product
-
-```text
-docs/PRD.md
-```
-
-Defines what YOWTF is, why it exists, scope, goals, non-goals, and V1 definition of done.
-
-### Architecture
-
-```text
-docs/ARCHITECTURE.md
-```
-
-Defines system structure, layers, boundaries, data flow, and architectural invariants.
-
-### Technology
-
-```text
-docs/TECH-STACK.md
-```
-
-Defines the approved technology stack and dependency policy.
-
-### CLI
-
-```text
-docs/CLI-SPEC.md
-```
-
-Defines public CLI behavior.
-
-### Detection
-
-```text
-docs/DETECTION-ENGINE.md
-```
-
-Defines evidence, collectors, rules, findings, applicability, evaluation, and detection behavior.
-
-### Scoring
-
-```text
-docs/SCORING.md
-```
-
-Defines the numerical health-score model.
+## 🛠️ What YOWTF Does
 
-### Commands
+YOWTF executes a structured diagnostic pipeline:
 
 ```text
-docs/COMMANDS.md
+DISCOVER ──> COLLECT ──> DETECT ──> EVALUATE ──> SCORE ──> EXPLAIN ──> REPORT
 ```
 
-Defines the complete V1 command catalogue.
+1. **Discover**: Resolves the target workspace, identifies active project types, manifests, and platform capabilities.
+2. **Collect**: Gathers low-overhead, read-only evidence across workstation and project surfaces.
+3. **Detect**: Evaluates collected evidence against explicit, authoritative V1 diagnostic rules.
+4. **Evaluate**: Determines finding statuses (`PASS`, `WARN`, `FAIL`, `SKIPPED`, `UNAVAILABLE`, `ERROR`).
+5. **Score**: Calculates a deterministic health score from 0 to 100 based on finding severity.
+6. **Explain**: Correlates findings with underlying evidence, architectural impact, and concrete remediation hints.
+7. **Report**: Formats results for terminal presentation or machine-readable JSON.
 
-### Rules
+### Anatomy of a Diagnostic Finding
 
-```text
-docs/RULE-CATALOGUE.md
-```
-
-Defines the complete V1 diagnostic rule inventory.
-
----
-
-# 📜 Documentation Is the Source of Truth
-
-YOWTF follows a strict documentation-first development model.
-
-The hierarchy is:
+Every detected finding provides structured diagnostic context:
 
 ```text
-Specification
-    ↓
-Implementation
-    ↓
-Tests
-    ↓
-README
+Finding
+ ├── Rule ID         e.g. runtime.version.mismatch
+ ├── Category        e.g. runtimes
+ ├── Status          FAIL | WARN | PASS | SKIPPED | UNAVAILABLE | ERROR
+ ├── Severity        CRITICAL | HIGH | MEDIUM | LOW | INFO
+ ├── Confidence      HIGH | MEDIUM | LOW
+ ├── Title           Summary of the identified condition
+ ├── Evidence        Specific observations that triggered the rule
+ ├── Impact          Why this issue affects development or reliability
+ └── Remediation     Actionable next steps to investigate or resolve
 ```
 
-If implementation conflicts with the specification:
-
-> **The implementation is wrong.**
-
-If README conflicts with the specification:
-
-> **The README is wrong.**
-
-If two specifications conflict:
-
-> **Stop and resolve the conflict before implementation.**
-
-Undocumented behavior is not automatically approved behavior.
-
 ---
 
-# 🤖 AI Coding Agent Policy
+## 🔍 What It Checks
 
-YOWTF is designed to be friendly to AI-assisted development without allowing AI to silently define the product.
+YOWTF features **60 authoritative V1 diagnostic rules** across 15 developer-focused categories:
 
-AI coding agents must:
+| Category             | Scope       | Focus Area                                                                       |
+| -------------------- | ----------- | -------------------------------------------------------------------------------- |
+| **System**           | Workstation | OS architecture, CPU load, memory pressure, and system uptime                    |
+| **Disk**             | Workstation | Storage limits, volume capacity, and partition availability                      |
+| **Processes**        | Workstation | Resource hogs, zombie processes, and duplicate dev process instances             |
+| **Ports**            | Workstation | Port conflicts, duplicate listeners, and unexpected local server exposure        |
+| **Network**          | Workstation | Interface availability, DNS configuration, and active proxy settings             |
+| **Environment**      | Environment | PATH anomalies, duplicate entries, shell mismatches, and sensitive key names     |
+| **Runtimes**         | Environment | Node.js, Python, Java version alignment, unpinned runtimes, and version managers |
+| **Tools**            | Environment | Availability and conflict detection for Git, package managers, and Docker        |
+| **Paths**            | Environment | PATH-order shadowing, empty entries, and executable resolution conflicts         |
+| **Versions**         | Environment | Runtime requirement constraints vs. resolved system binaries                     |
+| **Project**          | Project     | Project manifests, workspace root ambiguity, and config consistency              |
+| **Dependencies**     | Project     | Lockfile health, package manager alignment, and dependency integrity             |
+| **Git**              | Project     | Repository state, detached HEAD, dirty working trees, and divergence             |
+| **Configuration**    | Project     | Project config files, lint/build setups, and environment definitions             |
+| **Caches & Storage** | Maintenance | Large developer caches (npm, pnpm, yarn, pip, cargo) and build artifacts         |
 
-- read the relevant documentation first
-- follow the documented architecture
-- use only documented commands
-- use only documented rules
-- use documented thresholds
-- preserve stable rule IDs
-- add tests
-- avoid undocumented dependencies
-- avoid undocumented network behavior
-- avoid undocumented mutations
-- avoid silent scope expansion
-
-The rule is simple:
-
-> **AI may implement the specification. AI does not become the specification.**
-
----
-
-# 🧪 Testing Philosophy
-
-Tests are part of the product contract.
-
-YOWTF tests should cover:
-
-- collectors
-- platform adapters
-- project discovery
-- rule evaluation
-- rule applicability
-- threshold boundaries
-- scoring
-- command behavior
-- output modes
-- error handling
-- privacy behavior
-- read-only guarantees
-- regression cases
-
-For threshold-based rules, boundary cases matter.
-
-For example:
-
-```text
-79.9%
-80.0%
-80.1%
-```
-
-should not accidentally produce the same result when the specification defines different outcomes.
+> **What YOWTF is NOT:** YOWTF is not an antivirus, firewall, full vulnerability scanner, system monitor, background daemon, process manager, or package manager. It is a targeted developer health diagnostic tool.
 
 ---
 
-# 🔐 Safety Philosophy
-
-YOWTF is deliberately conservative.
-
-When evidence is unavailable:
+## 📊 Scoring
 
-```text
-don't invent
-```
+YOWTF calculates an objective, deterministic health score between **0 and 100**.
 
-When applicability is uncertain:
-
-```text
-don't assume
-```
+- Starts at **100**.
+- Applies penalties based on finding severity:
 
-When a condition cannot be proven:
+| Severity     | Full Deduction (`FAIL`) | Partial Deduction (`WARN`) |
+| ------------ | ----------------------: | -------------------------: |
+| **CRITICAL** |                  25 pts |                   12.5 pts |
+| **HIGH**     |                  15 pts |                    7.5 pts |
+| **MEDIUM**   |                   8 pts |                    4.0 pts |
+| **LOW**      |                   3 pts |                    1.5 pts |
+| **INFO**     |                   0 pts |                    0.0 pts |
 
-```text
-don't claim certainty
-```
+`PASS`, `SKIPPED`, `UNAVAILABLE`, and `ERROR` findings do not deduct points. The score is clamped to the range `0–100`.
 
-When a repair could alter user state:
+### Health Score Bands
 
-```text
-don't perform it
-```
+| Score Range | Status Band      | Interpretation                                               |
+| ----------: | ---------------- | ------------------------------------------------------------ |
+|  **90–100** | 🟢 **EXCELLENT** | Workstation and project environment are in optimal condition |
+|   **75–89** | 🟡 **GOOD**      | Minor issues or warnings detected; development unaffected    |
+|   **60–74** | 🟠 **FAIR**      | Several warnings or moderate issues require attention        |
+|   **40–59** | 🔴 **POOR**      | Significant environmental conflicts or failures present      |
+|    **0–39** | 🚨 **CRITICAL**  | Severe issues detected; build or runtime failures likely     |
 
-This makes YOWTF useful as a diagnostic layer without turning it into an unpredictable system-management tool.
+_Note: The health score is a diagnostic metric for evaluated scope, not a security certification._
 
 ---
 
-# 🚫 What YOWTF Is Not
+## 🧰 Command Reference
 
-YOWTF is **not**:
+YOWTF provides 20 canonical public commands:
 
-- an antivirus
-- a full security scanner
-- a system monitor
-- a process manager
-- a package manager
-- a cloud observability platform
-- a telemetry platform
-- an automatic repair utility
-- an AI assistant
-- a remote monitoring service
+| Command           | Category    | Purpose                                                                              |
+| ----------------- | ----------- | ------------------------------------------------------------------------------------ |
+| `yowtf`           | Core        | Full workstation and project diagnostic scan                                         |
+| `yowtf doctor`    | Core        | Health-oriented diagnostic scan highlighting prioritized issues                      |
+| `yowtf score`     | Core        | Calculate and display the 0–100 workstation/project health score                     |
+| `yowtf explain`   | Core        | Deep explanation view (problem → evidence → impact → remediation)                    |
+| `yowtf system`    | Workstation | Inspect OS, CPU architecture, memory pressure, and system uptime                     |
+| `yowtf disk`      | Workstation | Inspect disk space, storage pressure, and volume limits                              |
+| `yowtf processes` | Workstation | Detect process resource hogs and duplicate dev processes (read-only)                 |
+| `yowtf ports`     | Workstation | Detect development port conflicts and listening sockets (read-only)                  |
+| `yowtf network`   | Workstation | Inspect network interfaces, DNS configuration, and proxy settings                    |
+| `yowtf env`       | Environment | Inspect environment variables, PATH entries, and configuration metadata              |
+| `yowtf runtimes`  | Environment | Inspect installed and active runtimes (Node.js, Python, Java, etc.)                  |
+| `yowtf tools`     | Environment | Inspect developer tools (Git, package managers, Docker, etc.)                        |
+| `yowtf paths`     | Environment | Detect PATH-order shadowing, empty entries, and executable conflicts                 |
+| `yowtf versions`  | Environment | Diagnose version conflicts and requirement mismatches                                |
+| `yowtf project`   | Project     | Diagnose project type, manifest health, and configuration                            |
+| `yowtf deps`      | Project     | Diagnose project dependency health, lockfiles, and package manager consistency       |
+| `yowtf git`       | Project     | Inspect Git repository health, branch status, and working tree (read-only)           |
+| `yowtf config`    | Project     | Inspect project configuration files and environment definitions                      |
+| `yowtf caches`    | Maintenance | Identify developer caches and large storage consumers (read-only)                    |
+| `yowtf clean`     | Maintenance | Diagnostic cleanup candidate finder; `--preview` reports candidates without deleting |
 
-It is a **developer workstation and project diagnostic tool**.
+> **Safety Notice on `clean`:** `yowtf clean` is strictly diagnostic. It reports identified cleanup candidates and estimated space reclamation. It **never deletes files or caches**.
 
 ---
 
-# 🌐 Network Philosophy
-
-YOWTF is local-first.
+## 🎛️ Global Options
 
-The V1 diagnostic engine does not depend on a cloud backend.
+The following global options are supported across all commands:
 
-Network-related diagnostics concern local configuration and developer-relevant network state where specified.
-
-YOWTF does not silently turn a local scan into a remote data-upload operation.
+| Option          | Purpose        | Description                                                                 |
+| --------------- | -------------- | --------------------------------------------------------------------------- |
+| `-h, --help`    | Help           | Display usage information for YOWTF or a specific subcommand                |
+| `-V, --version` | Version        | Display the current YOWTF version number                                    |
+| `--verbose`     | Verbosity      | Enable detailed diagnostic output including rule IDs and evidence keys      |
+| `--no-color`    | Formatting     | Disable ANSI terminal colors for plain-text logs and pipelines              |
+| `--json`        | Machine Output | Output pure machine-readable JSON (suppresses animations and banners)       |
+| `--quiet`       | Quiet Mode     | Show minimal summaries and essential failures only (suppresses animation)   |
+| `--path <dir>`  | Project Path   | Target a specific project directory (applies to project-scoped diagnostics) |
 
 ---
 
-# 🐳 Docker
-
-Docker is not a mandatory runtime dependency for YOWTF V1.
+## 🚦 Exit Codes
 
-Docker-related diagnostics may be applicable when a project explicitly uses Docker/container metadata.
+YOWTF adheres to strict, standard CLI exit codes:
 
-YOWTF does not require Docker merely to run.
+| Code  | Status                | Meaning                                                                                                                     |
+| :---: | --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
+| **0** | **Success**           | The command completed successfully. Finding statuses (`FAIL`, `WARN`, `PASS`) are valid diagnostic outputs and exit code 0. |
+| **1** | **Application Error** | Internal runtime error or fatal failure preventing diagnostic completion.                                                   |
+| **2** | **Usage Error**       | Unknown command, unrecognized option, missing required argument, or inaccessible project path.                              |
 
 ---
 
-# 🗺️ Roadmap
-
-The V1 foundation focuses on:
-
-```text
-Local diagnostics
-Read-only analysis
-Deterministic rules
-Cross-platform support
-Project health
-Workstation health
-Explainable findings
-Health scoring
-CLI usability
-```
-
-Future functionality may be considered independently, but new capabilities require explicit specification.
-
-Potential future areas may include:
+## 🛡️ Safe by Design
 
-- additional diagnostic rules
-- broader ecosystem detection
-- richer machine-readable output
-- expanded platform coverage
-- additional project ecosystem support
-- optional integrations
-
-Nothing becomes part of the product merely because it appears on a roadmap.
+- **Read-Only**: YOWTF observes and inspects. It never installs packages, uninstalls tools, terminates processes, alters environment files, or mutates Git state.
+- **No Automatic Fixes**: YOWTF explains root causes and remediation paths; you decide what changes to make.
+- **Zero Telemetry**: No tracking, analytics, crash reporting, or external API calls during standard scans.
+- **No Network Requirement**: Diagnostic scans evaluate local workstation state; no internet connection is required.
+- **Secrets Protection**: Environment analysis inspects variable names and metadata, never printing credential values.
+- **Cross-Platform**: Tailored adapters for Windows, macOS, and Linux with graceful degradation when a metric is unavailable.
 
 ---
 
-# 🤝 Contributing
-
-Contributions are welcome! Please review our detailed [CONTRIBUTING.md](CONTRIBUTING.md) guide before opening pull requests.
-
-Before changing the code:
-
-1. Read the relevant documentation.
-2. Understand the existing behavior.
-3. Identify the owning specification.
-4. Make the smallest appropriate change.
-5. Add/update tests.
-6. Run validation.
-7. Update documentation when behavior changes.
+## 💻 Example Output
 
-For a new diagnostic rule:
+When running in an interactive terminal, YOWTF initializes with a fast boot sequence:
 
 ```text
-Requirement
-   ↓
-RULE-CATALOGUE.md
-   ↓
-Detection implementation
-   ↓
-Tests
-   ↓
-Registration
-   ↓
-Command integration
-   ↓
-Validation
-```
-
-Do not add hidden rules.
+YOWTF // INITIALIZING
 
----
+> loading diagnostic engine...
+> preparing collectors...
+> preparing detection rules...
+> preparing reporting pipeline...
+> ready.
 
-# 📝 Commit Convention
+Yo, WTF is happening?
 
-The project follows Conventional Commits.
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│   Workstation Health Score: 85/100 (GOOD)                   │
+│   Total Deductions: 15 pts across 1 finding(s)               │
+│   Scope: workstation + project                              │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
 
-Examples:
+Findings:
+[FAIL] runtime.version.mismatch (HIGH) - 15 pts
+  Active Node.js v18.20.0 does not satisfy required >=20.0.0
+  Impact: Build scripts or tools relying on modern runtime APIs will fail.
+  Remediation: Switch to Node.js 20+ using your version manager (nvm use 20, fnm use 20).
 
-```text
-feat: add runtime diagnostics
-fix: correct PATH normalization
-docs: clarify scoring behavior
-test: add lockfile mismatch coverage
-refactor: simplify rule registry
-chore: update dependencies
+[PASS] git.repo.clean
+  Working tree is clean and branch is tracked.
 ```
 
-Release behavior follows the project's semantic-versioning configuration.
-
----
-
-# 📦 Release Philosophy
+In automated pipelines or scripts (`--json`), all presentation animations are bypassed to output pure JSON:
 
-YOWTF uses semantic versioning.
-
-In general:
-
-```text
-MAJOR → breaking changes
-MINOR → new compatible functionality
-PATCH → compatible fixes
+```bash
+yowtf --json | jq .score
 ```
 
-Rule IDs and documented behavior are treated as compatibility-sensitive surfaces.
-
----
-
-# 🧭 Design Principles
-
-YOWTF is built around a small set of principles:
-
-### Local-first
-
-Your machine is the primary source of diagnostic evidence.
-
-### Read-only
-
-Diagnose first. Let the developer decide what to change.
-
-### Deterministic
-
-The same evidence should produce the same result.
-
-### Evidence-based
-
-Findings should be explainable from collected evidence.
-
-### Privacy by default
-
-Collect the minimum information necessary.
-
-### Developer-oriented
-
-Focus on problems developers actually encounter.
-
-### No silent magic
-
-Undocumented behavior is not a feature.
-
 ---
 
-# 💬 Philosophy
-
-A developer workstation is an ecosystem.
-
-Over time it collects:
-
-```text
-runtimes
-tools
-PATH entries
-package managers
-dependencies
-caches
-ports
-processes
-environment variables
-configuration
-projects
-Git repositories
-```
-
-Eventually something breaks.
-
-And when it does, developers often start checking random things manually.
-
-YOWTF's job is to make that investigation structured.
-
-Not:
+## 🛠️ Development
 
-> "Here are 400 lines of system information. Good luck."
-
-But:
+### Prerequisites
 
-> **"Yo, WTF is happening?"**
+- Node.js >= 20.0.0
+- pnpm >= 9.0.0
 
-followed by:
+### Quality Gate Commands
 
-```text
-What was detected.
-Why it matters.
-How confident we are.
-What evidence supports it.
-Where you should look next.
-```
+```bash
+# Install dependencies
+pnpm install
 
----
+# Check code formatting
+pnpm run format:check
 
-# ⭐ Why the Name?
+# Lint codebase
+pnpm run lint
 
-Because sometimes developer tooling needs to say what everyone is already thinking.
+# Verify TypeScript types
+pnpm run typecheck
 
-**YOWTF**
+# Run test suite
+pnpm test
 
-**Your Operating Workstation Trouble Finder**
+# Build production bundle
+pnpm run build
 
-```text
-Yo, WTF is happening?
+# Verify npm package archive
+npm pack --dry-run
 ```
 
-Serious diagnostics.
-
-Questionable branding.
+For contributing guidelines and coding standards, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ---
 
-# License
-
-YOWTF is licensed under the MIT License.
+## ❓ FAQ
 
-See the [LICENSE](LICENSE) file for the full license text.
+**Q: Does YOWTF modify any files or settings on my machine?**  
+A: No. YOWTF is strictly read-only. It never modifies configurations, alters project manifests, or deletes caches.
 
----
+**Q: Does YOWTF use AI or large language models?**  
+A: No. YOWTF uses an explicit rule engine and deterministic scoring. The same environment state produces the exact same findings every time.
 
-# 🔗 Project
+**Q: Does YOWTF send my system information to the cloud?**  
+A: No. YOWTF has zero telemetry, zero analytics, and requires no external server or user account.
 
-GitHub:
+**Q: Can I use YOWTF in CI/CD workflows?**  
+A: Yes. Use `yowtf --json` to generate machine-readable output suitable for CI gates and scripting.
 
-https://github.com/isthatpratham/yowtf
+**Q: How fast is the startup boot animation?**  
+A: The boot sequence takes ~250–300ms in interactive terminals and is completely skipped in non-TTY environments (pipes, CI), `--json`, and `--quiet` modes.
 
 ---
 
-# 📚 Documentation Map
+## 🔗 Project Links
 
-```text
-README.md
-   │
-   ├── docs/PRD.md
-   │      Product requirements
-   │
-   ├── docs/ARCHITECTURE.md
-   │      System architecture
-   │
-   ├── docs/TECH-STACK.md
-   │      Technology contract
-   │
-   ├── docs/CLI-SPEC.md
-   │      CLI behavior
-   │
-   ├── docs/DETECTION-ENGINE.md
-   │      Detection architecture
-   │
-   ├── docs/SCORING.md
-   │      Health scoring
-   │
-   ├── docs/COMMANDS.md
-   │      Command catalogue
-   │
-   └── docs/RULE-CATALOGUE.md
-          V1 diagnostic rules
-```
+- **GitHub Repository**: [https://github.com/isthatpratham/yowtf](https://github.com/isthatpratham/yowtf)
+- **npm Package**: [https://www.npmjs.com/package/yowtf](https://www.npmjs.com/package/yowtf)
+- **Issue Tracker**: [https://github.com/isthatpratham/yowtf/issues](https://github.com/isthatpratham/yowtf/issues)
 
 ---
 
-# 🧠 Final Word
-
-YOWTF isn't trying to manage your machine.
-
-It isn't trying to replace your package manager.
-
-It isn't trying to be an antivirus.
-
-It isn't trying to upload your workstation to some dashboard.
-
-It simply asks:
-
-```text
-What is happening?
-What looks wrong?
-Why does it matter?
-How certain are we?
-What should I investigate?
-```
-
-And then gives you the evidence.
-
-```text
-┌─────────────────────────────────────┐
-│                                     │
-│       YOWTF                         │
-│       Your Operating Workstation    │
-│       Trouble Finder                │
-│                                     │
-│       Yo, WTF is happening?         │
-│                                     │
-└─────────────────────────────────────┘
-```
-
-**Local. Read-only. Deterministic. Developer-first.**
+## 📄 License
 
-That's YOWTF.
+YOWTF is open-source software licensed under the [MIT License](LICENSE).