From 55ba6d4b4dfcdda95d50ac905006812ccee45644 Mon Sep 17 00:00:00 2001
From: David Ibia <david.ibia@boxmarshall.com>
Date: Thu, 15 Jan 2026 21:34:07 +0100
Subject: [PATCH] Improve README with quick reference table, utility docs, and
 clarifications

- Add quick reference table for all CLI commands
- Document non-standard env file support (api.env, database.env, etc.)
- Document auto-quoting behavior for special characters
- Add isExampleEnvFile utility to library API docs
- Expand example file detection patterns in notes
---
 README.md | 36 ++++++++++++++++++++++++++++++++++--
 1 file changed, 34 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 75df325..d524124 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,25 @@ The pepper file is created with mode `0600` when possible, and `.envsitter/` is
 
 ## CLI usage
 
-Commands:
+### Quick reference
+
+| Command | Description |
+|---------|-------------|
+| `keys` | List all keys in an env file |
+| `fingerprint` | Get deterministic fingerprint for a key |
+| `match` | Match candidate value(s) against key(s) |
+| `match-by-key` | Bulk match candidates by key |
+| `scan` | Detect value shapes (JWT, URL, base64) |
+| `validate` | Check dotenv syntax |
+| `copy` | Copy keys between env files |
+| `format` / `reorder` | Sort and organize env files |
+| `annotate` | Add comments to keys |
+| `add` | Add new key (fails if exists) |
+| `set` | Create or update key |
+| `unset` | Set key to empty value |
+| `delete` | Remove key(s) from file |
+
+### Commands
 
 - `keys --file <path> [--filter-regex <re>]`
 - `fingerprint --file <path> --key <KEY>`
@@ -70,7 +88,9 @@ Notes for file operations:
 
 - Commands that modify files (`copy`, `format`/`reorder`, `annotate`, `add`, `set`, `unset`, `delete`) are dry-run unless `--write` is provided.
 - These commands never print secret values; output includes keys, booleans, and line numbers only.
-- When targeting example files (`.env.example`, `.env.sample`, `.env.template`), a warning is emitted. Use `--no-example-warning` to suppress.
+- When targeting example files (`.env.example`, `.env.sample`, `.env.template`, `.env.dist`, `.env.default`), a warning is emitted. Use `--no-example-warning` to suppress.
+- Non-standard env file names are fully supported (e.g., `api.env`, `database.env`, `config.env.local`).
+- Values with special characters (spaces, `#`, quotes, newlines) are automatically double-quoted with proper escaping.
 
 ### List keys
 
@@ -335,6 +355,18 @@ await unsetEnvFileKey({ file: '.env', key: 'OLD_KEY', write: true });
 await deleteEnvFileKeys({ file: '.env', keys: ['DEPRECATED', 'UNUSED'], write: true });
 ```
 
+### Utility functions
+
+```ts
+import { isExampleEnvFile } from 'envsitter';
+
+// Detect example/template env files
+isExampleEnvFile('.env.example');      // true
+isExampleEnvFile('api.env.sample');    // true
+isExampleEnvFile('.env');              // false
+isExampleEnvFile('api.env');           // false
+```
+
 ### Match operators via the library
 
 ```ts