feat: CLI with check/rules commands, formatters, integration tests

README.md

@@ -2,15 +2,52 @@
 
 > Lint CLAUDE.md and AI spec files — catches missing sections, secrets, and context bloat.
 
-**Status:** Under construction
+## Installation
 
-## What this does
+```bash
+npm install -g @unityinflow/spec-linter
+```
 
-spec-linter validates AI agent spec files (CLAUDE.md, GEMINI.md, GSD specs) for structural problems that silently degrade agent performance.
+Or run directly:
 
-## Installation
+```bash
+npx @unityinflow/spec-linter check CLAUDE.md
+```
+
+## Usage
+
+```bash
+# Lint a specific file
+spec-linter check CLAUDE.md
+
+# Lint all spec files in current directory
+spec-linter check .
+
+# JSON output for CI
+spec-linter check CLAUDE.md --format json
+
+# Only show errors
+spec-linter check CLAUDE.md --quiet
+
+# List available rules
+spec-linter rules
+```
+
+## Rules
+
+| ID | Name | Severity | Description |
+|---|---|---|---|
+| S001 | required-sections | error | Must have: Project Overview, Constraints, Acceptance Criteria |
+| S003 | no-secrets | error | No API keys, tokens, or private keys |
+| S004 | file-size | warning | >30kb warns, >50kb errors (context bloat) |
+| S005 | no-wildcard-permissions | error | No `Bash(*:*)` or `"*"` in tool permissions |
+| S006 | no-duplicate-headers | warning | No duplicate section headings at same level |
+
+## Exit Codes
 
-Coming soon — `npm install -g @unityinflow/spec-linter`
+- `0` — all checks passed
+- `1` — errors found
+- `2` — warnings only
 
 ## License