@inneranimalmedia/agentsam-sdk 1.8.0 → 1.9.0

package/DEVELOPMENT.md

@@ -1,4 +1,4 @@
-# Developing agentsam-sdk with Inner Animal Media
+# DEVELOPING AGENTSAM-SDK WITH INNER ANIMAL MEDIA
 
 ## Local smoke test
 

package/docs/RELEASES.iam-mirror.md

@@ -0,0 +1,20 @@
+# Agent Sam SDK — release pairings (IAM home)
+
+**Status:** Evergreen receipts · **Product:** [README.md](./README.md)
+
+Canonical npm-side table also lives in the SDK repo: `docs/RELEASES.md`.  
+**Keep both updated** when publishing (dual-home of the receipt).
+
+| npm version | Published (UTC) | IAM git SHA (40) | Notes |
+|-------------|-----------------|------------------|-------|
+| 1.7.0 | 2026-07-14 | _(pre-receipt)_ | Prior publish |
+| 1.9.0 | _(pending publish)_ | `fc1628505cb3c9946c149e4c468c2e264d6f381e` | `repository.inspect` + `--dupes`; mirrored from IAM agentsam-sdk |
+| 1.8.0 | 2026-08-02T13:57:12.080Z | `580547301e370b77ec26bd72558979d335feedd9` | `python/` + `protocol/` in tarball; `repository.scan_bloat`; shell-kit under `packages/` |
+
+**Latest pairing (ready to publish):** `iam@fc1628505cb3c9946c149e4c468c2e264d6f381e` ↔ `@inneranimalmedia/agentsam-sdk@1.9.0`
+
+### Receipt rules
+
+- Full 40-char SHA only (AGENTS.md §3)
+- Record the IAM SHA that introduced or mirrored the consumer-facing change
+- Tag SDK repo `vX.Y.Z` on publish

package/docs/RELEASES.md

@@ -3,4 +3,7 @@
 | npm version | Published (UTC) | IAM git SHA (40) | Notes |
 |-------------|-----------------|------------------|-------|
 | 1.7.0 | 2026-07-14 | _(pre-receipt)_ | Prior publish |
-| 1.8.0 | _(pending publish)_ | `580547301e370b77ec26bd72558979d335feedd9` | `python/` + `protocol/` in npm `files`; `repository.scan_bloat`; shell-kit folded to `packages/agentsam-shell-kit` (private) |
+| 1.9.0 | _(pending publish)_ | `fc1628505cb3c9946c149e4c468c2e264d6f381e` | `python/agentsam_sdk/repository/inspect.py` (`--dupes`); CLI `agentsam repository inspect` |
+| 1.8.0 | 2026-08-02T13:57:12.080Z | `580547301e370b77ec26bd72558979d335feedd9` | `python/` + `protocol/` in npm `files`; `repository.scan_bloat`; shell-kit folded to `packages/agentsam-shell-kit` (private). SDK git at publish: `ac52669b89ddb16fad87c42fe53f2c93ef13bd1a`. |
+
+**Pairing (ready to publish):** `iam@fc1628505cb3c9946c149e4c468c2e264d6f381e` ↔ `@inneranimalmedia/agentsam-sdk@1.9.0`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@inneranimalmedia/agentsam-sdk",
-  "version": "1.8.0",
-  "description": "Agent Sam is a full-stack AI agent SDK for autonomous task execution — covering data management, creative workflows, design commands, and multi-step agentic pipelines.",
+  "version": "1.9.0",
+  "description": "Agent Sam is a full-stack AI agent SDK for autonomous task execution \u2014 covering data management, creative workflows, design commands, and multi-step agentic pipelines.",
   "type": "module",
   "main": "./src/index.js",
   "exports": {

package/python/agentsam_sdk/cli.py

@@ -6,6 +6,7 @@ convention: Python tooling here is stdlib-only).
   agentsam repository inventory --repo-root .. --output-dir /tmp/scan --format json
   agentsam repository inventory --repo-root .. --format json | jq '.data.totals'
   agentsam repository scan-bloat --root src --min-kb 10 --top 30 --format json
+  agentsam repository inspect --repo-root . --json --dupes | jq '.duplicates'
 """
 from __future__ import annotations
 
@@ -54,8 +55,7 @@ def _cmd_data_d1_bloat(args: argparse.Namespace) -> int:
         mode=mode,
         params={
             "db": args.db, "config": args.config, "repo_root": args.repo_root,
-            "prefix": args.prefix, "workers": args.workers,
-            "count_only": args.count_only, "top": args.top,
+            "prefix": args.prefix, "workers": args.workers, "top": args.top,
         },
         output_dir=args.output_dir,
     )
@@ -123,6 +123,36 @@ def _cmd_repository_scan_bloat(args: argparse.Namespace) -> int:
     return 0 if result.ok else 1
 
 
+def _cmd_repository_inspect(args: argparse.Namespace) -> int:
+    from agentsam_sdk.repository import inspect as repo_inspect
+
+    argv: list[str] = []
+    if args.repo_root:
+        argv.extend(["--repo-root", args.repo_root])
+    want_text = bool(args.text) or args.format in ("text", "markdown")
+    want_json = bool(args.json) or args.format == "json" or not want_text
+    if want_json and not want_text:
+        argv.append("--json")
+    if want_text and not want_json:
+        argv.append("--text")
+    if want_text and want_json:
+        # Explicit both → JSON wins (machine default) unless only --text
+        argv.append("--json")
+    if args.dupes:
+        argv.append("--dupes")
+    if args.all:
+        argv.append("--all")
+    if args.since:
+        argv.extend(["--since", args.since])
+    if args.recent is not None:
+        argv.extend(["--recent", str(args.recent)])
+    if args.largest is not None:
+        argv.extend(["--largest", str(args.largest)])
+    if args.out:
+        argv.extend(["--out", args.out])
+    return repo_inspect.main_cli(argv)
+
+
 def build_parser() -> argparse.ArgumentParser:
     ap = argparse.ArgumentParser(prog="agentsam", description="agentsam_sdk CLI")
     sub = ap.add_subparsers(dest="group", required=True)
@@ -130,16 +160,20 @@ def build_parser() -> argparse.ArgumentParser:
     data = sub.add_parser("data", help="D1 data audits")
     data_sub = data.add_subparsers(dest="cmd", required=True)
 
-    bloat = data_sub.add_parser("d1-bloat", help="find largest/text-heavy D1 tables")
+    bloat = data_sub.add_parser(
+        "d1-bloat",
+        help="database-scoped D1 audit (--quick=counts, --full=text sizes)",
+    )
     bloat.add_argument("--db", help="D1 database name (else AGENTSAM_D1_DB_NAME)")
     bloat.add_argument("--config", help="wrangler config path (else AGENTSAM_WRANGLER_CONFIG)")
     bloat.add_argument("--repo-root", help="repo root wrangler runs from")
-    bloat.add_argument("--quick", action="store_true", default=True)
-    bloat.add_argument("--full", action="store_true")
-    bloat.add_argument("--prefix")
+    bloat.add_argument("--quick", action="store_true", default=True,
+                       help="All tables: COUNT(*) only (default)")
+    bloat.add_argument("--full", action="store_true",
+                       help="All tables: row counts + text/JSON LENGTH estimates")
+    bloat.add_argument("--prefix", help="Only tables whose name starts with this prefix")
     bloat.add_argument("--workers", type=int, default=6)
     bloat.add_argument("--top", type=int, default=40)
-    bloat.add_argument("--count-only", action="store_true")
     bloat.add_argument("--output-dir")
     bloat.add_argument("--format", choices=["json", "markdown"], default="markdown")
     bloat.set_defaults(func=_cmd_data_d1_bloat)
@@ -199,6 +233,22 @@ def build_parser() -> argparse.ArgumentParser:
     )
     sb.set_defaults(func=_cmd_repository_scan_bloat)
 
+    insp = repo_sub.add_parser(
+        "inspect",
+        help="file walk: sizes + dates (+ optional --dupes SHA-256 groups)",
+    )
+    insp.add_argument("--repo-root", default=None)
+    insp.add_argument("--format", choices=["json", "markdown", "text"], default="json")
+    insp.add_argument("--json", action="store_true")
+    insp.add_argument("--text", action="store_true")
+    insp.add_argument("--dupes", action="store_true")
+    insp.add_argument("--all", action="store_true")
+    insp.add_argument("--since", default=None)
+    insp.add_argument("--recent", type=int, default=50)
+    insp.add_argument("--largest", type=int, default=30)
+    insp.add_argument("--out", default=None)
+    insp.set_defaults(func=_cmd_repository_inspect)
+
     return ap
 
 

package/python/agentsam_sdk/data/d1_bloat.py

@@ -1,54 +1,56 @@
 """agentsam_sdk.data.d1_bloat -- port of scripts/d1_bloat_audit.py.
 
-Finds largest / text-heavy D1 tables via row counts + SUM(LENGTH(text_col))
-(D1 remote has no dbstat, so this is an estimate, not exact page bytes).
+Database-scoped D1 size audit (not tenant/workspace). Walks one CF D1 database.
+
+Modes:
+  quick  — every user table + COUNT(*) only
+  full   — same tables + SUM(LENGTH(...)) on text-ish columns + briefing
+
+D1 remote has no dbstat; sizes are LENGTH estimates, not exact page bytes.
 
 Deferred from the legacy script (see docs/gaps.md): --email/Resend delivery.
-This module writes json + markdown only; wire up email at the CLI/ops layer
-if still wanted -- keeps this module free of a RESEND_API_KEY dependency.
+This module writes json + markdown only.
 """
 from __future__ import annotations
 
+import json
 import re
 from concurrent.futures import ThreadPoolExecutor, as_completed
-from dataclasses import dataclass, field, asdict
+from dataclasses import asdict, dataclass, field
 from datetime import datetime, timezone
-from pathlib import Path
 from typing import Any, Optional
 
 from agentsam_sdk.data.d1_adapter import D1Adapter, D1AdapterError
-from agentsam_sdk.runtime.contract import ToolInput, ToolResult, write_receipt, start_timer
+from agentsam_sdk.runtime.contract import ToolInput, ToolResult, start_timer, write_receipt
 
 TOOL_NAME = "data.d1_bloat"
 
+# Prefer payload-ish TEXT columns when measuring LENGTH (full mode).
 BLOAT_COL_RE = re.compile(
     r"(body|content|value|markdown|_json\b|schema|payload|output|prompt|message|"
     r"text|config|metadata|description|notes|script|summary|arguments|result|"
     r"attributes|events|resource|handler|input_|output_|sql\b|embedding|merged_)",
     re.I,
 )
-SKIP_COL_RE = re.compile(
-    r"(^id$|_id$|_at$|_at_epoch$|_hash$|_key$|_uuid$|_ref$|_url$|_path$|_email$|"
-    r"_slug$|_name$|_type$|_status$|_mode$|_token$|tenant_id|workspace_id|user_id)",
-    re.I,
-)
-QUICK_TABLE_RE = re.compile(
-    r"^(agentsam_|otlp_|system_health|deployment|terminal_|cms_|worker_analytics|"
-    r"ai_api_test|dashboard_versions|semantic_search)",
-    re.I,
-)
 
-# Table-name -> rollup guidance. Naming convention hints, not identity/secrets;
-# safe to ship. Extend freely -- this is documentation, not config.
 ROLLUP_HINTS: dict[str, str] = {
     "agentsam_tool_call_log": "Archive/purge output_json + input_json >30d; keep output_summary + ids.",
-    "agentsam_tool_chain": "result_json dominates -- rollup to object storage or truncate JSON.",
-    "agentsam_tool_cache": "Cache table -- enforce TTL + max rows.",
-    "agentsam_workflow_runs": "Move step_results_json to R2 artifact; D1 row = pointer + status + cost.",
-    "agentsam_scripts": "body must stay empty; canonical source in R2 (source_stored=r2:...).",
-    "agentsam_skill": "Large SKILL.md -> R2; D1 = metadata + retrieval_strategy=r2.",
-    "agentsam_memory": "value is prose -- OK for pinned rows; vectors live in Supabase/Vectorize.",
-    "otlp_traces": "Retention policy on attributes_json; sample or export to observability backend.",
+    "agentsam_tool_chain": "result_json dominates — rollup to R2 or truncate; keep summaries.",
+    "agentsam_tool_cache": "Enforce TTL + max rows; output_json must not grow unbounded.",
+    "agentsam_mcp_tool_execution": "Archive old output_json; mirror tool_call_log policy.",
+    "agentsam_execution_steps": "Archive input/output JSON after workflow completes.",
+    "agentsam_workflow_runs": "Move step_results_json to R2; D1 row = pointer + status + cost.",
+    "agentsam_webhook_events": "Rollup payload_json; retain type + ts + external id.",
+    "agentsam_scripts": "body must stay empty; canonical source in R2 (source_stored=r2:…).",
+    "agentsam_skill": "Large SKILL.md → R2; D1 = metadata + retrieval_strategy=r2.",
+    "agentsam_memory": "Archive stale prose; vectors live in Supabase/Vectorize, not D1.",
+    "agentsam_rules_document": "body_markdown → R2; D1 = trigger + key + short summary.",
+    "agentsam_cron_runs": "Trim metadata_json on old runs.",
+    "agentsam_hook_execution": "Archive payload_json; keep hook id + status.",
+    "agentsam_eval_runs": "Cap grader notes; long artifacts → Supabase eval tables.",
+    "otlp_traces": "Retention on attributes_json; sample or export off-D1.",
+    "terminal_history_archive_431": "Archive scrollback to R2 or cap rows per connection.",
+    "system_health_snapshots": "Shorten retention or aggregate further.",
 }
 
 
@@ -73,40 +75,55 @@ class TableStat:
         if self.name in ROLLUP_HINTS:
             return ROLLUP_HINTS[self.name]
         if self.text_bytes > 500_000 and any(
-            c.name in ("body", "content_markdown", "value", "output_json", "result_json", "payload_json")
+            c.name
+            in (
+                "body",
+                "content_markdown",
+                "value",
+                "output_json",
+                "result_json",
+                "payload_json",
+            )
             for c in self.columns
         ):
-            return "Large text/JSON in D1 -- prefer R2 pointer + vector lanes for search."
+            return "Large text/JSON in D1 — prefer R2 pointer + vector lanes for search."
         return None
 
 
-def _pick_bloat_columns(cols: list[tuple[str, str]], max_cols: int = 8) -> list[str]:
-    out: list[str] = []
-    for name, typ in cols:
-        if typ not in ("TEXT", "BLOB", "JSON"):
-            continue
-        if SKIP_COL_RE.search(name):
-            continue
-        if BLOAT_COL_RE.search(name):
-            out.append(name)
-    return out[:max_cols]
+def _pick_measure_columns(cols: list[tuple[str, str]], max_cols: int = 12) -> list[str]:
+    """TEXT/BLOB/JSON columns to LENGTH-scan. Prefer payload-ish names; else any text cols."""
+    textish = [
+        n
+        for n, typ in cols
+        if (typ or "TEXT").upper() in ("TEXT", "BLOB", "JSON") or "CHAR" in (typ or "").upper()
+    ]
+    preferred = [n for n in textish if BLOAT_COL_RE.search(n)]
+    chosen = preferred if preferred else textish
+    return chosen[:max_cols]
 
 
 def _scan_table(adapter: D1Adapter, table: str, analyze_text: bool) -> TableStat:
     stat = TableStat(name=table)
     try:
+        if not analyze_text:
+            stat.row_count = adapter.row_count(table)
+            stat.est_bytes = stat.row_count * 120
+            return stat
+
         cols = adapter.table_columns(table)
-        bloat_cols = _pick_bloat_columns(cols) if analyze_text else []
-        if bloat_cols:
-            parts = [f'SUM(LENGTH(COALESCE("{c}", \'\'))) AS "{c}"' for c in bloat_cols]
-            max_parts = [f'MAX(LENGTH(COALESCE("{c}", \'\'))) AS "m_{c}"' for c in bloat_cols]
+        measure = _pick_measure_columns(cols)
+        if measure:
+            parts = [f'SUM(LENGTH(COALESCE("{c}", \'\'))) AS "{c}"' for c in measure]
+            max_parts = [f'MAX(LENGTH(COALESCE("{c}", \'\'))) AS "m_{c}"' for c in measure]
             sql = f'SELECT COUNT(*) AS rc, {", ".join(parts + max_parts)} FROM "{table}"'
             row = adapter.query(sql)[0]
             stat.row_count = int(row.get("rc") or 0)
-            for c in bloat_cols:
+            for c in measure:
                 b = int(row.get(c) or 0)
                 if b:
-                    stat.columns.append(ColStat(name=c, bytes=b, max_len=int(row.get(f"m_{c}") or 0)))
+                    stat.columns.append(
+                        ColStat(name=c, bytes=b, max_len=int(row.get(f"m_{c}") or 0))
+                    )
             stat.text_bytes = sum(c.bytes for c in stat.columns)
             stat.est_bytes = stat.text_bytes if stat.text_bytes else stat.row_count * 120
         else:
@@ -127,10 +144,45 @@ def _fmt_bytes(n: int) -> str:
     return f"{n} B"
 
 
-def _flag_suspicious(stats: list[TableStat]) -> list[dict[str, Any]]:
-    flags: list[dict[str, Any]] = []
-    ranked = sorted(stats, key=lambda s: s.text_bytes or s.est_bytes, reverse=True)
+def _build_findings(stats: list[TableStat], mode: str) -> list[dict[str, Any]]:
+    findings: list[dict[str, Any]] = []
+    if mode == "quick":
+        ranked = sorted(stats, key=lambda s: s.row_count, reverse=True)
+        for s in ranked[:40]:
+            if s.error:
+                findings.append(
+                    {
+                        "severity": "medium",
+                        "table": s.name,
+                        "rows": s.row_count,
+                        "est_bytes": 0,
+                        "est_human": "—",
+                        "why": f"scan_error: {s.error[:120]}",
+                        "next_steps": ["Re-run --full for this table after fixing access."],
+                    }
+                )
+                continue
+            if s.row_count < 50_000:
+                continue
+            sev = "high" if s.row_count >= 100_000 else "medium"
+            findings.append(
+                {
+                    "severity": sev,
+                    "table": s.name,
+                    "rows": s.row_count,
+                    "est_bytes": s.est_bytes,
+                    "est_human": _fmt_bytes(s.est_bytes),
+                    "why": f"High row count ({s.row_count:,}) — run --full to size text/JSON.",
+                    "next_steps": [
+                        f"agentsam data d1-bloat --full --prefix {s.name}",
+                        "Confirm retention / archive policy for this table.",
+                    ],
+                }
+            )
+        return findings
+
     total_text = sum(s.text_bytes for s in stats) or 1
+    ranked = sorted(stats, key=lambda s: s.text_bytes or s.est_bytes, reverse=True)
     for s in ranked[:80]:
         est = s.text_bytes or s.est_bytes
         reasons: list[str] = []
@@ -144,121 +196,249 @@ def _flag_suspicious(stats: list[TableStat]) -> list[dict[str, Any]]:
             reasons.append("known_rollup_candidate")
         if s.error:
             reasons.append(f"scan_error:{s.error[:80]}")
-        if reasons:
-            flags.append({
-                "table": s.name, "rows": s.row_count, "est_bytes": est,
+        if not reasons:
+            continue
+        steps = []
+        if s.rollup_hint:
+            steps.append(s.rollup_hint)
+        else:
+            steps.append("Inspect top text columns; archive or move large payloads to R2.")
+        steps.append("Cap writers at source (result ceilings / retention).")
+        findings.append(
+            {
+                "severity": "high"
+                if est >= 5_000_000 or s.row_count >= 100_000
+                else "medium",
+                "table": s.name,
+                "rows": s.row_count,
+                "est_bytes": est,
                 "est_human": _fmt_bytes(est),
-                "severity": "high" if est >= 5_000_000 or s.row_count >= 100_000 else "medium",
-                "reasons": reasons, "hint": s.rollup_hint,
-            })
-    return flags
+                "why": "; ".join(reasons),
+                "next_steps": steps,
+                "top_columns": [
+                    {"name": c.name, "bytes": c.bytes, "human": _fmt_bytes(c.bytes)}
+                    for c in sorted(s.columns, key=lambda x: x.bytes, reverse=True)[:5]
+                ],
+            }
+        )
+    return findings
+
+
+def _build_doing_well(
+    stats: list[TableStat], findings: list[dict[str, Any]]
+) -> list[dict[str, str]]:
+    flagged = {f["table"] for f in findings}
+    well: list[dict[str, str]] = []
+    small = [s for s in stats if not s.error and s.row_count < 1_000 and s.name not in flagged]
+    if small:
+        well.append(
+            {
+                "area": "small_tables",
+                "why": f"{len(small)} tables under 1k rows and not flagged — fine for registry/config.",
+            }
+        )
+    empty = sum(1 for s in stats if not s.error and s.row_count == 0)
+    if empty:
+        well.append(
+            {
+                "area": "empty_tables",
+                "why": f"{empty} empty tables (candidates to drop later, not urgent).",
+            }
+        )
+    if not findings:
+        well.append(
+            {"area": "no_flags", "why": "No high/medium bloat heuristics fired on this pass."}
+        )
+    return well
 
 
-def _render_markdown(stats: list[TableStat], db_size, mode, table_total, scanned) -> str:
+def _build_briefing(
+    stats: list[TableStat],
+    findings: list[dict[str, Any]],
+    doing_well: list[dict[str, str]],
+    db_name: str,
+    db_size: Optional[str],
+    mode: str,
+    table_total: int,
+) -> str:
+    high = sum(1 for f in findings if f["severity"] == "high")
+    med = sum(1 for f in findings if f["severity"] == "medium")
+    verdict = "needs_attention" if high or med else "healthy"
     lines = [
-        "# D1 bloat audit",
+        f"# D1 health — {db_name}",
         "",
         f"- **Generated:** {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}",
+        f"- **Mode:** {mode} (database-scoped; not tenant/workspace)",
         f"- **Reported DB size:** {db_size or 'unknown'}",
-        f"- **Mode:** {mode}",
-        f"- **Tables in DB:** {table_total}",
-        f"- **Tables scanned:** {scanned}",
-        f"- **Estimated text payload (scanned):** {_fmt_bytes(sum(s.text_bytes for s in stats))}",
-        "",
-        "> D1 remote has no `dbstat`. Sizes are `SUM(LENGTH(text_col))` estimates.",
-        "",
-        "## Top tables by estimated text bytes",
+        f"- **Tables:** {table_total} scanned",
+        f"- **Verdict:** {verdict} ({high} high / {med} medium findings)",
         "",
-        "| Rank | Table | Rows | Text est. | Top columns | Rollup hint |",
-        "|------|-------|------|-----------|-------------|-------------|",
     ]
-    ranked = sorted(stats, key=lambda s: s.est_bytes, reverse=True)
-    for i, s in enumerate(ranked[:40], 1):
-        top_cols = ", ".join(
-            f"`{c.name}` {_fmt_bytes(c.bytes)}"
-            for c in sorted(s.columns, key=lambda x: x.bytes, reverse=True)[:3]
+    if mode == "quick":
+        lines.append(
+            "> Quick = row counts only. Run `--full` for text/JSON size estimates and rollup guidance."
+        )
+        lines.append("")
+    else:
+        lines.append(
+            f"> Full text estimate (scanned columns): {_fmt_bytes(sum(s.text_bytes for s in stats))}."
         )
-        hint = (s.rollup_hint or "").replace("|", "/")[:80]
-        err = f" ⚠ {s.error}" if s.error else ""
         lines.append(
-            f"| {i} | `{s.name}` | {s.row_count:,} | {_fmt_bytes(s.text_bytes or s.est_bytes)} | "
-            f"{top_cols or '—'} | {hint or '—'}{err} |"
+            "> D1 remote has no `dbstat` — sizes are `SUM(LENGTH(...))`, not exact page bytes."
         )
+        lines.append("")
+
+    lines.append("## What's fine")
+    lines.append("")
+    if doing_well:
+        for w in doing_well:
+            lines.append(f"- **{w['area']}:** {w['why']}")
+    else:
+        lines.append("- (nothing notable)")
+    lines.append("")
+
+    lines.append("## What's bloated / needs attention")
+    lines.append("")
+    if not findings:
+        lines.append("- None flagged on this pass.")
+    else:
+        for i, f in enumerate(findings[:25], 1):
+            lines.append(
+                f"{i}. **`{f['table']}`** [{f['severity']}] — "
+                f"rows={f['rows']:,}, est={f['est_human']}"
+            )
+            lines.append(f"   - Why: {f['why']}")
+            for step in f.get("next_steps") or []:
+                lines.append(f"   - Next: {step}")
+    lines.append("")
+
+    lines.append("## Next steps (global)")
+    lines.append("")
+    if mode == "quick":
+        lines.append("1. `agentsam data d1-bloat --full --format json` for size + column detail.")
+        lines.append("2. Prioritize tables with ≥100k rows from the inventory above.")
+    else:
+        lines.append("1. Act on high findings first (archive / R2 / writer caps).")
+        lines.append("2. Re-run `--quick` weekly for row-count drift; `--full` after large ingest.")
+        lines.append("3. Prefer D1 for pointers + state; R2 for bytes; Vectorize/Supabase for search.")
     lines.append("")
     return "\n".join(lines)
 
 
 def run(tool_input: ToolInput) -> ToolResult:
     started = start_timer()
+    tool_input.assert_read_only()
     p = tool_input.params
     mode = tool_input.mode if tool_input.mode in ("quick", "full") else "quick"
     prefix = p.get("prefix")
     workers = int(p.get("workers", 6))
-    count_only = bool(p.get("count_only", False))
     top = int(p.get("top", 40))
+    analyze_text = mode == "full"
 
     output_dir = tool_input.output_path()
 
     try:
         adapter = D1Adapter.from_env(
-            db_name=p.get("db"), wrangler_config=p.get("config"), repo_root=p.get("repo_root")
+            db_name=p.get("db"),
+            wrangler_config=p.get("config"),
+            repo_root=p.get("repo_root"),
         )
         all_tables = adapter.list_tables()
+        tables = all_tables
         if prefix:
-            tables = [t for t in all_tables if t.lower().startswith(prefix.lower())]
-        elif mode == "quick":
-            tables = [t for t in all_tables if QUICK_TABLE_RE.match(t)]
-        else:
-            tables = all_tables
+            tables = [t for t in all_tables if t.lower().startswith(str(prefix).lower())]
 
         db_size = adapter.database_size()
         stats: list[TableStat] = []
         with ThreadPoolExecutor(max_workers=max(1, workers)) as pool:
-            futures = {pool.submit(_scan_table, adapter, t, not count_only): t for t in tables}
+            futures = {
+                pool.submit(_scan_table, adapter, t, analyze_text): t for t in tables
+            }
             for fut in as_completed(futures):
                 try:
                     stats.append(fut.result())
                 except Exception as e:  # noqa: BLE001
                     stats.append(TableStat(name=futures[fut], error=str(e)))
 
-        stats.sort(key=lambda s: s.est_bytes, reverse=True)
-        flags = _flag_suspicious(stats)
-        md = _render_markdown(stats, db_size, mode, len(all_tables), len(tables))
+        if mode == "quick":
+            stats.sort(key=lambda s: s.row_count, reverse=True)
+        else:
+            stats.sort(key=lambda s: s.text_bytes or s.est_bytes, reverse=True)
+
+        findings = _build_findings(stats, mode)
+        doing_well = _build_doing_well(stats, findings)
+        high = sum(1 for f in findings if f["severity"] == "high")
+        med = sum(1 for f in findings if f["severity"] == "medium")
+        verdict = "needs_attention" if high or med else "healthy"
+        md = _build_briefing(
+            stats, findings, doing_well, adapter.db_name, db_size, mode, len(tables)
+        )
 
-        artifacts: list[str] = []
         json_payload = {
             "database": adapter.db_name,
-            "database_size": db_size,
+            "scope": "database",
             "mode": mode,
+            "verdict": verdict,
+            "database_size": db_size,
             "tables_total": len(all_tables),
             "tables_scanned": len(tables),
             "estimated_text_bytes": sum(s.text_bytes for s in stats),
-            "flags": flags,
+            "doing_well": doing_well,
+            "findings": findings,
+            "next_steps_global": (
+                [
+                    "agentsam data d1-bloat --full --format json",
+                    "Act on tables with ≥100k rows first",
+                ]
+                if mode == "quick"
+                else [
+                    "Act on high findings (archive / R2 / writer caps)",
+                    "Re-run --quick weekly for row drift",
+                ]
+            ),
             "tables": [
-                {**{k: v for k, v in asdict(s).items() if k != "columns"},
-                 "columns": [asdict(c) for c in s.columns], "rollup_hint": s.rollup_hint}
+                {
+                    **{k: v for k, v in asdict(s).items() if k != "columns"},
+                    "columns": [asdict(c) for c in s.columns],
+                    "rollup_hint": s.rollup_hint,
+                }
                 for s in stats[:top]
             ],
         }
+
+        artifacts: list[str] = []
         if output_dir:
             output_dir.mkdir(parents=True, exist_ok=True)
             (output_dir / "d1-bloat.md").write_text(md, encoding="utf-8")
             (output_dir / "d1-bloat.json").write_text(
-                __import__("json").dumps(json_payload, indent=2), encoding="utf-8"
+                json.dumps(json_payload, indent=2), encoding="utf-8"
             )
             artifacts = [str(output_dir / "d1-bloat.md"), str(output_dir / "d1-bloat.json")]
 
         result = ToolResult(
-            ok=True, tool=TOOL_NAME, mode=mode, request_id=tool_input.request_id,
-            started_at=started, finished_at=start_timer(),
-            summary=f"Scanned {len(tables)}/{len(all_tables)} tables, {len(flags)} flagged.",
-            data=json_payload, artifacts=artifacts,
+            ok=True,
+            tool=TOOL_NAME,
+            mode=mode,
+            request_id=tool_input.request_id,
+            started_at=started,
+            finished_at=start_timer(),
+            summary=(
+                f"Scanned {len(tables)}/{len(all_tables)} tables "
+                f"(mode={mode}, verdict={verdict}, findings={len(findings)})."
+            ),
+            data=json_payload,
+            artifacts=artifacts,
         )
     except D1AdapterError as e:
         result = ToolResult(
-            ok=False, tool=TOOL_NAME, mode=mode, request_id=tool_input.request_id,
-            started_at=started, finished_at=start_timer(),
-            summary="D1 adapter error", error=str(e),
+            ok=False,
+            tool=TOOL_NAME,
+            mode=mode,
+            request_id=tool_input.request_id,
+            started_at=started,
+            finished_at=start_timer(),
+            summary="D1 adapter error",
+            error=str(e),
         )
 
     write_receipt(result, output_dir)