From 70258ddcbd65e288cf4e6e524078c0f340f7a961 Mon Sep 17 00:00:00 2001
From: 44r0n7 <44r0n7+gitea@pm.me>
Date: Wed, 31 Dec 2025 22:54:37 -0500
Subject: [PATCH] Update README with user and developer guides

---
 README.md | 119 +++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 87 insertions(+), 32 deletions(-)

diff --git a/README.md b/README.md
index 993aa1c..61de3af 100644
--- a/README.md
+++ b/README.md
@@ -1,61 +1,66 @@
 # Vid-Repair
 
-Vid-Repair is a cross‑platform Rust CLI that scans video files for container/stream/decode problems and applies safe repairs using system `ffmpeg`/`ffprobe`.
+Vid-Repair is a cross‑platform CLI that scans video files for container/stream/decode problems and applies safe repairs using your system `ffmpeg`/`ffprobe`.
 
-## Features
+## Quick Start (Regular Users)
 
-- Scan: ffprobe metadata + ffmpeg decode pass
-- Data‑driven rulesets (TOML) with linting
-- Safe fix planning (remux/faststart) + optional aggressive re‑encode
-- Atomic replace + optional keep‑original
-- Watch mode with settle window
-- Text output by default, JSON with schema version
-
-## Requirements
+### Requirements
 
 - `ffmpeg` and `ffprobe` available on PATH
 
-## Install
+### Install
 
 ```bash
 cargo build --release
 ```
 
-## Usage
+### Common commands
 
 ```bash
-# Scan
+# Scan files or folders
 vid-repair scan /path/to/videos
 
-# Scan and watch for new files
+# Watch a folder and scan new/changed files once they finish writing
 vid-repair scan --watch /path/to/videos
 
-# Scan depth (quick|standard|deep)
-vid-repair scan --scan-depth quick /path/to/videos
-
-# Disable recursive scanning
-vid-repair scan --no-recursive /path/to/videos
-
 # Fix (safe policy, in-place)
 vid-repair fix /path/to/videos
 
-# Fix with aggressive policy
+# Fix with aggressive policy (allows re-encode)
 vid-repair fix --policy aggressive /path/to/videos
 
-# JSON output
+# JSON output (for scripts)
 vid-repair scan --json /path/to/videos
-
-# Lint rulesets
-vid-repair rules lint
 ```
 
-Exit codes:
+### Scan depth
+
+```bash
+# Quick scan (faster, less thorough)
+vid-repair scan --scan-depth quick /path/to/videos
+
+# Standard scan
+vid-repair scan --scan-depth standard /path/to/videos
+
+# Deep scan (default, full decode)
+vid-repair scan --scan-depth deep /path/to/videos
+```
+
+### Recursive vs non‑recursive
+
+```bash
+# Disable recursive scanning
+vid-repair scan --no-recursive /path/to/videos
+```
+
+### Exit codes
+
 - `0` no issues
 - `1` issues found
 - `2` fix failed
 - `3` fatal error
 
-## Config
+## Config (Regular Users)
 
 On first run, a commented TOML config is created in the XDG config directory:
 
@@ -63,16 +68,66 @@ On first run, a commented TOML config is created in the XDG config directory:
 - macOS: `~/Library/Application Support/vid-repair/config.toml`
 - Windows: `%APPDATA%/vid-repair/config.toml`
 
-CLI flags override config values.
+You can edit this file to set defaults like scan depth, include/exclude patterns, and watch behavior. CLI flags always override config values.
 
-## Rulesets
+## Rulesets (Regular Users)
 
-Rules are stored in `rulesets/*.toml`. Use `vid-repair rules lint` before shipping changes.
+Rulesets tell Vid‑Repair how to interpret ffmpeg error messages. They’re shipped with the app and already work out of the box.  
+You generally **do not need to edit them** unless you want to add your own rules or tune behavior.
 
-## Fixtures
+If you do edit rulesets, run the linter:
 
-Generate fixtures (git‑ignored) with:
+```bash
+vid-repair rules lint
+```
+
+## Fixtures (Regular Users)
+
+Fixtures are small, generated test videos used to validate the scanner.  
+**You only need this if you are developing or testing changes.**
+
+If you want to generate them manually:
 
 ```bash
 scripts/generate_fixtures.sh
 ```
+
+---
+
+# Developer Guide
+
+This section is for contributors and anyone building on the project.
+
+## Project layout
+
+- `vid-repair/` – CLI binary
+- `vid-repair-core/` – core library (scan, rules, fix, report, watch)
+- `rulesets/` – modular rule packs (TOML)
+- `scripts/` – helper scripts (fixtures, checks)
+
+## Rulesets (Dev)
+
+Rules are data‑driven and split by domain in `rulesets/*.toml`.  
+Before shipping changes:
+
+```bash
+vid-repair rules lint
+```
+
+## Fixtures (Dev)
+
+Generate fixtures locally (git‑ignored):
+
+```bash
+scripts/generate_fixtures.sh
+```
+
+Use fixtures to validate scan logic and rule coverage. Add new fixtures for real‑world edge cases (truncated files, corrupted NAL units, etc.).
+
+## Tests
+
+```bash
+scripts/check.sh
+```
+
+This runs the full test suite and ruleset lint.