feat: add fleet cost report for #520

docs/LAB-003-battery-disconnect-install.md

@@ -1,281 +0,0 @@
-# LAB-003: Truck Battery Disconnect Switch Installation
-
-**Issue:** [timmy-home#528](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/528)  
-**Objective:** Eliminate parasitic battery drain via proper disconnect switch installation  
-**Status:** Planning Complete — Ready for Execution
-
----
-
-## Problem Statement
-
-Parasitic battery drain is killing the truck battery when parked. This is critical for operational mobility in a rural location where the truck is essential for:
-- Supply runs to Newport/Claremont
-- Emergency egress
-- Equipment transport
-
-The battery has likely been damaged from repeated deep discharges and may need replacement.
-
----
-
-## Pre-Installation Checklist
-
-### Diagnostic Steps (Do These First)
-
-1. **Verify parasitic drain with multimeter:**
-   - Set multimeter to DC Amps (10A scale)
-   - Disconnect negative battery terminal
-   - Connect multimeter in series between battery negative and cable
-   - Normal drain: <50mA (0.05A)
-   - Problem drain: >100mA (0.1A)
-   - Record reading: __________ mA
-
-2. **Identify the culprit (if drain is high):**
-   - While monitoring current, pull fuses one at a time
-   - When current drops, you've found the circuit
-   - Common culprits: aftermarket radio, alarm system, interior lights, OBD-II tracker
-
-3. **Test battery health:**
-   - With engine off, battery voltage should be ~12.6V
-   - With engine running, alternator should show ~13.7-14.7V
-   - If voltage <12.4V when "fully charged," battery is degraded
-
----
-
-## Shopping List
-
-### Required Items
-
-| Item | Purpose | Est. Cost | Stores |
-|------|---------|-----------|--------|
-| Battery disconnect switch (side-post or top-post) | Isolate battery when parked | $8-15 | AutoZone, Advance, O'Reilly, NAPA |
-| Terminal shim/post riser (if needed) | Ensure proper terminal clearance | $3-8 | Same as above |
-| Dielectric grease | Prevent corrosion on terminals | $3-5 | Same as above |
-| Battery terminal cleaner brush | Clean posts before install | $2-4 | Same as above |
-| **Total Estimated** | | **$15-30** | |
-
-### Product Recommendations
-
-#### Option 1: Top Terminal Post Mount (Most Common)
-- **Recommended:** Battery Doctor Knife Switch #20138 (Advance Auto)
-  - $12-15
-  - 250A continuous, 1000A surge
-  - Easy quarter-turn operation
-  - No tools needed to operate
-
-- **Alternative:** EverStart Battery Disconnect Switch (Walmart/AutoZone)
-  - $8-12
-  - 125A continuous
-  - Twist-knob style
-
-#### Option 2: Side Terminal Mount (GM Vehicles)
-- **Recommended:** Battery Doctor Side Terminal Switch #20140
-  - $12-18
-  - Designed for GM-style side terminals
-  - Requires terminal shim for proper fit
-
-#### Option 3: Quick-Disconnect (Side Post with Cable)
-- **Recommended:** Quick Cable Battery Disconnect #5091
-  - $10-15
-  - Works with existing cable ends
-  - Marine-grade (good for NH weather)
-
-### Store Locations (Newport/Claremont Area)
-
-**AutoZone — Newport**
-- 65 Main St, Newport, NH 03773
-- (603) 863-5040
-- Hours: M-Sat 7:30AM-9PM, Sun 9AM-8PM
-
-**Advance Auto Parts — Newport**
-- 71 Main St, Newport, NH 03773
-- (603) 863-2860
-- Hours: M-Sat 7:30AM-9PM, Sun 9AM-7PM
-
-**O'Reilly Auto Parts — Claremont**
-- 385 Washington St, Claremont, NH 03743
-- (603) 542-4635
-- Hours: M-Sat 7:30AM-9PM, Sun 9AM-8PM
-
-**NAPA Auto Parts — Newport**
-- 29 John Stark Hwy, Newport, NH 03773
-- (603) 863-5500
-- Hours: M-F 7:30AM-6PM, Sat 7:30AM-4PM, Sun Closed
-
----
-
-## Installation Procedure
-
-### Tools Required
-- 10mm wrench (for most battery terminals)
-- 13mm wrench (if GM side terminals)
-- Wire brush or terminal cleaner
-- Shop rags
-- Optional: zip ties for cable management
-
-### Step-by-Step Installation
-
-1. **Safety First**
-   - Park on level ground
-   - Engage parking brake
-   - Remove keys from ignition
-   - Wear safety glasses
-
-2. **Disconnect Battery**
-   - **CRITICAL:** Disconnect NEGATIVE (-) terminal FIRST
-   - This prevents short circuits if wrench touches frame
-   - Loosen 10mm nut, wiggle terminal off post
-   - Tuck cable away so it can't touch battery post
-
-3. **Clean Terminals**
-   - Use terminal brush to clean inside of cable clamp
-   - Clean battery post until shiny
-   - Apply thin layer of dielectric grease to post
-
-4. **Install Disconnect Switch**
-
-   **For Top Post Batteries:**
-   - Remove battery cable end from switch (if pre-attached)
-   - Slide switch onto battery negative post
-   - Re-attach cable to other side of switch
-   - Tighten securely (don't overtighten — battery posts strip easily)
-
-   **For Side Terminal (GM) Batteries:**
-   - May need terminal shim/post riser for clearance
-   - Install shim on negative side terminal
-   - Mount switch to shim
-   - Connect cable to switch
-
-   **For Cable-End Style:**
-   - Cut existing negative cable near battery (leave enough slack)
-   - Strip 1/2" of insulation from both ends
-   - Install in quick-disconnect connector
-   - Crimp or bolt securely per manufacturer instructions
-
-5. **Test Installation**
-   - Switch should rotate/turn smoothly
-   - No binding or interference with battery hold-down
-   - Cable has enough slack for switch operation
-   - Switch in "ON" position: truck electronics work
-   - Switch in "OFF" position: no power to truck
-
-6. **Reconnect and Verify**
-   - Switch to ON position
-   - Attempt to start truck — should start normally
-   - Check all electronics function
-   - Switch to OFF position
-   - Verify no interior lights, radio, etc.
-
----
-
-## Testing Protocol
-
-### Immediate Test (Same Day)
-- [ ] Start truck with switch ON — engine starts normally
-- [ ] Turn switch OFF while running — engine dies (expected)
-- [ ] Switch OFF, wait 30 seconds, attempt start — no response (expected)
-- [ ] Switch ON, attempt start — starts normally
-
-### Overnight Test (Critical)
-- [ ] Park truck with switch in OFF position
-- [ ] Note battery voltage: __________ V
-- [ ] Wait 24 hours
-- [ ] Next day, switch ON, attempt start
-- [ ] Record result: □ Started normally  □ Slow crank  □ No start
-- [ ] If started, check voltage: __________ V
-
-### 48-Hour Test (If Battery Healthy)
-- [ ] Repeat overnight test with 48-hour duration
-- [ ] If truck starts normally, installation is successful
-- [ ] If truck fails to start, battery replacement needed
-
----
-
-## If Battery Needs Replacement
-
-### Symptoms of Bad Battery
-- Voltage <12.4V after "charging" overnight
-- Slow cranking even with switch disconnected
-- Battery case bulging or terminals corroded
-- Battery >4 years old
-
-### Replacement Battery Shopping
-
-**Common Truck Batteries (Group Size):**
-- Measure existing battery or check current battery label
-- Common truck sizes: Group 24F, 27F, 31, 65, 78
-
-**Recommended:**
-- **DieHard Platinum AGM** (Advance Auto) — $200-250
-  - Best cold cranking amps (CCA) for NH winters
-  - AGM handles deep discharges better
-  - 3-year full replacement warranty
-
-- **EverStart Maxx** (Walmart) — $100-150
-  - Budget option
-  - Check CCA rating matches or exceeds old battery
-
-- **Optima YellowTop** (Pep Boys/Amazon) — $300+
-  - Deep cycle + starting
-  - Best for vehicles with parasitic drain issues
-  - Handles repeated discharge cycles
-
----
-
-## Documentation Requirements
-
-Per issue #528 acceptance criteria, upload to Gitea:
-
-- [ ] Photo of installed disconnect switch (close-up)
-- [ ] Photo of receipt from parts store
-- [ ] Photo of truck odometer (optional, for record)
-- [ ] Note of test results (overnight start success/failure)
-- [ ] Note of battery voltage readings (before/after)
-
-Upload via:
-1. Open issue #528 in browser
-2. Comment with photos attached
-3. Check off acceptance criteria
-
----
-
-## Troubleshooting
-
-| Problem | Cause | Solution |
-|---------|-------|----------|
-| Switch won't tighten on post | Wrong terminal type | Get side-terminal adapter or different switch style |
-| Switch hits battery hold-down | Clearance issue | Add terminal shim to raise switch, or relocate hold-down |
-| Cable too short | Switch adds height | Get battery cable extension or longer replacement cable |
-| Still drains with switch OFF | Switch installed on wrong terminal | Move to NEGATIVE terminal only |
-| Switch gets hot | Loose connection | Tighten terminal nuts; check for corrosion |
-| Truck won't start even with switch ON | Battery too dead | Jump start, then evaluate if battery needs replacement |
-
----
-
-## Cold Weather Considerations (NH)
-
-- Batteries lose ~50% capacity at 0°F
-- Disconnect switch prevents drain but doesn't prevent cold damage
-- If storing truck long-term:
-  - Switch to OFF
-  - Consider battery maintainer (trickle charger)
-  - Or remove battery and store in heated space
-
----
-
-## Summary
-
-This installation is straightforward and should take 30-60 minutes including store run. The key steps:
-
-1. **Diagnose first** — verify parasitic drain, check battery health
-2. **Buy the right switch** — match your battery terminal type (top vs side)
-3. **Install on NEGATIVE terminal only** — this is critical for safety
-4. **Test thoroughly** — overnight test proves the fix worked
-5. **Document** — photos and receipts to close the issue
-
-**Estimated total time:** 2-3 hours (including store run)  
-**Estimated cost:** $15-30 (switch only) or $100-300 (if battery replacement needed)
-
----
-
-*Prepared for: timmy-home#528*  
-*Last updated: 2026-04-22*

docs/LAB-003-verification-template.md

@@ -1,109 +0,0 @@
-# LAB-003 Verification Report Template
-
-**Issue:** [timmy-home#528](https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/528)  
-**Date:** __________  
-**Technician:** __________
-
----
-
-## Pre-Installation Diagnostics
-
-| Test | Reading | Normal Range | Status |
-|------|---------|--------------|--------|
-| Battery Voltage (engine off) | _____ V | 12.4-12.7V | □ Pass □ Fail |
-| Parasitic Current | _____ mA | <50mA | □ Pass □ Fail |
-| Battery Voltage (engine running) | _____ V | 13.7-14.7V | □ Pass □ Fail |
-
-**Battery Health Assessment:** □ Good □ Fair □ Replace
-
----
-
-## Parts Purchased
-
-| Item | Store | Cost |
-|------|-------|------|
-| Battery Disconnect Switch | _________ | $_____ |
-| Dielectric Grease | _________ | $_____ |
-| Terminal Cleaner | _________ | $_____ |
-| Other: _________ | _________ | $_____ |
-| **Total** | | **$_____** |
-
----
-
-## Installation Checklist
-
-- [ ] Negative terminal disconnected first
-- [ ] Terminals cleaned
-- [ ] Dielectric grease applied
-- [ ] Switch installed on NEGATIVE terminal
-- [ ] All connections tight
-- [ ] Switch operates smoothly (no tools needed)
-- [ ] No interference with hood/battery hold-down
-
----
-
-## Post-Installation Tests
-
-### Immediate Tests
-- [ ] Truck starts with switch ON
-- [ ] No power with switch OFF
-- [ ] All electronics function normally (switch ON)
-
-### 24-Hour Test
-- [ ] Parked with switch OFF for 24+ hours
-- [ ] Truck started normally next day
-- [ ] Battery voltage before test: _____ V
-- [ ] Battery voltage after test: _____ V
-
-### 48-Hour Test (if applicable)
-- [ ] Parked with switch OFF for 48+ hours
-- [ ] Truck started normally
-
----
-
-## Photos Required
-
-Upload these to issue #528:
-
-- [ ] Photo of installed disconnect switch (close-up)
-- [ ] Photo of receipt from parts store
-- [ ] Photo showing switch in OFF position
-- [ ] Photo of truck dashboard (optional, for records)
-
----
-
-## Results Summary
-
-| Acceptance Criterion | Status |
-|---------------------|--------|
-| Disconnect switch installed and physically secure | □ Pass □ Fail |
-| Truck starts reliably after 24+ hours with switch disconnected | □ Pass □ Fail |
-| No special tools required to operate the disconnect | □ Pass □ Fail |
-| Receipt uploaded to issue | □ Pass □ Fail |
-
-**Overall Status:** □ Complete - All criteria met  
-□ Partial - See notes  
-□ Failed - Requires follow-up
-
----
-
-## Notes / Issues Encountered
-
-_________________________________________________________________
-
-_________________________________________________________________
-
-_________________________________________________________________
-
----
-
-## Follow-up Actions (if needed)
-
-- [ ] Replace battery (if tests failed)
-- [ ] Exchange switch for different style (if fitment issue)
-- [ ] Troubleshoot remaining parasitic drain
-- [ ] Other: _____________________________________________
-
----
-
-*Fill out this template during installation and upload to issue #528*

scripts/fleet_cost_report.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+"""Fleet cost report generator.
+
+Reads Timmy's sovereignty metrics database and estimates paid API spend by
+agent/provider lane. Default output targets the local timmy-config reports
+folder so the cost report can be filed from the sidecar repo.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sqlite3
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Iterable
+
+DB_PATH = Path.home() / ".timmy" / "metrics" / "model_metrics.db"
+
+
+AGENT_LANES = (
+    {
+        "agent": "Timmy Cloud Lane",
+        "provider": "OpenRouter",
+        "patterns": ("openrouter/", "google/", "deepseek/", "x-ai/", "mistral/"),
+        "notes": "Cloud fallback and external reasoning routed through OpenRouter-compatible lanes.",
+    },
+    {
+        "agent": "Ezra",
+        "provider": "Anthropic",
+        "patterns": ("claude-", "anthropic/claude"),
+        "notes": "Archivist / long-form reasoning house on Claude-family models.",
+    },
+    {
+        "agent": "Bezalel",
+        "provider": "OpenAI",
+        "patterns": ("gpt-", "openai/", "codex"),
+        "notes": "Forge / implementation house on Codex/OpenAI-backed execution lanes.",
+    },
+    {
+        "agent": "Allegro",
+        "provider": "Kimi / Moonshot",
+        "patterns": ("kimi", "moonshot"),
+        "notes": "Tempo-and-dispatch house on Kimi / Moonshot direct API lanes.",
+    },
+)
+
+
+def default_report_path(report_date: str | None = None) -> Path:
+    if report_date is None:
+        report_date = datetime.now().strftime("%Y-%m-%d")
+    return Path.home() / "code" / "timmy-config" / "reports" / "production" / f"{report_date}-fleet-cost-report.md"
+
+
+def match_lane(model: str) -> dict | None:
+    lowered = (model or "").lower()
+    for lane in AGENT_LANES:
+        if any(pattern in lowered for pattern in lane["patterns"]):
+            return lane
+    return None
+
+
+def load_cost_rows(days: int = 30, db_path: Path = DB_PATH) -> list[tuple[str, int, int, int, float]]:
+    if not db_path.exists():
+        return []
+    cutoff = (datetime.now() - timedelta(days=days)).timestamp()
+    with sqlite3.connect(str(db_path)) as conn:
+        rows = conn.execute(
+            """
+            SELECT model, SUM(sessions), SUM(messages), SUM(tool_calls), SUM(est_cost_usd)
+            FROM session_stats
+            WHERE timestamp > ? AND is_local = 0
+            GROUP BY model
+            ORDER BY SUM(est_cost_usd) DESC, model ASC
+            """,
+            (cutoff,),
+        ).fetchall()
+    return [
+        (model, int(sessions or 0), int(messages or 0), int(tool_calls or 0), float(cost or 0.0))
+        for model, sessions, messages, tool_calls, cost in rows
+    ]
+
+
+def summarize_rows(rows: Iterable[tuple[str, int, int, int, float]], days: int = 30) -> dict:
+    rows = list(rows)
+    agents: dict[str, dict] = {}
+    providers_seen: set[str] = set()
+    inventory = [
+        {
+            "agent": lane["agent"],
+            "provider": lane["provider"],
+            "notes": lane["notes"],
+        }
+        for lane in AGENT_LANES
+    ]
+
+    for lane in AGENT_LANES:
+        agents[lane["agent"]] = {
+            "provider": lane["provider"],
+            "models": [],
+            "sessions": 0,
+            "messages": 0,
+            "tool_calls": 0,
+            "monthly_cost_usd": 0.0,
+            "daily_cost_usd": 0.0,
+            "notes": lane["notes"],
+        }
+
+    unassigned = {
+        "provider": "Unassigned",
+        "models": [],
+        "sessions": 0,
+        "messages": 0,
+        "tool_calls": 0,
+        "monthly_cost_usd": 0.0,
+        "daily_cost_usd": 0.0,
+        "notes": "Observed paid-model spend not yet mapped to a named wizard house.",
+    }
+
+    for model, sessions, messages, tool_calls, monthly_cost in rows:
+        lane = match_lane(model)
+        if lane is None:
+            bucket = unassigned
+        else:
+            bucket = agents[lane["agent"]]
+            providers_seen.add(lane["provider"])
+        bucket["models"].append(
+            {
+                "model": model,
+                "sessions": sessions,
+                "messages": messages,
+                "tool_calls": tool_calls,
+                "monthly_cost_usd": round(monthly_cost, 4),
+            }
+        )
+        bucket["sessions"] += sessions
+        bucket["messages"] += messages
+        bucket["tool_calls"] += tool_calls
+        bucket["monthly_cost_usd"] += monthly_cost
+
+    for bucket in list(agents.values()) + [unassigned]:
+        bucket["monthly_cost_usd"] = round(bucket["monthly_cost_usd"], 4)
+        bucket["daily_cost_usd"] = round(bucket["monthly_cost_usd"] / max(days, 1), 4)
+
+    if unassigned["models"]:
+        agents["Unassigned"] = unassigned
+        providers_seen.add("Unassigned")
+
+    total_monthly = round(sum(item["monthly_cost_usd"] for item in agents.values()), 4)
+    total_daily = round(sum(item["daily_cost_usd"] for item in agents.values()), 4)
+
+    provider_order = sorted(providers_seen)
+    if "Unassigned" in provider_order:
+        provider_order = [p for p in provider_order if p != "Unassigned"] + ["Unassigned"]
+
+    return {
+        "days": days,
+        "providers": provider_order,
+        "inventory": inventory,
+        "agents": agents,
+        "total_monthly_cost_usd": total_monthly,
+        "total_daily_cost_usd": total_daily,
+    }
+
+
+def render_markdown(summary: dict, report_date: str | None = None) -> str:
+    if report_date is None:
+        report_date = datetime.now().strftime("%Y-%m-%d")
+    lines = [
+        f"# Fleet Cost Report — {report_date}",
+        "",
+        f"Window: last {summary['days']} days of paid-model session stats from `~/.timmy/metrics/model_metrics.db`.",
+        "",
+        "## Paid API inventory",
+        "",
+        "| Agent | Provider | Notes |",
+        "| --- | --- | --- |",
+    ]
+    for item in summary["inventory"]:
+        lines.append(f"| {item['agent']} | {item['provider']} | {item['notes']} |")
+
+    lines.extend(
+        [
+            "",
+            "## Estimated cost per agent per day",
+            "",
+            "| Agent | Provider | Daily cost | Monthly estimate | Sessions | Messages | Tool calls |",
+            "| --- | --- | ---: | ---: | ---: | ---: | ---: |",
+        ]
+    )
+    for agent, data in summary["agents"].items():
+        lines.append(
+            f"| {agent} | {data['provider']} | ${data['daily_cost_usd']:.2f} | ${data['monthly_cost_usd']:.2f} | {data['sessions']} | {data['messages']} | {data['tool_calls']} |"
+        )
+
+    lines.extend(
+        [
+            "",
+            f"Total estimated daily paid spend: ${summary['total_daily_cost_usd']:.2f}",
+            f"Total estimated monthly paid spend: ${summary['total_monthly_cost_usd']:.2f}",
+            "",
+            "## Model evidence",
+            "",
+        ]
+    )
+    for agent, data in summary["agents"].items():
+        lines.append(f"### {agent}")
+        if not data["models"]:
+            lines.append("- No paid-model sessions observed in the selected window.")
+        else:
+            for model in data["models"]:
+                lines.append(
+                    f"- `{model['model']}` — {model['sessions']} sessions / {model['messages']} messages / {model['tool_calls']} tool calls / ${model['monthly_cost_usd']:.2f} est."
+                )
+        lines.append("")
+
+    lines.append("Generated by `python3 scripts/fleet_cost_report.py --days 30`. Default output path targets the local timmy-config report lane.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def write_report(output_path: Path, summary: dict, report_date: str | None = None) -> Path:
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(render_markdown(summary, report_date=report_date), encoding="utf-8")
+    return output_path
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Estimate paid API spend per fleet agent")
+    parser.add_argument("--days", type=int, default=30, help="Lookback window in days")
+    parser.add_argument("--db-path", default=str(DB_PATH), help="Path to model_metrics.db")
+    parser.add_argument("--output", help="Optional markdown output path")
+    parser.add_argument("--date", help="Override report date (YYYY-MM-DD)")
+    args = parser.parse_args()
+
+    rows = load_cost_rows(days=args.days, db_path=Path(args.db_path).expanduser())
+    summary = summarize_rows(rows, days=args.days)
+    report_date = args.date or datetime.now().strftime("%Y-%m-%d")
+    output_path = Path(args.output).expanduser() if args.output else default_report_path(report_date)
+    write_report(output_path, summary, report_date=report_date)
+    print(output_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/lab_003_battery_disconnect.sh

@@ -1,215 +0,0 @@
-#!/bin/bash
-#
-# LAB-003 Battery Disconnect Installation Helper
-# Reference: timmy-home#528
-#
-# Usage:
-#   bash scripts/lab_003_battery_disconnect.sh diagnose    # Test battery before install
-#   bash scripts/lab_003_battery_disconnect.sh checklist   # Print installation checklist
-#   bash scripts/lab_003_battery_disconnect.sh verify      # Post-install verification
-#
-
-set -euo pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-LOG_FILE="$SCRIPT_DIR/../logs/lab_003_$(date +%Y%m%d_%H%M%S).log"
-ISSUE_URL="https://forge.alexanderwhitestone.com/Timmy_Foundation/timmy-home/issues/528"
-
-echo "=== LAB-003: Battery Disconnect Switch Installation ==="
-echo "Issue: $ISSUE_URL"
-echo ""
-
-mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
-
-log() {
-    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE" 2>/dev/null || echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1"
-}
-
-diagnose() {
-    log "=== Battery Diagnosis ==="
-    echo ""
-    echo "This will help determine if you need a new battery or just the disconnect switch."
-    echo ""
-    
-    echo "Step 1: Check battery voltage with multimeter"
-    echo "  - Set multimeter to DC Volts (20V scale)"
-    echo "  - Red probe to battery positive (+)"
-    echo "  - Black probe to battery negative (-)"
-    echo ""
-    read -p "Enter voltage reading (e.g., 12.6): " voltage
-    log "Battery voltage: ${voltage}V"
-    
-    if (( $(echo "$voltage >= 12.6" | bc -l) )); then
-        echo "✓ Battery voltage is GOOD (≥12.6V)"
-        log "Battery voltage GOOD"
-    elif (( $(echo "$voltage >= 12.4" | bc -l) )); then
-        echo "⚠ Battery voltage is FAIR (12.4-12.5V) - may need replacement soon"
-        log "Battery voltage FAIR"
-    else
-        echo "✗ Battery voltage is LOW (<12.4V) - likely needs replacement"
-        log "Battery voltage LOW - replacement recommended"
-    fi
-    
-    echo ""
-    echo "Step 2: Check for parasitic drain"
-    echo "  - Set multimeter to DC Amps (10A scale)"
-    echo "  - Disconnect negative battery cable"
-    echo "  - Connect multimeter between battery negative post and cable"
-    echo "  - Wait 2 minutes for modules to sleep"
-    echo ""
-    read -p "Enter current reading in milliamps (e.g., 50): " current
-    log "Parasitic current: ${current}mA"
-    
-    if (( $(echo "$current <= 50" | bc -l) )); then
-        echo "✓ Parasitic drain is NORMAL (≤50mA)"
-        log "Parasitic drain NORMAL"
-        echo ""
-        echo "NOTE: Normal drain means the disconnect switch may not be necessary"
-        echo "      unless you're storing the truck for weeks at a time."
-    elif (( $(echo "$current <= 100" | bc -l) )); then
-        echo "⚠ Parasitic drain is ELEVATED (50-100mA)"
-        log "Parasitic drain ELEVATED"
-        echo "Disconnect switch will help prevent dead battery."
-    else
-        echo "✗ Parasitic drain is HIGH (>100mA)"
-        log "Parasitic drain HIGH - disconnect switch highly recommended"
-        echo ""
-        echo "You definitely need the disconnect switch!"
-    fi
-    
-    echo ""
-    log "Diagnosis complete. Log saved to: $LOG_FILE"
-}
-
-checklist() {
-    cat << 'EOF'
-=== LAB-003 Installation Checklist ===
-
-BEFORE YOU GO:
-□ Determine battery terminal type (top post vs side terminal)
-□ Measure battery group size (look for label like "Group 24F")
-□ Check if you have 10mm and 13mm wrenches
-□ Verify multimeter has DC Volts and DC Amps capability
-
-AT THE STORE:
-□ Purchase battery disconnect switch (match your terminal type)
-□ Purchase dielectric grease
-□ Purchase terminal cleaner brush (if you don't have one)
-□ Get receipt for documentation
-
-INSTALLATION:
-□ Park on level ground, engage parking brake
-□ Disconnect NEGATIVE (-) terminal first
-□ Clean terminals with wire brush
-□ Apply dielectric grease
-□ Install switch on NEGATIVE terminal
-□ Reconnect and test operation
-
-TESTING:
-□ Switch ON: truck starts normally
-□ Switch OFF: no power to truck
-□ Overnight test: switch OFF, verify start next day
-□ Document with photos
-□ Upload photos to issue #528
-
-TROUBLESHOOTING:
-□ If switch doesn't fit: wrong terminal type - exchange at store
-□ If still drains overnight: battery needs replacement
-□ If slow crank with new switch: battery degraded - replace
-
-EOF
-}
-
-verify() {
-    log "=== Post-Installation Verification ==="
-    echo ""
-    echo "Post-installation tests. Run these AFTER installing the disconnect switch."
-    echo ""
-    
-    read -p "Test 1 - Can you start the truck with the switch ON? (y/n): " t1
-    if [[ "$t1" == "y" ]]; then
-        log "Test 1 PASSED: Truck starts with switch ON"
-        echo "✓ Test 1 PASSED"
-    else
-        log "Test 1 FAILED: Truck won't start with switch ON"
-        echo "✗ Test 1 FAILED - Check installation and battery"
-    fi
-    
-    echo ""
-    read -p "Test 2 - With truck OFF and switch OFF, do interior lights/radio work? (y/n): " t2
-    if [[ "$t2" == "n" ]]; then
-        log "Test 2 PASSED: No power with switch OFF"
-        echo "✓ Test 2 PASSED"
-    else
-        log "Test 2 FAILED: Power still on with switch OFF"
-        echo "✗ Test 2 FAILED - Switch may be on wrong terminal or defective"
-    fi
-    
-    echo ""
-    read -p "Test 3 - Is the switch easy to operate by hand (no tools needed)? (y/n): " t3
-    if [[ "$t3" == "y" ]]; then
-        log "Test 3 PASSED: Switch operable without tools"
-        echo "✓ Test 3 PASSED"
-    else
-        log "Test 3 WARNING: Switch may require tools"
-        echo "⚠ Test 3 WARNING - Consider a different switch style"
-    fi
-    
-    echo ""
-    echo "=== 24-Hour Test ==="
-    echo "Park truck with switch OFF. Tomorrow, try to start it."
-    echo "Record result in issue #528: $ISSUE_URL"
-    echo ""
-    
-    read -p "Did the 24-hour test pass (truck started normally)? (y/n/skip): " t24
-    case "$t24" in
-        y)
-            log "24-hour test PASSED"
-            echo "✓ Installation SUCCESSFUL!"
-            echo ""
-            echo "Close issue #528 with:"
-            echo "  - Photo of installed switch"
-            echo "  - Photo of receipt"
-            echo "  - Note: '24-hour test passed, truck started normally'"
-            ;;
-        n)
-            log "24-hour test FAILED"
-            echo "✗ Test FAILED - Battery likely needs replacement"
-            echo ""
-            echo "Next steps:"
-            echo "  1. Jump start truck"
-            echo "  2. Drive to store for battery replacement"
-            echo "  3. Reference LAB-003-battery-disconnect-install.md for battery shopping guide"
-            ;;
-        *)
-            log "24-hour test pending"
-            echo "Run this script again after 24 hours with: bash $0 verify"
-            ;;
-    esac
-    
-    echo ""
-    log "Verification complete. Log saved to: $LOG_FILE"
-}
-
-case "${1:-help}" in
-    diagnose)
-        diagnose
-        ;;
-    checklist)
-        checklist
-        ;;
-    verify)
-        verify
-        ;;
-    *)
-        echo "Usage: $0 {diagnose|checklist|verify}"
-        echo ""
-        echo "  diagnose   - Check battery voltage and parasitic drain"
-        echo "  checklist  - Print installation checklist"
-        echo "  verify     - Post-installation verification tests"
-        echo ""
-        echo "Full guide: docs/LAB-003-battery-disconnect-install.md"
-        echo "Issue: $ISSUE_URL"
-        exit 1
-        ;;
-esac

tests/test_fleet_cost_report.py

@@ -0,0 +1,77 @@
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+import tempfile
+import unittest
+
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPT_PATH = ROOT / "scripts" / "fleet_cost_report.py"
+
+
+def load_module():
+    spec = spec_from_file_location("fleet_cost_report", SCRIPT_PATH)
+    module = module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+class TestFleetCostReport(unittest.TestCase):
+    def test_default_output_targets_timmy_config_report_path(self):
+        module = load_module()
+        output_path = module.default_report_path("2026-04-22")
+        self.assertIn("timmy-config", str(output_path))
+        self.assertTrue(str(output_path).endswith("2026-04-22-fleet-cost-report.md"))
+
+    def test_summary_groups_paid_costs_by_agent_and_provider(self):
+        module = load_module()
+        rows = [
+            ("claude-sonnet-4-6", 12, 120, 24, 6.0),
+            ("gpt-5.4", 6, 60, 12, 3.0),
+            ("openrouter/google/gemini-2.5-pro", 4, 40, 8, 2.0),
+            ("kimi-k2", 2, 20, 4, 1.0),
+        ]
+        summary = module.summarize_rows(rows, days=30)
+
+        self.assertEqual(summary["providers"], ["Anthropic", "Kimi / Moonshot", "OpenAI", "OpenRouter"])
+        self.assertAlmostEqual(summary["agents"]["Ezra"]["monthly_cost_usd"], 6.0)
+        self.assertAlmostEqual(summary["agents"]["Bezalel"]["monthly_cost_usd"], 3.0)
+        self.assertAlmostEqual(summary["agents"]["Timmy Cloud Lane"]["monthly_cost_usd"], 2.0)
+        self.assertAlmostEqual(summary["agents"]["Allegro"]["monthly_cost_usd"], 1.0)
+        self.assertAlmostEqual(summary["agents"]["Ezra"]["daily_cost_usd"], 0.2)
+
+    def test_report_render_mentions_inventory_and_agent_costs(self):
+        module = load_module()
+        rows = [
+            ("claude-sonnet-4-6", 12, 120, 24, 6.0),
+            ("gpt-5.4", 6, 60, 12, 3.0),
+            ("openrouter/google/gemini-2.5-pro", 4, 40, 8, 2.0),
+        ]
+        summary = module.summarize_rows(rows, days=30)
+        report = module.render_markdown(summary, report_date="2026-04-22")
+
+        self.assertIn("# Fleet Cost Report — 2026-04-22", report)
+        self.assertIn("## Paid API inventory", report)
+        self.assertIn("Anthropic", report)
+        self.assertIn("OpenRouter", report)
+        self.assertIn("OpenAI", report)
+        self.assertIn("## Estimated cost per agent per day", report)
+        self.assertIn("Timmy Cloud Lane", report)
+        self.assertIn("Ezra", report)
+        self.assertIn("Bezalel", report)
+
+    def test_write_report_creates_markdown_file(self):
+        module = load_module()
+        rows = [("claude-sonnet-4-6", 1, 10, 2, 0.5)]
+        summary = module.summarize_rows(rows, days=30)
+        with tempfile.TemporaryDirectory() as tmpdir:
+            dest = Path(tmpdir) / "fleet-cost.md"
+            module.write_report(dest, summary, report_date="2026-04-22")
+            self.assertTrue(dest.exists())
+            text = dest.read_text()
+            self.assertIn("Fleet Cost Report", text)
+            self.assertIn("Ezra", text)
+
+
+if __name__ == "__main__":
+    unittest.main()