ckforensics 0.2.1 → 0.2.2

package/.claude/skills/ckforensics/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: ck:forensics
+description: "Forensic analysis of Claude Code sessions — token cost, context map, audit manifest, skill recommendations. Use when user asks 'what did Claude touch', 'where did my tokens go', 'how much did this session cost', 'show last session', 'what skill should I have used', or wants post-hoc review of CC work."
+category: dev-tools
+keywords: [claude-code, audit, forensics, observability, token-cost, context, skill-recommender, session-review]
+argument-hint: "summary|sessions|audit|map|suggest|skills|ingest [args]"
+metadata:
+  author: phong28zk
+  version: "0.2.1"
+  upstream: "https://github.com/phong28zk/ckforensics"
+---
+
+# ck:forensics — Claude Code Session Forensics
+
+Read-only post-hoc analysis of `~/.claude/projects/**/*.jsonl` transcripts. Surfaces:
+- **What was burned:** tokens, $, time, by tool/skill/file
+- **What changed:** files touched, diff, reasoning trail, subagent attribution
+- **What lives in context:** heatmap of items by category (tool_result, message, ...)
+- **What you missed:** skills that would have replaced repeated manual sequences
+
+Powered by the `ckforensics` CLI (npm `ckforensics@^0.2.1`). Local-only, no telemetry.
+
+---
+
+## Default (No Arguments)
+
+If invoked without arguments, use `AskUserQuestion` to present operations:
+
+| Operation | Description |
+|-----------|-------------|
+| `summary` | Token + cost rollup (last 7d default) |
+| `sessions` | List recent sessions with cost/duration |
+| `audit` | Per-session change manifest (files, diff, reasoning) |
+| `map` | Context-window heatmap (what eats tokens?) |
+| `suggest` | Skills that would have helped (pattern detection) |
+| `skills` | List/search indexed skills with usage stats |
+| `ingest` | Refresh DB from `~/.claude/projects/` |
+
+Present via `AskUserQuestion` with header "Forensics" and question "Which analysis?".
+
+---
+
+## Installation Check
+
+Before running any command, ensure CLI is installed:
+
+```bash
+command -v ckforensics >/dev/null || {
+  echo "ckforensics not installed. Install with: npm i -g ckforensics"
+  exit 1
+}
+```
+
+If missing, ask user to install before proceeding.
+
+---
+
+## Workflows
+
+| Workflow | Reference |
+|----------|-----------|
+| End-of-day session review | `references/workflow-eod.md` |
+| Pre-commit audit | `references/workflow-pre-commit.md` |
+| Weekly cost retro | `references/workflow-weekly-retro.md` |
+| Command reference | `references/commands.md` |
+| Output interpretation | `references/interpretation.md` |
+
+---
+
+## Core Commands
+
+### `summary [--days N]`
+
+Token/cost rollup. Default 7 days.
+
+```bash
+ckforensics summary             # last 7 days
+ckforensics summary --days 1    # today
+ckforensics summary --days 30   # this month
+ckforensics summary --json      # for piping to jq
+```
+
+**Cost interpretation:** API-rate equivalent. Subscription users (Pro/Max) pay flat fee — treat as "value extracted", not actual bill. See `references/interpretation.md`.
+
+### `audit [--last|<session-id>] [--out FILE]`
+
+Per-session change manifest:
+- Header (model, duration, cost, total events)
+- Files changed (with chronological edits + reasoning quotes)
+- Subagent dispatches + recursive cost breakdown
+- Reasoning correlator: each tool call linked to preceding assistant text
+
+```bash
+ckforensics audit --last                            # most recent session
+ckforensics audit <session-id> --out review.md      # for PR review
+ckforensics audit --last --format json | jq         # script-friendly
+```
+
+### `map [--last|<session-id>] [--top N]`
+
+Context-window heatmap. Shows what categories eat the most tokens:
+- `tool:Bash` → shell output
+- `tool:Read` / `tool:Edit` → file ops
+- `assistant` / `user` → messages
+- `unknown` → unattributable
+
+Use `--simulate-compact` to project what survives next auto-compact.
+
+```bash
+ckforensics map --last --top 20
+ckforensics map --simulate-compact --target-pct 50
+```
+
+### `suggest [--session ID|--last|--days N] [--min-confidence 70]`
+
+Skill recommendations: detects repeated tool patterns and matches against `~/.claude/skills/` catalog. Suggests skills that would have replaced manual work.
+
+```bash
+ckforensics suggest --last                       # for most recent session
+ckforensics suggest --days 7 --min-confidence 30  # weekly retro
+```
+
+### `sessions [--project SLUG] [--limit N]`
+
+List recent sessions with cost/duration. Filter by project.
+
+```bash
+ckforensics sessions --limit 10
+ckforensics sessions --project ckforensics --limit 50
+```
+
+### `skills [--unused|--used] [--search QUERY] [--refresh]`
+
+List indexed skills. `--unused` shows skills you have but never invoked. Discoverability tool.
+
+```bash
+ckforensics skills --refresh        # re-scan ~/.claude/skills/
+ckforensics skills --unused | head  # what am I missing?
+```
+
+### `ingest`
+
+Refresh DB from `~/.claude/projects/`. Incremental — only new jsonl content.
+
+```bash
+ckforensics ingest                  # one-shot
+ckforensics ingest --watch          # poll every 5s
+```
+
+---
+
+## When to Use This Skill
+
+**After CC session:** Run `audit --last` to review what Claude changed.
+
+**Cost review:** Run `summary` to see token burn vs subscription value.
+
+**Habit improvement:** Run `suggest --days 7` weekly to find skill opportunities.
+
+**Context optimization:** Run `map --last` when session hits compaction wall — see what eats tokens.
+
+**Pre-commit:** Run `audit --last --out review.md` then `redact review.md --in-place` before sharing.
+
+---
+
+## Output Interpretation
+
+| Pattern | Meaning |
+|---------|---------|
+| `tool:Bash` >40% of map | Heavy shell output; consider piping to `tail`/`head` |
+| `tool:Read` repeats on same dir | `/ck:scout` candidate |
+| Subagent cost > main cost | Runaway subagent — review prompt scope |
+| Cost in red (>$10) | High-value session; worth saving manifest for retro |
+| Suggest confidence <50% | Probably noise; only act on ≥70% |
+
+See `references/interpretation.md` for full guide.
+
+---
+
+## Important Notes
+
+- **All operations are read-only.** Never modifies `~/.claude/projects/`.
+- **Cost is API-rate estimate** (Nov 2025 Anthropic pricing); subscription users see flat fee.
+- **±20% attribution margin** on context map (heuristic-based).
+- **Cache local at** `~/.local/share/ckforensics/store.db` (mode 0600).
+- **Logs at** `~/.local/state/ckforensics/logs/` (Linux), `~/Library/Logs/ckforensics/` (macOS).
+
+## Token Efficiency
+
+- Activate `ck:context-engineering` skill if running `audit` or `map` on very long sessions (output can be 100k+ tokens of markdown — pipe to file).
+- Use `--json` for downstream tools; avoids markdown formatting overhead.
+- For routine ingest, cron handles it: `0 * * * * ckforensics ingest >> ~/.local/state/ckforensics/logs/ingest.log 2>&1`.
+
+**Sacrifice grammar for concision when reporting findings to user.**
+
+---
+
+## Quick Start (User's First Run)
+
+```bash
+npm i -g ckforensics                    # install
+ckforensics doctor                      # verify
+ckforensics ingest                      # populate DB (~20s for 1000+ jsonl)
+ckforensics summary                     # see weekly totals
+ckforensics audit --last | head -50     # review last session
+```

package/.claude/skills/ckforensics/references/commands.md

@@ -0,0 +1,108 @@
+# ck:forensics — Command Reference
+
+Quick reference for every `ckforensics` subcommand exposed via `/ck:forensics`.
+
+## Global flags
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--db <path>` | XDG data dir | Override SQLite path |
+| `--no-color` | off | Disable ANSI |
+| `-v, --verbose` | off | Info-level logging to stderr |
+| `--debug` | off | Debug-level logging |
+| `--log-dir <path>` | XDG state dir | Override log dir |
+| `--json` | off | Force JSON output globally |
+
+## Subcommands
+
+### `summary [--days N] [--format text|md|json]`
+
+Aggregate token/cost/files across a rolling window.
+
+**Output fields:**
+- `sessionCount`
+- `totalInputTokens`, `totalOutputTokens`, `totalCacheRead`, `totalCacheCreate`
+- `estimatedCostUsd` (API-rate equivalent)
+- `filesTouched`, `editOps`
+- `oldestSession`, `newestSession`
+
+### `sessions [--project SLUG] [--limit N] [--format text|md|csv|json]`
+
+List recent sessions ordered by `started_at DESC`.
+
+**Columns:** ID, Project, Started, Model, Events, Cost, Duration
+
+Cost color-coded: red >$10, yellow $1-10, green <$1, dim — for null.
+
+### `audit [<session-id>|--last] [--out FILE] [--format md|json]`
+
+Per-session change manifest.
+
+**Sections:**
+1. Header (session ID, project, model, duration, cost, total events)
+2. Summary (files changed, lines +/-, edit ops, tokens, cache read)
+3. File Changes (chronological edits, reasoning quotes, unified diff)
+4. Subagent Dispatches (each Agent() / Task() with input + duration)
+5. Subagent Cost Breakdown (nested table with tokens + cost per agent)
+
+Exit codes: 0 success, 3 session not found.
+
+### `map [<session-id>|--last] [--top N=20] [--simulate-compact] [--target-pct N=50]`
+
+Context window heatmap by category.
+
+**Categories:** `tool:<Name>`, `assistant`, `user`, `system_prompt`, `memory`, `skill_load`, `unknown`
+
+Each row: ASCII bar + percentage + token count + item count.
+
+**`--simulate-compact`:** projects which items survive next auto-compact based on documented heuristic.
+
+**Sub-commands:**
+- `ckforensics map --save NAME` — persist snapshot
+- `ckforensics map list` — list saved snapshots
+- `ckforensics map diff <A> <B>` — token movement between snapshots
+- `ckforensics map --pin ITEM_ID --emit-manifest [FILE]` — pinned items → paste-ready markdown
+
+### `suggest [<session-id>|--last|--days N=7] [--min-confidence N=70] [--top N=3] [--format text|md|json]`
+
+Detect repeated tool patterns and recommend skills.
+
+**Patterns detected:**
+- `read-fanout`: ≥5 Reads within 3 adjacent turns on same dir
+- `test-loop`: ≥3 Bash test runs
+- `manual-diff-cycle`: read→edit→read ≥2 cycles
+- `grep-walk`: ≥4 Grep+Read pairs
+- `subagent-skip`: ≥20 main-thread tool calls, no Agent/Task
+
+**Output per rec:** invocation hint (`/ck:scout`), confidence %, est savings (tokens + USD), evidence turns.
+
+### `skills [--unused|--used] [--search QUERY] [--refresh] [--format text|md|csv|json]`
+
+List indexed skills from `~/.claude/skills/`.
+
+- `--refresh` — re-scan SKILL.md frontmatter
+- `--unused` — show skills you've never invoked
+- `--used` — show skills you've activated, with usage count
+- `--search "pattern"` — keyword search
+
+### `ingest [--watch]`
+
+Parse `~/.claude/projects/**/*.jsonl` → SQLite. Idempotent + incremental.
+
+- `--watch` polls every 5s (for cron alternative)
+
+### `redact <file> [--in-place] [--force]`
+
+Apply 9 redaction rules (sk-ant, GH tokens, AWS, JWT, etc.) to a markdown/text file. Use before sharing audit exports.
+
+### `export <view> --format md|json|csv [--out FILE]`
+
+Pipe-friendly export: `summary`, `sessions`, `audit`.
+
+### `doctor`
+
+Health check: DB exists + version, JSONL dir readable, last ingest mtime, log dir writeable, Bun version.
+
+### `path`
+
+Print resolved paths (DB, data dir, JSONL source, log dir, config dir).

package/.claude/skills/ckforensics/references/interpretation.md

@@ -0,0 +1,81 @@
+# ck:forensics — Output Interpretation Guide
+
+How to read what ckforensics tells you, and when to act on it.
+
+## Cost interpretation
+
+| Display | Meaning |
+|---------|---------|
+| `$X.XX` (green) | <$1 — typical small session |
+| `$X.XX` (yellow) | $1-10 — substantive work |
+| `$X.XX` (red) | >$10 — high-value session, worth saving manifest |
+| `unknown` / `—` | Cost not estimable (missing model in DB, pre-pricing-fix) |
+| `*` footnote | API-rate equivalent, not actual subscription bill |
+
+**Two cost numbers compared:**
+- ckforensics `Estimated Cost`: token count × Anthropic published rates
+- CC live statusline: real-time `cost.total_cost_usd` from CC's internal calc
+
+Discrepancy expected (CC may exclude some cache pricing). Within 30% = normal.
+
+**For subscription users:** the cost number = "value extracted from your $X/mo plan", not a bill.
+
+## Map heatmap thresholds
+
+| Pattern | Diagnostic | Action |
+|---------|-----------|--------|
+| `tool:Bash` >40% | Heavy shell output | Pipe to `head`/`tail`, redirect logs, or limit verbose flags |
+| `tool:Read` >30% | Excessive file reads | Use `/ck:scout` for batched discovery |
+| `tool:Edit` >30% | Lots of edits | Normal for code-heavy session; check for thrashing |
+| `assistant` >40% | Very long replies | Verbose mode, summarisation overhead |
+| `unknown` >10% | Attribution failure | Schema drift; report to ckforensics issues |
+
+## Suggest confidence brackets
+
+| Confidence | Meaning | Action |
+|------------|---------|--------|
+| 80-100% | Strong signal, multi-pattern match | Try the skill next session |
+| 60-80% | Plausible, single pattern | Worth reading description |
+| 40-60% | Weak — likely keyword coincidence | Skip unless desperate |
+| <40% | Noise | Ignore |
+
+Default threshold = 70. Lower with `--min-confidence 30` if seeing no recs.
+
+## Audit manifest sections
+
+### Files changed
+
+Each file shows chronological edits with reasoning quote. **Read the reasoning** — it's the assistant's intent text before the tool call, not post-hoc explanation. Useful for:
+- Understanding *why* an edit was made
+- Catching scope creep (intent vs action mismatch)
+- Composing PR descriptions (reasoning often is the PR body)
+
+### Subagent Cost Breakdown
+
+Nested table. Top-level rows = direct Agent()/Task() calls from main thread. Indented rows = nested (subagent inside subagent).
+
+**Red flags:**
+- Single subagent with >$5 cost in <10 tool calls = runaway
+- "open" duration → subagent still running (session paused?)
+- Many small subagents (≤2 calls each) = excessive fanout
+
+### Reasoning correlator
+
+Each tool call gets a "Reasoning:" quote. If reasoning is empty/unhelpful:
+- Assistant didn't narrate (rare)
+- Tool fired in middle of multi-block message (correlator picks last text block)
+- Subagent invocation (reasoning belongs to parent dispatch)
+
+## Sessions list signals
+
+- Same project, multiple short sessions same day → context flushing too often
+- Single 10+ hour session → consider checkpointing via context map
+- Cost trending up week-over-week → instrument with `summary --days N`
+
+## When ingest finds nothing
+
+If `ckforensics ingest` reports 0 new events:
+1. Check `ckforensics doctor` — last ingest mtime
+2. Verify `~/.claude/projects/` has recent jsonl: `ls -lt ~/.claude/projects/*/*.jsonl | head`
+3. CC may be on different config dir (CLAUDE_CONFIG_DIR env var) — set `--db` accordingly
+4. Force re-ingest from scratch: `rm ~/.local/share/ckforensics/store.db && ckforensics ingest`

package/.claude/skills/ckforensics/references/workflow-eod.md

@@ -0,0 +1,56 @@
+# End-of-Day Session Review Workflow
+
+Pattern: after a substantial Claude Code session, run forensics to know what shipped, what burned, what to remember.
+
+## Flow
+
+```
+1. ckforensics ingest                       # refresh DB
+2. ckforensics summary --days 1             # today's totals
+3. ckforensics audit --last --out eod.md    # capture manifest
+4. ckforensics suggest --last               # skills that would have helped
+5. ckforensics map --last --top 15          # what ate the context
+```
+
+## When Claude runs this skill
+
+User says one of:
+- "wrap up this session"
+- "what did I do today"
+- "end of day review"
+- "summary of last session"
+- "did Claude do anything weird"
+
+## What Claude should do
+
+1. Run the 5 commands above (or relevant subset).
+2. **Summarise**, don't paste raw output to user. Surface:
+   - Total cost (API-rate) + duration
+   - Top 3 files changed (by lines or by importance from reasoning quotes)
+   - Any subagent that cost >$1 (flag for review)
+   - Top 1-2 skill recommendations with confidence ≥70
+   - Context map insight: what ate most tokens
+3. **Offer next actions:**
+   - "Save audit manifest as PR description?" → use `eod.md`
+   - "Dismiss low-value skill recs?" → `~/.config/ckforensics/dismissed.json`
+   - "Schedule cron for daily ingest?" → crontab snippet
+
+## Example response template
+
+```
+Today's session burned $X.XX over Y hours. Modified Z files (top: A, B, C).
+
+Notable:
+- Subagent "P11 log infra" cost $28 — runaway, worth reviewing
+- Skill /ck:scout would have replaced 23× Read on src/audit/* (saves ~12k tokens)
+- Context map: tool:Bash 40%, tool:Edit 16% — heavy shell + editing
+
+Manifest saved to eod.md. Want me to draft a commit message from it?
+```
+
+## Anti-patterns
+
+- ❌ Paste full audit markdown (1000+ lines) to user
+- ❌ Run all 5 commands when user only asked "cost today"
+- ❌ Recommend skills with confidence <70 without flagging confidence
+- ❌ Skip subagent cost breakdown — that's the highest-signal section

package/.claude/skills/ckforensics/references/workflow-pre-commit.md

@@ -0,0 +1,63 @@
+# Pre-Commit Audit Workflow
+
+Pattern: before user runs `git commit`, generate a manifest of what Claude touched and use it as commit/PR body draft.
+
+## Flow
+
+```
+1. ckforensics ingest                       # ensure DB current
+2. ckforensics audit --last --out review.md # capture this session's manifest
+3. ckforensics redact review.md --in-place  # strip secrets before sharing
+4. (user opens review.md, copies relevant sections to commit body)
+```
+
+## When Claude runs this skill
+
+User says one of:
+- "ready to commit"
+- "draft a commit message from this session"
+- "what should the PR description say"
+- "review what I just did before committing"
+
+## What Claude should do
+
+1. Run `audit --last` to get the manifest.
+2. Pipe through `redact` (always, never skip — secrets risk).
+3. Extract from manifest:
+   - **Files changed** + line counts (for `git diff --stat` equivalent)
+   - **Reasoning quotes** per file (often makes the PR body)
+   - **Subagent contributions** (mention if subagents did significant work)
+4. **Draft conventional commit**:
+   ```
+   <type>(<scope>): <subject>
+   
+   <body — TLDR of what changed and why, from reasoning>
+   
+   <body — files affected, key decisions>
+   ```
+5. **Surface anything suspicious:**
+   - Files touched in unexpected directories
+   - Reasoning that doesn't match the actions (intent drift)
+   - Subagents with high cost (worth mentioning in PR)
+
+## Integration with ck:git
+
+After draft, hand off to `/ck:git cm` for execution:
+```
+ckforensics audit --last --out review.md
+ckforensics redact review.md --in-place
+# Claude reads review.md, drafts commit message
+# Hand to /ck:git cm — user reviews + executes
+```
+
+Or pipe directly (v0.5 phase 12 will support this):
+```
+ckforensics commit --phase last | ck:git cm --message-stdin
+```
+
+## Anti-patterns
+
+- ❌ Skip redaction — manifests can contain edited file contents = secrets risk
+- ❌ Paste raw manifest as commit body (too long, unstructured)
+- ❌ Auto-commit — always show draft, let user approve via /ck:git
+- ❌ Forget to mention subagents — they did work that deserves credit/audit

package/.claude/skills/ckforensics/references/workflow-weekly-retro.md

@@ -0,0 +1,72 @@
+# Weekly Retro Workflow
+
+Pattern: every Sunday (or Monday morning), look back at the week — cost trends, skill discovery, runaway sessions.
+
+## Flow
+
+```
+1. ckforensics ingest                                 # ensure DB current
+2. ckforensics summary --days 7                       # weekly rollup
+3. ckforensics sessions --limit 20                    # week's sessions
+4. ckforensics suggest --days 7 --min-confidence 50   # patterns to fix
+5. ckforensics skills --unused | head -20             # discovery
+```
+
+## When Claude runs this skill
+
+User says one of:
+- "weekly retro"
+- "what did I spend on Claude Code this week"
+- "any patterns I should fix in my workflow"
+- "show me sessions ranked by cost"
+- "what skills should I learn"
+
+## What Claude should do
+
+1. **Summary numbers first** — cost, session count, vs previous week if possible (`--days 14` then compute delta).
+2. **Top 5 most expensive sessions** with project + duration. Flag anything over $50.
+3. **Recurring patterns** from `suggest --days 7`:
+   - List top 3 skill recommendations
+   - Group by pattern type (e.g. "read-fanout detected 4× this week")
+4. **Skill discovery**:
+   - From `skills --unused`, pick 3-5 that match user's project work (filter by keyword overlap with recent session topics)
+   - Format as "consider trying: /ck:xyz — <description>"
+5. **Anomaly check**:
+   - Any single session >$100? Flag for review.
+   - Any subagent that ran >1h? Worth investigating.
+6. **Optional: write retro to docs/**:
+   - `docs/retros/YYYY-MM-DD-week-N.md`
+   - Auto-fill summary + recommendations sections
+   - User edits notes manually after
+
+## Example response template
+
+```
+Weekly retro (Mon 2026-05-04 → Sun 2026-05-10):
+
+📊 Totals: $733 API-equivalent across 19 sessions, 967M tokens
+   vs prev week: +180% (last week $260 / 12 sessions)
+   
+🔥 Top sessions:
+   1. project-noname  18h56m  $1102  (Tue, 4082 events)
+   2. MQL5            2h21m   $29    (Tue)
+   3. career-launchpad 19h    $32    (Wed)
+
+📚 Skill recommendations:
+   - /ck:scout (4× read-fanout patterns this week — 50k tok save)
+   - /ck:test (3× test-loop patterns — 15k tok save)
+
+💡 Try these unused skills:
+   - /ck:retro — auto-generate this report (would replace this manual flow)
+   - /ck:journal — capture session reflections automatically
+   - /ck:debug — systematic debugging when stuck
+
+⚠️ Notable: session #1 was 18h Opus — consider checkpointing context mid-way.
+```
+
+## Anti-patterns
+
+- ❌ Compare cost to subscription price as if it's the bill — it's API-equivalent, frame as "value extracted"
+- ❌ Recommend ALL unused skills (150+) — filter to relevant per project context
+- ❌ Skip anomaly check — outliers are the highest-signal items
+- ❌ Long bullet lists — keep tight, 3-5 items per category max

package/.claude/skills/ckforensics/scripts/session-overview.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""
+session-overview.py — One-shot session report for ck:forensics skill.
+
+Runs multiple `ckforensics` CLI commands and stitches a single JSON
+report. Saves Claude from chaining 4-5 Bash calls when answering
+"summarize this session" prompts.
+
+Usage:
+    python3 session-overview.py [--session-id ID] [--days N]
+    python3 session-overview.py --last           # default — most recent session
+
+Output: JSON on stdout with shape:
+    {
+      "schema": "ck-forensics-overview-v1",
+      "generatedAt": "ISO8601",
+      "scope": {"sessionId": "...", "days": 7, "lastOnly": true},
+      "summary":   { ... },     # `ckforensics summary --json` data
+      "session":   { ... },     # one row from `ckforensics sessions --json`
+      "audit":     { ... },     # `ckforensics audit --json` (manifest)
+      "suggest":   [ ... ],     # top recs from `ckforensics suggest --json`
+      "map":       { ... }      # context map heatmap
+    }
+
+Errors are reported as {"schema": "error", "error": "..."} with exit 1.
+
+Stdlib only — no third-party deps required. Compatible with Python 3.8+.
+"""
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+
+def check_cli_installed() -> None:
+    """Verify ckforensics CLI is on PATH; exit 1 with clear error if not."""
+    if shutil.which("ckforensics") is None:
+        emit_error(
+            "ckforensics CLI not installed. "
+            "Install with: npm i -g ckforensics"
+        )
+        sys.exit(1)
+
+
+def run_cli(args: list) -> dict:
+    """
+    Run `ckforensics <args>` with --json and return parsed output.
+    Raises CalledProcessError on non-zero exit (caller decides whether to ignore).
+    """
+    cmd = ["ckforensics", *args, "--json"]
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=30,
+    )
+    if result.returncode != 0:
+        # Many subcommands exit 3 when no data — return empty rather than fail
+        if result.returncode == 3:
+            return {}
+        raise subprocess.CalledProcessError(
+            result.returncode, cmd, result.stdout, result.stderr
+        )
+    return json.loads(result.stdout) if result.stdout.strip() else {}
+
+
+def emit_error(msg: str) -> None:
+    """Write error envelope to stdout."""
+    print(json.dumps({"schema": "error", "error": msg}), flush=True)
+
+
+def collect_overview(session_id: str | None, days: int, last: bool) -> dict:
+    """Gather all sections; failures in individual sections become null."""
+    overview = {
+        "schema": "ck-forensics-overview-v1",
+        "generatedAt": datetime.now(timezone.utc).isoformat(),
+        "scope": {"sessionId": session_id, "days": days, "lastOnly": last},
+        "summary": None,
+        "session": None,
+        "audit": None,
+        "suggest": None,
+        "map": None,
+    }
+
+    # 1. Summary — rolling window
+    try:
+        overview["summary"] = run_cli(["summary", "--days", str(days)]).get("data")
+    except Exception as e:
+        overview["summary"] = {"error": str(e)}
+
+    # 2. Session metadata — pick from list or by id
+    try:
+        sessions_envelope = run_cli(["sessions", "--limit", "1"])
+        sessions = sessions_envelope.get("data", [])
+        if session_id:
+            # Filter to specific session if requested
+            sessions = [s for s in sessions if s.get("id") == session_id]
+        overview["session"] = sessions[0] if sessions else None
+    except Exception as e:
+        overview["session"] = {"error": str(e)}
+
+    # 3. Audit manifest — uses --last unless explicit id given
+    audit_args = ["audit", "--last"] if last or not session_id else ["audit", session_id]
+    try:
+        overview["audit"] = run_cli(audit_args)
+    except Exception as e:
+        overview["audit"] = {"error": str(e)}
+
+    # 4. Suggest — same scope as audit
+    suggest_args = ["suggest", "--last", "--min-confidence", "30", "--top", "3"]
+    if session_id and not last:
+        suggest_args = ["suggest", "--session", session_id, "--min-confidence", "30", "--top", "3"]
+    try:
+        overview["suggest"] = run_cli(suggest_args).get("data", [])
+    except Exception as e:
+        overview["suggest"] = {"error": str(e)}
+
+    # 5. Map — top-10 heatmap categories
+    map_args = ["map", "--last", "--top", "10"]
+    if session_id and not last:
+        map_args = ["map", session_id, "--top", "10"]
+    try:
+        overview["map"] = run_cli(map_args).get("data")
+    except Exception as e:
+        overview["map"] = {"error": str(e)}
+
+    return overview
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(
+        prog="session-overview",
+        description="Unified session report — runs multiple ckforensics commands and merges output.",
+    )
+    p.add_argument("--session-id", help="Explicit session UUID (defaults to --last)")
+    p.add_argument("--days", type=int, default=7, help="Summary window in days (default 7)")
+    p.add_argument(
+        "--last",
+        action="store_true",
+        default=True,
+        help="Use most recent session (default behavior)",
+    )
+    return p.parse_args()
+
+
+def main() -> int:
+    check_cli_installed()
+    args = parse_args()
+    last = args.last and not args.session_id
+
+    try:
+        overview = collect_overview(args.session_id, args.days, last)
+        print(json.dumps(overview, indent=2, default=str))
+        return 0
+    except Exception as e:
+        emit_error(f"unexpected error: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ckforensics",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "module": "index.ts",
   "type": "module",
   "bin": {
@@ -16,6 +16,8 @@
   "files": [
     "bin/",
     "scripts/postinstall.js",
+    "scripts/install-claudekit-skill.js",
+    ".claude/skills/",
     "README.md",
     "LICENSE"
   ],

package/scripts/install-claudekit-skill.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+/**
+ * install-claudekit-skill.js — Install the bundled `/ck:forensics` skill into
+ * the user's ClaudeKit skill directory (`~/.claude/skills/ckforensics/`).
+ *
+ * Called from postinstall.js. Designed to be silent on success and never
+ * fail the parent install — skill is a nice-to-have, not a hard dependency.
+ *
+ * Behavior:
+ *  - Copies `<pkg>/.claude/skills/ckforensics/` to `~/.claude/skills/ckforensics/`.
+ *  - Skip when source dir missing (e.g. dev install without the bundle).
+ *  - Skip on opt-out: `CKFORENSICS_SKIP_SKILL_INSTALL=1`.
+ *  - Existing skill dir is overwritten (idempotent re-install / version upgrade).
+ *  - Warnings to stderr only; never exits non-zero.
+ */
+
+import { existsSync, mkdirSync, cpSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(__dirname, "..");
+const SKILL_SOURCE = join(PKG_ROOT, ".claude", "skills", "ckforensics");
+const SKILL_TARGET = join(homedir(), ".claude", "skills", "ckforensics");
+
+function log(msg) {
+  // Single-line dim format to fit cleanly in npm install output
+  process.stderr.write(`[ckforensics:skill] ${msg}\n`);
+}
+
+function shouldSkip() {
+  // Explicit opt-out
+  if (process.env.CKFORENSICS_SKIP_SKILL_INSTALL === "1") {
+    log("skipped via CKFORENSICS_SKIP_SKILL_INSTALL=1");
+    return true;
+  }
+  // Source missing — dev install or trimmed tarball
+  if (!existsSync(SKILL_SOURCE)) {
+    log(`skill source not bundled (${SKILL_SOURCE}); skipping`);
+    return true;
+  }
+  return false;
+}
+
+function copySkill() {
+  // Ensure parent dir exists; cpSync recursive handles the rest.
+  mkdirSync(dirname(SKILL_TARGET), { recursive: true });
+
+  // Detect upgrade vs first install for friendlier message
+  const existing = existsSync(SKILL_TARGET);
+  cpSync(SKILL_SOURCE, SKILL_TARGET, {
+    recursive: true,
+    force: true,
+    // Don't overwrite if user has customised it (mtime-based heuristic)
+    // — but that's risky and confusing. For now: always overwrite, matches
+    // CLI versioning semantics (skill version pinned to CLI version).
+  });
+
+  const action = existing ? "updated" : "installed";
+  log(`${action} skill at ${SKILL_TARGET}`);
+  log("activate next Claude Code session: /ck:forensics");
+}
+
+try {
+  if (shouldSkip()) {
+    process.exit(0);
+  }
+  copySkill();
+} catch (err) {
+  // Never fail parent install over skill copy
+  log(`warning: skill install failed (${err.message}); continuing`);
+  process.exit(0);
+}

package/scripts/postinstall.js

@@ -234,4 +234,19 @@ async function main() {
   console.log(`[ckforensics] Run: ckforensics --help`);
 }
 
-main().catch((e) => fatal(String(e)));
+async function installSkill() {
+  // Best-effort: invoke the dedicated skill installer module. Failures here
+  // never block the binary install. Module handles its own opt-out + missing-
+  // source cases.
+  try {
+    await import("./install-claudekit-skill.js");
+  } catch (err) {
+    process.stderr.write(
+      `[ckforensics:skill] warning: failed to load skill installer (${err.message})\n`
+    );
+  }
+}
+
+main()
+  .then(installSkill)
+  .catch((e) => fatal(String(e)));