docs: add USAGE.md — reading guide and how to use findings (#1518)

USAGE.md

@@ -0,0 +1,78 @@
+# Usage Guide
+
+How to use the Timmy Time Dashboard repository for research, auditing, and improvement of the Hermes Agent system.
+
+## What This Repository Is
+
+This is an **analysis and documentation** repository. It contains the results of an empirical audit of the Hermes Agent system — 10,985 sessions analyzed, 82,645 error log lines processed, 2,160 errors categorized.
+
+There is no application to run. The value is in the documentation.
+
+## Reading Guide
+
+Start here, in order:
+
+1. **README.md** — overview and key findings. Read this first to understand the 5 root causes of agent failure and the 15 proposed solutions.
+
+2. **hermes-agent-architecture-report.md** — deep dive into the system architecture. Covers session management, cron infrastructure, tool execution, and the gateway layer.
+
+3. **failure_root_causes.md** — detailed breakdown of every error pattern found, with examples and frequency data.
+
+4. **complete_test_report.md** — what testing was done and what it revealed.
+
+5. **experiment-framework.md** — methodology for reproducing the audit.
+
+6. **experiment_log.md** — step-by-step log of experiments conducted.
+
+## Using the Findings
+
+### For Developers
+
+The 15 issues identified in the audit are prioritized in `IMPLEMENTATION_GUIDE.md`:
+
+- **P1 (Critical):** Circuit breaker, token tracking, gateway config — fix these first
+- **P2 (Important):** Path validation, syntax validation, tool fixation detection
+- **P3 (Beneficial):** Session management, memory tool, model routing
+
+Each issue includes implementation patterns with code snippets.
+
+### For Researchers
+
+The data supports reproducible research:
+
+- `results/experiment_data.json` — raw experimental data
+- `paper_outline.md` — academic paper structure
+- `paper/main.tex` — LaTeX paper draft
+
+### For Operators
+
+If you run a Hermes Agent deployment:
+
+- Check `failure_root_causes.md` for error patterns you might be hitting
+- Use the circuit breaker pattern from `IMPLEMENTATION_GUIDE.md`
+- Monitor for the 5 root cause categories in your logs
+
+## Key Numbers
+
+| Metric | Value |
+|--------|-------|
+| Sessions analyzed | 10,985 |
+| Error log lines | 82,645 |
+| Total errors | 2,160 |
+| Error rate | 9.4% |
+| Empty sessions | 3,564 (32.4%) |
+| Error cascade factor | 2.33x |
+| Dead cron jobs | 9 |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute findings, corrections, or new analysis.
+
+## Related Repositories
+
+- [hermes-agent](https://github.com/nousresearch/hermes-agent) — the system being analyzed
+- [timmy-config](https://forge.alexanderwhitestone.com/Rockachopa/timmy-config) — Timmy's sovereign configuration
+
+---
+
+*Sovereignty and service always.*