docs: update README with usage, JSON output, shell completions

- Fix shell completion generation (PersistentPreRunE was breaking
  subcommands like 'completion' and 'version')
- Add comprehensive usage examples for text and JSON output
- Document installation methods (go install, install.sh, releases)
- Add shell completion instructions for bash, zsh, and fish
- Update feature list with JSON output and cross-platform binaries

Author: ga1az

README.md

@@ -1,77 +1,186 @@
 # PathDigest
 
-PathDigest is a command-line tool written in Go that analyzes Git repositories, local directories, or individual files and generates a structured, LLM-friendly text digest of their content. This digest can be easily used as context for Large Language Models (LLMs) in tools like Cursor, VSCode, Gemini, and others.
+PathDigest is a command-line tool written in Go that analyzes Git repositories, local directories, or individual files and generates a structured, LLM-friendly text digest of their content. The digest can be used as context for Large Language Models (LLMs) in tools like Cursor, VSCode, Gemini, and others.
 
 Inspired by web-based tools like [gitingest](https://github.com/cyclotruc/gitingest) by @cyclotruc, PathDigest brings similar powerful code-to-context capabilities directly to your terminal as a native, efficient binary.
 
-> I made this tool for my own use, but I thought it might be useful for others.
+> I made this tool for my own use, but I thought it might be useful to others.
 
 ## Installation
 
-### Via `go install` (Recommended if you have Go installed)
+### Via `go install` (requires Go 1.23+)
 
-Make sure you have Go (1.20 or higher recommended) installed and `$HOME/go/bin` (or `$GOPATH/bin`) is in your `PATH`.
+Make sure `$HOME/go/bin` (or `$GOPATH/bin`) is in your `PATH`.
 
 ```bash
 go install github.com/ga1az/pathdigest@latest
 ```
 
-### Via `install.sh` (Recommended if you don't have Go installed)
+### Via install script (macOS & Linux)
 
 ```bash
+# Install to default directory ($GOPATH/bin or ./bin)
 curl -sSfL https://raw.githubusercontent.com/ga1az/pathdigest/main/install.sh | sh -s
 
 # Install to a specific directory
 curl -sSfL https://raw.githubusercontent.com/ga1az/pathdigest/main/install.sh | sh -s -- -b /usr/local/bin
+
+# Install a specific version
+curl -sSfL https://raw.githubusercontent.com/ga1az/pathdigest/main/install.sh | sh -s -- v0.2.0
+```
+
+### Via GitHub Releases
+
+Download the binary for your platform from [github.com/ga1az/pathdigest/releases](https://github.com/ga1az/pathdigest/releases).
+
+```bash
+# macOS (Apple Silicon)
+curl -sL https://github.com/ga1az/pathdigest/releases/latest/download/pathdigest_0.0.0_darwin_arm64.tar.gz | tar xz
+chmod +x pathdigest
+mv pathdigest /usr/local/bin/
+
+# macOS (Intel)
+curl -sL https://github.com/ga1az/pathdigest/releases/latest/download/pathdigest_0.0.0_darwin_amd64.tar.gz | tar xz
+chmod +x pathdigest
+mv pathdigest /usr/local/bin/
+
+# Linux (amd64)
+curl -sL https://github.com/ga1az/pathdigest/releases/latest/download/pathdigest_0.0.0_linux_amd64.tar.gz | tar xz
+chmod +x pathdigest
+mv pathdigest /usr/local/bin/
+
+# Linux (arm64)
+curl -sL https://github.com/ga1az/pathdigest/releases/latest/download/pathdigest_0.0.0_linux_arm64.tar.gz | tar xz
+chmod +x pathdigest
+mv pathdigest /usr/local/bin/
 ```
 
 ## Usage
 
+### Basic
+
 ```bash
-pathdigest <source>
+# Digest a local directory (outputs to pathdigest_digest.txt by default)
+pathdigest ./my-project
 
-//Git URL
+# Digest a Git repository URL
 pathdigest https://github.com/ga1az/pathdigest
 
-//Local Directory
-pathdigest ./projects/pathdigest -o pathdigest_digest.txt
+# Output to stdout (useful for piping)
+pathdigest ./my-project -o -
+
+# Output to a specific file
+pathdigest ./my-project -o digest.txt
 ```
 
-## Features
+### JSON Output
 
-*   **Versatile Source Input**: Process Git repository URLs (cloning specific branches/commits if needed), local directories, or single files.
-*   **Structured Output**: Generates a clear text output including:
-    *   A summary of the processed source.
-    *   A tree-like representation of the directory structure.
-    *   Concatenated content of all processed text files.
-*   **Customizable Filtering**:
-    *   Use glob patterns to exclude specific files or directories (e.g., `*.log`, `node_modules/`).
-    *   Use glob patterns to explicitly include files or directories, overriding exclusion rules.
-*   **File Size Control**: Set a maximum file size to skip very large files, keeping the context manageable.
-*   **Git Integration**:
-    *   Specify a branch or commit hash when providing a Git URL.
-    *   Handles different Git URL formats (HTTPS, SSH, slugs).
-*   **Go-Powered**: Built with Go for fast performance and easy cross-platform binary creation.
+Use `--format json` (or `-f json`) for structured output that tools and scripts can consume:
+
+```bash
+# JSON to file
+pathdigest ./my-project -f json -o digest.json
 
+# JSON to stdout
+pathdigest ./my-project -f json -o -
 
-Output will be a json file (In progress) or txt file that can be used as a context for cursor, vscode, gemini, etc.
+# Default text format (unchanged behavior)
+pathdigest ./my-project
+```
 
-### Flags
+The JSON output includes:
+- `summary` — source path, file count, total size, patterns used
+- `tree` — nested directory structure with names, paths, types, sizes
+- `files` — flat array of all processed files with content
+- `git_info` — repository metadata when processing a Git URL
 
-*   `-o, --output <file_path>`: Specifies the output file path for the digest. Defaults to `pathdigest_digest.txt`. Use `-` to print to standard output.
-*   `-s, --max-size <bytes>`: Maximum file size in bytes to process (e.g., `10485760` for 10MB). Defaults to 10MB.
-*   `-e, --exclude-pattern <pattern>`: Glob pattern to exclude files/directories. Can be used multiple times. Adds to a list of default exclude patterns (e.g., `.git/`, `node_modules/`).
-*   `-i, --include-pattern <pattern>`: Glob pattern to include files/directories. Can be used multiple times. If include patterns are provided, only files matching these patterns will be processed (overriding excludes if a path matches both).
-*   `-b, --branch <branch_name>`: Specifies the branch to clone and ingest if the source is a Git URL. Can also be a commit hash.
+### Filtering
 
-To see all available flags and default values:
 ```bash
-pathdigest --help
+# Exclude additional patterns (adds to built-in defaults)
+pathdigest ./my-project -e "*.test.ts" -e "coverage/"
+
+# Include only specific patterns (overrides excludes)
+pathdigest ./my-project -i "*.go" -i "go.mod"
+
+# Limit max file size (default: 10MB)
+pathdigest ./my-project -s 1048576  # 1MB limit
 ```
 
-### Build Binary
+### Git Integration
 
 ```bash
-go build ./cmd/pathdigest
+# Clone and digest a specific branch
+pathdigest https://github.com/user/repo -b develop
+
+# Digest a specific path within a repo
+pathdigest https://github.com/user/repo/tree/main/internal/pkg
+```
+
+### All Flags
+
+```
+Flags:
+  -b, --branch string             Branch to clone and ingest (if source is a Git URL)
+  -e, --exclude-pattern strings   Glob patterns to exclude (adds to defaults)
+  -f, --format string             Output format: text or json (default "text")
+  -h, --help                      Help for pathdigest
+  -i, --include-pattern strings   Glob patterns to include (overrides excludes)
+  -s, --max-size int              Maximum file size in bytes (default 10485760)
+  -o, --output string             Output file path (default "pathdigest_digest.txt")
+```
+
+## Shell Completions
+
+PathDigest supports autocompletion for **bash**, **zsh**, and **fish**.
+
+### Bash
+
+```bash
+# Generate and load completions
+pathdigest completion bash > ~/.config/pathdigest/completion.bash
+echo 'source ~/.config/pathdigest/completion.bash' >> ~/.bashrc
+
+# Or if you use bash-completion (recommended)
+pathdigest completion bash > $(brew --prefix)/etc/bash_completion.d/pathdigest  # macOS
+pathdigest completion bash > /etc/bash_completion.d/pathdigest                  # Linux
+```
+
+### Zsh
+
+```bash
+# Generate completions to your fpath
+pathdigest completion zsh > "${fpath[1]}/_pathdigest"
+
+# Or manually:
+mkdir -p ~/.zfunc
+pathdigest completion zsh > ~/.zfunc/_pathdigest
+
+# Make sure ~/.zfunc is in your fpath in ~/.zshrc:
+# fpath+=~/.zfunc
+# autoload -U compinit && compinit
 ```
 
+### Fish
+
+```bash
+pathdigest completion fish > ~/.config/fish/completions/pathdigest.fish
+```
+
+## Features
+
+- **Versatile Source Input** — Process Git repository URLs (cloning specific branches/commits), local directories, or single files.
+- **Text & JSON Output** — Default text format for human consumption, JSON format (`-f json`) for tools and scripts.
+- **Smart Filtering** — Built-in exclude patterns for common noise (`.git/`, `node_modules/`, `build/`, etc.) plus custom glob patterns.
+- **Git Integration** — Specify branches, commits, and sub-paths when providing a Git URL.
+- **File Size Control** — Set a maximum file size to skip very large files.
+- **Cross-Platform** — Pre-built binaries for macOS, Linux, and Windows (amd64 and arm64).
+- **Shell Completions** — Autocompletion for bash, zsh, and fish.
+
+## Build from Source
+
+```bash
+git clone https://github.com/ga1az/pathdigest.git
+cd pathdigest
+go build ./cmd/pathdigest
+```

cmd/root.go

@@ -41,9 +41,18 @@ You can specify a local path or a repository URL as the source.`,
 	Args:    cobra.ExactArgs(1),
 	Version: appVersion,
 	PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+		// Only parse exclude patterns when running the root command
+		if !cmd.Flags().Changed("exclude-pattern") && !cmd.HasFlags() {
+			return nil
+		}
+		if !cmd.Flags().HasAvailableFlags() {
+			return nil
+		}
+
 		userExcludePatterns, err := cmd.Flags().GetStringSlice("exclude-pattern")
 		if err != nil {
-			return fmt.Errorf("error parsing exclude patterns: %w", err)
+			// Flag doesn't exist for this subcommand (e.g. completion, version) — skip
+			return nil
 		}
 
 		finalExcludesSet := make(map[string]struct{})