feat(docs): document history trends command and add chart example

- Add trend analysis section and CLI examples to README
- Add `history trends` command docs with metrics/options and image export notes
- Include trends example image asset and switch logo to raw GitHub URL
- Add `viz` extra (matplotlib) and update lockfile dependencies

Author: akhundMurad

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/logo-ascii.png" alt="Pacta" width="400">
+  <img src="https://raw.githubusercontent.com/akhundMurad/pacta/main/assets/logo-ascii.png" alt="Pacta" width="400">
 </p>
 
 <p align="center">
@@ -46,6 +46,7 @@ Codebases rot. The "clean architecture" you designed becomes spaghetti after a f
 - **Baseline mode** — fail only on *new* violations, not legacy debt
 - **Snapshots** — version your architecture like code
 - **History tracking** — view architecture evolution over time
+- **Trend analysis** — track violations, nodes, edges over time with charts
 
 ## Quick example
 
@@ -121,10 +122,20 @@ a1b2c3d4  2025-01-22  abc1234  main    42 nodes  87 edges  2 violations (latest)
 e5f6g7h8  2025-01-20  def5678  main    42 nodes  85 edges  4 violations
 ...
 
+# View trends over time
+$ pacta history trends . --metric violations
+
+# Export chart as image (requires pacta[viz])
+$ pacta history trends . --output trends.png
+
 # Export for external tools
 pacta history export --format json > history.json
 ```
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/akhundMurad/pacta/main/assets/trends-example.png" alt="Trends Chart" width="600">
+</p>
+
 ## Docs
 
 - [CLI Reference](https://akhundmurad.github.io/pacta/cli/)
@@ -135,6 +146,7 @@ pacta history export --format json > history.json
 
 - [x] Open-source CLI and analysis engine
 - [x] Content-addressed snapshots with history tracking
+- [x] Trend analysis with chart export
 - [ ] Architecture visualization (Mermaid, D2)
 - [ ] Health metrics (drift score, instability)
 - [ ] Proprietary hosted service with:

assets/trends-example.png

@@ -206,6 +206,95 @@ pacta history export . -o export.json
 }
 ```
 
+## history trends
+
+Show metric trends over time with ASCII charts or export as images.
+
+```bash
+pacta history trends [PATH] [OPTIONS]
+```
+
+**Options:**
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--metric {violations,nodes,edges,density}` | `violations` | Metric to track |
+| `--last N` | - | Show only last N entries |
+| `--since DATE` | - | Show entries since date (ISO-8601) |
+| `--branch NAME` | - | Filter by branch name |
+| `--width N` | `60` | Chart width in characters |
+| `--format {text,json}` | `text` | Output format |
+| `-o, --output FILE` | - | Export chart as image (PNG/SVG) |
+
+**Metrics:**
+
+| Metric | Description |
+|--------|-------------|
+| `violations` | Total violation count (default) |
+| `nodes` | Architecture component count |
+| `edges` | Dependency count |
+| `density` | Coupling ratio (edges/nodes) |
+
+**Examples:**
+
+```bash
+# Show violation trends (default)
+pacta history trends .
+
+# Show node count trends
+pacta history trends . --metric nodes
+
+# Show density trends (edges/nodes ratio)
+pacta history trends . --metric density
+
+# Filter by branch and limit
+pacta history trends . --branch main --last 10
+
+# JSON output for scripting
+pacta history trends . --format json
+
+# Export as PNG image (requires pacta[viz])
+pacta history trends . --output trends.png
+
+# Export as SVG for docs/presentations
+pacta history trends . --metric violations --output violations.svg
+```
+
+**Image Export:**
+
+To export charts as images, install the visualization extras:
+
+```bash
+pip install pacta[viz]
+```
+
+This adds matplotlib support for PNG, SVG, and PDF export.
+
+![Trends Example](https://raw.githubusercontent.com/akhundMurad/pacta/main/assets/trends-example.png)
+
+**Example output:**
+
+```
+Violations Trend (5 entries)
+============================
+
+  5 |      *
+  4 |  *       *
+  3 |              *
+  2 |                  *
+  1 |
+  0 |
+    +--------------------
+      Jan 15      Jan 22
+
+Trend: Improving (-3 over period)
+First: 4 violations (Jan 15)
+Last:  2 violations (Jan 22)
+
+Average: 3 violations
+Min: 2, Max: 5
+```
+
 ## Exit Codes
 
 | Code | Meaning |