docs: enhance export-metrics.js documentation

- Added comprehensive header comment explaining use case
- Documents data source (session.json from audit-logs)
- CSV output format and use cases clearly described
- Includes usage examples and note about raw data access
- Removes need for separate docs/ folder in repo

Docs were design artifacts, not needed in open source repo.
All relevant documentation now lives in code comments.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

scripts/export-metrics.js

@@ -1,15 +1,40 @@
 #!/usr/bin/env node
 
 /**
- * Export Metrics Script
+ * Export Metrics to CSV
  *
- * Export session metrics from audit logs to CSV format for analysis.
+ * Converts session.json from audit-logs into CSV format for spreadsheet analysis.
  *
- * Use Cases:
+ * DATA SOURCE:
- * - Performance analysis across sessions
+ * - Reads from: audit-logs/{hostname}_{sessionId}/session.json
- * - Cost tracking and budgeting
+ * - Source of truth for all metrics, timing, and cost data
- * - Agent success rate analysis
+ * - Automatically created by Shannon during agent execution
- * - Benchmarking improvements
+ *
+ * CSV OUTPUT:
+ * - One row per agent with: agent, phase, status, attempts, duration_ms, cost_usd
+ * - Perfect for importing into Excel/Google Sheets for analysis
+ *
+ * USE CASES:
+ * - Compare performance across multiple sessions
+ * - Track costs and optimize budget
+ * - Identify slow agents for optimization
+ * - Generate charts and visualizations
+ * - Export data for external reporting tools
+ *
+ * EXAMPLES:
+ * ```bash
+ * # Export to stdout
+ * ./scripts/export-metrics.js --session-id abc123
+ *
+ * # Export to file
+ * ./scripts/export-metrics.js --session-id abc123 --output metrics.csv
+ *
+ * # Find session ID from Shannon store
+ * cat .shannon-store.json | jq '.sessions | keys'
+ * ```
+ *
+ * NOTE: For raw metrics, just read audit-logs/.../session.json directly.
+ * This script only exists to provide a spreadsheet-friendly CSV format.
  */
 
 import chalk from 'chalk';