docs: add metrics documentation and new CLI commands

- Add --status and --metrics-reset to CLI options table
- Add comprehensive Metrics section documenting:
  - Viewing metrics with --status command
  - Resetting metrics with --metrics-reset command
  - All tracked metrics fields and descriptions
  - Cost estimation for different AI model providers
  - Tips for using metrics effectively
- Update Directory Structure to include metrics.json file
- Add example output showing metrics display format
- Add confirmation prompt example for safe reset

Signed-off-by: leocavalcante <leo@cavalcante.dev>

Author: leocavalcante

README.md

@@ -129,6 +129,11 @@ opencoder -P anthropic/claude-opus-4 -B anthropic/claude-sonnet-4
 | `-B, --build-model MODEL` | Model for build phase |
 | `-p, --project DIR` | Project directory (default: current directory) |
 | `-v, --verbose` | Enable verbose logging |
+| `--status` | Display metrics summary and exit (no model required) |
+| `--metrics-reset` | Reset all metrics to default values (requires confirmation) |
+| `--no-auto-commit` | Disable automatic commits after tasks |
+| `--no-auto-push` | Disable automatic push after cycles |
+| `-s, --signoff` | Add Signed-off-by line to commits (DCO) |
 | `-h, --help` | Show help message |
 | `-V, --version` | Show version |
 
@@ -210,6 +215,7 @@ OpenCoder creates a `.opencode/opencoder/` directory in your project:
 └── opencoder/
     ├── config.json              # Configuration file
     ├── state.json               # Current state (JSON)
+    ├── metrics.json             # Performance metrics and statistics
     ├── current_plan.md          # Active task plan
     ├── ideas/                   # Drop .md files here to queue tasks
     │   ├── feature-x.md
@@ -302,6 +308,117 @@ The AI prioritizes based on:
 - **No naming convention** - Any `.md` filename works
 - **Auto-cleanup** - Empty/invalid ideas are automatically deleted
 
+## Metrics
+
+OpenCoder automatically tracks detailed metrics about your development sessions, including cycles, tasks, token usage, and estimated costs. Monitor your progress and efficiency with built-in metrics commands.
+
+### Viewing Metrics
+
+Display a summary of all tracked metrics without starting the loop:
+
+```bash
+opencoder --status
+
+# With a specific project
+opencoder --status -p ./myproject
+```
+
+This displays:
+- **Cycles**: Total completed and timed out
+- **Tasks**: Completed, failed, and skipped
+- **Retries**: Total retry attempts across all operations
+- **Ideas**: Number of queued ideas processed
+- **Token Usage**: Input and output tokens consumed
+- **Estimated Cost**: Approximate API costs incurred
+- **Duration**: Average cycle duration
+- **Activity**: Timestamp of last activity
+
+Example output:
+```
+OpenCoder Metrics
+=================
+
+Cycles: 5 completed, 0 timed out
+Tasks: 42 completed, 2 failed, 0 skipped
+Success rate: 95.5%
+Retries: 3 total
+Ideas: 1 processed
+Avg cycle duration: 1m 0s
+Tokens: 50.0K in, 25.0K out
+Estimated cost: $1.50
+
+Last activity: 2026-01-18T17:30:00Z
+```
+
+### Resetting Metrics
+
+Reset all metrics to default values with confirmation:
+
+```bash
+opencoder --metrics-reset
+
+# With a specific project
+opencoder --metrics-reset -p ./myproject
+```
+
+This command:
+1. Displays your current metrics
+2. Asks for confirmation before proceeding
+3. Resets all counters to zero (preserves timestamps)
+4. Confirms successful reset
+
+The confirmation prompt helps prevent accidental data loss:
+```
+Current Metrics:
+================
+
+Cycles: 5 completed, 0 timed out
+Tasks: 42 completed, 2 failed, 0 skipped
+...
+
+Are you sure you want to reset all metrics to default values? (yes/no): no
+Metrics reset cancelled.
+```
+
+### Tracked Metrics
+
+OpenCoder tracks the following metrics:
+
+| Metric | Description |
+|--------|-------------|
+| **cyclesCompleted** | Number of complete plan-build-eval cycles |
+| **cyclesTimedOut** | Number of cycles that exceeded the timeout limit |
+| **tasksCompleted** | Number of tasks successfully completed |
+| **tasksFailed** | Number of tasks that failed after max retries |
+| **tasksSkipped** | Number of tasks skipped due to timeout |
+| **totalRetries** | Total retry attempts across all operations |
+| **ideasProcessed** | Number of ideas from the queue that were processed |
+| **totalInputTokens** | Cumulative input tokens consumed from API |
+| **totalOutputTokens** | Cumulative output tokens generated by API |
+| **totalCostUsd** | Estimated total cost of all API calls in USD |
+| **totalCycleDurationMs** | Total time spent in completed cycles (milliseconds) |
+| **firstRunTime** | ISO timestamp of first OpenCoder run with this project |
+| **lastActivityTime** | ISO timestamp of most recent activity |
+
+### Cost Estimation
+
+OpenCoder estimates costs based on actual token usage and current model pricing for major providers:
+
+- **Claude models** (Opus, Sonnet, Haiku) - Anthropic pricing
+- **GPT models** (GPT-4o, GPT-4 Turbo, GPT-3.5) - OpenAI pricing
+- **Gemini models** - Google pricing
+- **Default pricing** - Used for unknown models
+
+Costs are estimated during operation and recorded in metrics. Use the `--status` flag to see total estimated costs.
+
+### Tips for Metrics
+
+- **Monitor regularly** - Check metrics with `--status` between sessions to track progress
+- **Reset between projects** - Use `--metrics-reset` when starting a new project
+- **Track efficiency** - Compare success rates and token usage across different models
+- **Cost awareness** - Monitor token consumption and estimated costs to stay within budget
+- **Metrics file location** - Metrics are stored in `.opencode/opencoder/metrics.json`
+
 ## Tips
 
 - **Start with a clear hint** - The more specific your instruction, the better the initial plan