Upload 3 files

DOCS.md

@@ -1,18 +1,18 @@
 # voice — Help
 
-Generated from `voice --help` and `voice <cmd> --help` (v2.0.0, 11 commands).
+Generated from `voice --help` and `voice <cmd> --help` (v2.1.0, 12 commands).
 
 ## voice --help
 
 ```
 usage: voice [-h] [-v] [--non-interactive] [--version]
              [--completion {bash,zsh,fish}]
-             {get,cast,tensor,delta,list,info,remove,cleanup,auth,path,doctor} ...
+             {get,cast,tensor,delta,list,info,remove,cleanup,auth,report,path,doctor} ...
 
 Lift a model's voice and cast it onto another model.
 
 positional arguments:
-  {get,cast,tensor,delta,list,info,remove,cleanup,auth,path,doctor}
+  {get,cast,tensor,delta,list,info,remove,cleanup,auth,report,path,doctor}
     get                 Get a voice from a model (safetensors repo, .gguf, or URL)
     cast                Cast a voice onto a .gguf or .safetensors file
     tensor              Extract or cast any named tensor
@@ -22,6 +22,7 @@ positional arguments:
     remove              Remove a stored voice
     cleanup             Remove incomplete downloads
     auth                Save your HF token (optional)
+    report              Save a report locally and optionally share to community
     path                Put voice on your PATH
     doctor              Check your setup
 
@@ -180,6 +181,36 @@ options:
   --show      Show if token is present (masked)
 ```
 
+## voice report
+
+```
+usage: voice report [-h] [--message MESSAGE] [--voice VOICE] [--target TARGET]
+                    [--reporter REPORTER] [--yes] [--no-push] [--sync]
+
+Save a report locally and optionally share to community (Wiself/voice-reports)
+
+positional arguments:
+  --message, -m MESSAGE
+                        Freeform note (240ch, sanitized, CSV-injection safe)
+  --voice VOICE         Voice name context
+  --target TARGET       Target file basename context (no PII path)
+  --reporter REPORTER   Reporter id (optional, 64ch sanitized)
+
+options:
+  -h, --help  show this help message and exit
+  --yes                 Non-interactive: auto-share to community
+  --no-push             Local only, skip share prompt
+  --sync                Sync pending outbox to community
+
+After local save (flock+fsync JSONL at ~/.voices/reports.jsonl, 0600), prompts:
+  Share to community reports (Wiself/voice-reports)? [y/N]
+Waits for explicit y/n, no timeout. Non-interactive skips unless --yes.
+Local: outbox retained at ~/.voices/outbox/<id>.json until shared.
+Remote: Wiself/voice-reports dataset, data/reports-YYYY-MM.jsonl, merge-append
+with dedup on report_id, 3 retries on 429/409. Offline keeps outbox.
+Doctor shows reports N local, M pending, and community target.
+```
+
 ## voice path
 
 ```

README.md

@@ -120,7 +120,7 @@ A delta carries only the difference from its base, so it blends more gently with
 
 ## Commands
 
-Commands. One idea each — 11 commands, `voice --help` is the source of truth (`DOCS.md` generated from live `voice.py` v2.0.0):
+Commands. One idea each — 12 commands, `voice --help` is the source of truth (`DOCS.md` generated from live `voice.py` v2.1.0):
 
 | Command | Description | Source |
 |---|---|---|
@@ -129,13 +129,14 @@ Commands. One idea each — 11 commands, `voice --help` is the source of truth (
 | `voice tensor get <source> --tensor <n>` | Extract **any** named tensor to a standalone artifact (safetensors or gguf for quant) | `voice.py:1890` `cmd_tensor_get` |
 | `voice tensor cast <target> <file>` | Cast **any** named tensor onto a `.gguf` or `.safetensors` file | `voice.py:1942` `cmd_tensor_cast` |
 | `voice delta [name]` | Make a portable style (`voice − base` → `F16` delta) you can reuse across compatible models | `voice.py:1999` `cmd_delta` |
-| `voice list [base]` | Show saved voices — `voice list base` shows cached base heads | `voice.py:2289` `cmd_list` |
-| `voice info <voice>` | Show details for a saved voice, delta, or cached base | `voice.py:2303` `cmd_info` |
-| `voice remove <voice>` | Remove a voice from your library | `voice.py:2347` `cmd_remove` |
-| `voice cleanup [--force]` | Remove incomplete downloads (`.parts`) — skips active (<10 min) unless `--force` | `voice.py:2365` `cmd_cleanup` |
-| `voice auth [--show\|--clear]` | Save your HF token (0600, optional, faster/verified) | `voice.py:2388` `cmd_auth` |
-| `voice path` | Put `voice` on your PATH (symlink to `/usr/local/bin` or `~/.local/bin`) | `voice.py:2435` `cmd_path` |
-| `voice doctor` | Check your setup — Python + uv + venv + disk + HF token + connectivity | `voice.py:2471` `cmd_doctor` |
+| `voice list [base]` | Show saved voices — `voice list base` shows cached base heads | `voice.py:2295` `cmd_list` |
+| `voice info <voice>` | Show details for a saved voice, delta, or cached base | `voice.py:2309` `cmd_info` |
+| `voice remove <voice>` | Remove a voice from your library | `voice.py:2353` `cmd_remove` |
+| `voice cleanup [--force]` | Remove incomplete downloads (`.parts`) — skips active (<10 min) unless `--force` | `voice.py:2371` `cmd_cleanup` |
+| `voice report [--voice X] [-m MSG]` | Save report locally (flock+fsync JSONL `~/.voices/reports.jsonl` + outbox 0600) and optionally share to `Wiself/voice-reports` — prompt `[y/N]` waits for explicit y/n, no timeout; `--yes` auto-share, `--no-push` local-only, `--sync` flushes outbox | `voice.py:2646` `cmd_report` |
+| `voice auth [--show\|--clear]` | Save your HF token (0600, optional, faster/verified) | `voice.py:2718` `cmd_auth` |
+| `voice path` | Put `voice` on your PATH (symlink to `/usr/local/bin` or `~/.local/bin`) | `voice.py:2816` `cmd_path` |
+| `voice doctor` | Check your setup — Python + uv + venv + disk + HF token + connectivity + reports/outbox + community target | `voice.py:2852` `cmd_doctor` |
 
 Example:
 
@@ -153,7 +154,19 @@ voice list base
 voice cast ./model.gguf styletune-v2 --out ./voiced/
 ```
 
-> `delta-` is reserved. Voice names cannot start with it. Deltas always do. Full CLI reference: [`DOCS.md`](./DOCS.md) (generated from `voice --help`, 11 commands). Names are lowercased when saved.
+> `delta-` is reserved. Voice names cannot start with it. Deltas always do. Full CLI reference: [`DOCS.md`](./DOCS.md) (generated from `voice --help`, 12 commands). Names are lowercased when saved.
+
+### Why report exists — a tiny hope
+
+We didn't add `voice report` to be clever. Just — if each of us leaves a one-line note — *which voice, which target, did it sing or loop?* — that shared notebook at [`Wiself/voice-reports`](https://huggingface.co/datasets/Wiself/voice-reports) might, slowly, show which tensors carry which quirks. No grand claim. Just cheaper to check than to argue, because a voice is small.
+
+```bash
+voice report --voice styletune-v2 --target ./model.gguf -m "delta fixed loop, 1.6% shared"
+# ✓ local → ~/.voices/reports.jsonl
+# Share to community reports (Wiself/voice-reports)? [y/N]  ← waits for y/n, no default
+```
+
+Local first (0600, `flock` + `fsync`), opt-in share, batched by month. `--no-push` keeps it local, `--yes`/`--sync` for scripts. `voice doctor` shows what's pending. Details: `DOCS.md#voice report`.
 
 
 ## What StyleTune showed

voice.py

@@ -13,6 +13,7 @@ Commands:
     voice info <voice>                       Show voice details
     voice remove <voice>                     Remove a stored voice
     voice cleanup                            Remove incomplete downloads
+    voice report                             Save a report locally and optionally share
     voice auth                               Save your Hugging Face token (optional, faster)
     voice path                               Put `voice` on your PATH
     voice doctor                             Check your setup
@@ -38,8 +39,12 @@ from urllib.parse import urlparse
 VOICES_DIR = Path.home() / ".voices"
 HF_TOKEN_PATH = VOICES_DIR / ".hf_token"
 OPERATIONS_LOG = VOICES_DIR / "operations.log"
+REPORTS_JSONL = VOICES_DIR / "reports.jsonl"
+REPORTS_OUTBOX = VOICES_DIR / "outbox"
+REPORTS_DATASET_ID = "Wiself/voice-reports"
+REPORTS_REMOTE_PREFIX = "data/reports-"
 
-VERSION = "2.0.0"
+VERSION = "2.1.0"
 DTYPE_BYTES = {"F32": 4, "F16": 2, "BF16": 2}
 VERBOSE = False
 
@@ -132,25 +137,39 @@ def _confirm(question, args):
 #  Hugging Face token & HTTP
 # ---------------------------------------------------------------------------
 
+_HF_TOKEN_CACHE = {"tok": None, "ts": 0.0}
 def _get_hf_token():
+    # cache 60s to avoid file thrash on hot path
+    now = time.time()
+    if now - _HF_TOKEN_CACHE["ts"] < 60 and _HF_TOKEN_CACHE["tok"] is not None:
+        return _HF_TOKEN_CACHE["tok"]
+    tok = None
     for k in ("HF_TOKEN", "HF_HUB_TOKEN", "HUGGING_FACE_HUB_TOKEN"):
         v = os.environ.get(k)
         if v and v.strip().startswith("hf_"):
-            return v.strip()
-    for p in (HF_TOKEN_PATH, Path.home() / ".cache" / "huggingface" / "token", Path.home() / ".huggingface" / "token"):
-        try:
-            if p.exists():
-                t = p.read_text().strip()
-                if t.startswith("hf_"):
-                    return t
-        except Exception:
-            continue
-    return None
+            tok = v.strip()
+            break
+    if tok is None:
+        for p in (HF_TOKEN_PATH, Path.home() / ".cache" / "huggingface" / "token", Path.home() / ".huggingface" / "token"):
+            try:
+                if p.exists():
+                    t = p.read_text().strip()
+                    if t.startswith("hf_"):
+                        tok = t
+                        break
+            except Exception:
+                continue
+    _HF_TOKEN_CACHE["tok"] = tok
+    _HF_TOKEN_CACHE["ts"] = now
+    return tok
 
 
 _HF_TRUSTED_HOSTS = frozenset({"huggingface.co", "cdn-lfs.huggingface.co", "cdn-lfs-us-1.huggingface.co"})
 
 
+from functools import lru_cache
+
+@lru_cache(maxsize=256)
 def _is_hf_url(url):
     try:
         host = (urlparse(url).hostname or "").lower()
@@ -158,7 +177,6 @@ def _is_hf_url(url):
         return False
     if host in _HF_TRUSTED_HOSTS:
         return True
-    # allow HF subdomains (e.g. huggingface.co, *.huggingface.co) but not attacker-controlled nesting
     return host == "huggingface.co" or host.endswith(".huggingface.co")
 
 
@@ -416,21 +434,16 @@ def rewrite_safetensors_tensor(target_path, out_path, replace_name, replace_byte
 #  Dtype decode — one implementation, used everywhere
 # ---------------------------------------------------------------------------
 
+_DTYPE_BYTES_MAP = {
+    "F32": 4, "FP32": 4, "F64": 8,
+    "F16": 2, "FP16": 2, "BF16": 2, "BF16E8M": 2, "F16E5M6": 2,
+    "I8": 1, "U8": 1, "BOOL": 1, "I16": 2, "I32": 4, "I64": 8,
+}
 def dtype_bytes(dtype):
-    d = dtype.upper()
-    if d in ("F32", "FP32", "F64"):
-        return 4 if d in ("F32", "FP32") else 8
-    if d in ("F16", "FP16", "BF16", "BF16E8M", "F16E5M6"):
-        return 2
-    if d in ("I8", "U8", "BOOL"):
-        return 1
-    if d in ("I16",):
-        return 2
-    if d in ("I32",):
-        return 4
-    if d in ("I64",):
-        return 8
-    raise ValueError(f"unsupported dtype {dtype}")
+    try:
+        return _DTYPE_BYTES_MAP[dtype.upper()]
+    except KeyError:
+        raise ValueError(f"unsupported dtype {dtype}")
 
 
 def bf16_to_f32(u16):
@@ -1259,6 +1272,101 @@ def log_operation(record):
             _warn("could not write operation log")
 
 
+# ---------------------------------------------------------------------------
+#  Reports — local durable store + community share
+# ---------------------------------------------------------------------------
+
+def _atomic_jsonl_append(path, record):
+    """Append one JSON line atomically with flock + fsync. Optimised: single chmod, cached JSON."""
+    path = Path(path)
+    # fast path: parent exists, avoid mkdir/chmod churn
+    if not path.parent.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            os.chmod(path.parent, 0o700)
+        except Exception:
+            pass
+    if not path.exists():
+        try:
+            fd = os.open(str(path), os.O_WRONLY | os.O_CREAT, 0o600)
+            os.close(fd)
+        except Exception:
+            pass
+    else:
+        # occasional chmod drift check, not every append
+        try:
+            if oct(path.stat().st_mode & 0o777) != "0o600":
+                os.chmod(path, 0o600)
+        except Exception:
+            pass
+    _assert_not_symlink(path)
+    line = json.dumps(record, ensure_ascii=False, separators=(",", ":")) + "\n"
+    with open(path, "a") as f:
+        try:
+            import fcntl
+            fcntl.flock(f, fcntl.LOCK_EX)
+            locked = True
+        except Exception:
+            locked = False
+        try:
+            f.write(line)
+            f.flush()
+            try:
+                os.fsync(f.fileno())
+            except Exception:
+                pass
+        finally:
+            if locked:
+                try:
+                    import fcntl
+                    fcntl.flock(f, fcntl.LOCK_UN)
+                except Exception:
+                    pass
+    try:
+        dirfd = os.open(str(path.parent), os.O_DIRECTORY)
+        try:
+            os.fsync(dirfd)
+        finally:
+            os.close(dirfd)
+    except Exception:
+        pass
+
+def _write_outbox(report_id, record):
+    REPORTS_OUTBOX.mkdir(parents=True, exist_ok=True)
+    try:
+        os.chmod(REPORTS_OUTBOX, 0o700)
+    except Exception:
+        pass
+    _assert_not_symlink(REPORTS_OUTBOX)
+    out_path = REPORTS_OUTBOX / f"{report_id}.json"
+    _assert_not_symlink(out_path)
+    tmp = out_path.with_suffix(".tmp")
+    fd = os.open(str(tmp), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        os.write(fd, (json.dumps(record, ensure_ascii=False) + "\n").encode("utf-8"))
+        try:
+            os.fsync(fd)
+        except Exception:
+            pass
+    finally:
+        os.close(fd)
+    tmp.replace(out_path)
+    try:
+        dirfd = os.open(str(REPORTS_OUTBOX), os.O_DIRECTORY)
+        try:
+            os.fsync(dirfd)
+        finally:
+            os.close(dirfd)
+    except Exception:
+        pass
+    return out_path
+
+def _append_report(record):
+    _atomic_jsonl_append(REPORTS_JSONL, record)
+    _write_outbox(record["report_id"], record)
+    log_operation({"op": "report", "report_id": record["report_id"], "status": "ok", "voice": record.get("voice"), "target": record.get("target")})
+
+
 # ---------------------------------------------------------------------------
 #  Registry (stored voices)
 # ---------------------------------------------------------------------------
@@ -2405,6 +2513,252 @@ def cmd_cleanup(args):
         pass
 
 
+# ---------------------------------------------------------------------------
+#  CMD: report — save a report locally and optionally share to community
+# ---------------------------------------------------------------------------
+
+def _hash_file(path):
+    import hashlib
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            b = f.read(8 << 20)
+            if not b:
+                break
+            h.update(b)
+    return h.hexdigest()
+
+def _sanitize_note(s):
+    if s is None:
+        return None
+    s = str(s).replace("\r", " ").replace("\n", " ").replace("\x00", " ")
+    s = re.sub(r"\s+", " ", s).strip()
+    if not s:
+        return None
+    # strip CSV injection prefixes
+    if s and s[0] in "=+@-":
+        s = "'" + s
+    if len(s) > 240:
+        s = s[:239] + "…"
+    return s
+
+def _sanitize_reporter(s):
+    if not s:
+        return None
+    s = re.sub(r"[^A-Za-z0-9._-]", "_", str(s).strip())[:64].strip("_")
+    return s or None
+
+def _prompt_share(args):
+    if getattr(args, "no_push", False):
+        return False
+    if getattr(args, "yes", False):
+        return True
+    if _noninteractive(args):
+        return False
+    # blocking wait for explicit y/n, no default timeout
+    while True:
+        try:
+            ans = input("  Share to community reports (Wiself/voice-reports)? [y/N] ").strip().lower()
+        except (EOFError, KeyboardInterrupt):
+            _say("  ⚠ Cancelled.")
+            sys.exit(0)
+        if ans in ("y", "yes"):
+            return True
+        if ans in ("n", "no", ""):
+            return False
+        _say("  Please answer y or n.")
+
+def _push_reports_batch(records):
+    """Batch push: group by shard, single fetch+upload per shard. Returns pushed count."""
+    import time, tempfile
+    if not records:
+        return 0
+    tok = _get_hf_token()
+    if not tok:
+        _warn("  No HF token — saved to outbox only. Run: voice auth")
+        return 0
+    try:
+        from huggingface_hub import HfApi
+        api = HfApi(token=tok)
+    except Exception as e:
+        _warn(f"  huggingface_hub not available ({e}) — kept in outbox.")
+        return 0
+    try:
+        api.create_repo(repo_id=REPORTS_DATASET_ID, repo_type="dataset", exist_ok=True)
+    except Exception:
+        pass
+    # group by shard
+    from collections import defaultdict
+    by_shard = defaultdict(list)
+    for r in records:
+        shard = f"{REPORTS_REMOTE_PREFIX}{r['ts'][:7]}.jsonl"
+        by_shard[shard].append(r)
+    pushed = 0
+    for shard, recs in by_shard.items():
+        for attempt in range(3):
+            try:
+                existing = ""
+                try:
+                    from huggingface_hub import hf_hub_download
+                    tmp = hf_hub_download(repo_id=REPORTS_DATASET_ID, repo_type="dataset", filename=shard, token=tok)
+                    existing = Path(tmp).read_text(encoding="utf-8", errors="replace")
+                except Exception:
+                    existing = ""
+                # filter already pushed
+                todo = [r for r in recs if r["report_id"] not in existing]
+                if not todo:
+                    for r in recs:
+                        try:
+                            (REPORTS_OUTBOX / f"{r['report_id']}.json").unlink(missing_ok=True)
+                        except Exception:
+                            pass
+                    pushed += len(recs)
+                    break
+                if not existing:
+                    new_content = "\n".join(json.dumps(r, ensure_ascii=False, separators=(",", ":")) for r in todo) + "\n"
+                else:
+                    if not existing.endswith("\n"):
+                        existing += "\n"
+                    new_content = existing + "\n".join(json.dumps(r, ensure_ascii=False, separators=(",", ":")) for r in todo) + "\n"
+                tmpf = Path(tempfile.mktemp())
+                try:
+                    fd = os.open(str(tmpf), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+                    os.write(fd, new_content.encode("utf-8"))
+                    try:
+                        os.fsync(fd)
+                    except Exception:
+                        pass
+                    os.close(fd)
+                except Exception:
+                    tmpf.write_text(new_content, encoding="utf-8")
+                api.upload_file(path_or_fileobj=str(tmpf), path_in_repo=shard, repo_id=REPORTS_DATASET_ID, repo_type="dataset", commit_message=f"report batch {len(todo)} -> {shard}")
+                try:
+                    tmpf.unlink(missing_ok=True)
+                except Exception:
+                    pass
+                for r in todo:
+                    try:
+                        (REPORTS_OUTBOX / f"{r['report_id']}.json").unlink(missing_ok=True)
+                    except Exception:
+                        pass
+                pushed += len(todo)
+                break
+            except Exception as e:
+                try:
+                    from huggingface_hub.utils import HfHubHTTPError as _HE
+                    if isinstance(e, _HE) and getattr(e, "response", None) is not None and getattr(e.response, "status_code", None) in (429, 409, 412):
+                        ra = _parse_retry_after(getattr(e.response, "headers", {}) or {})
+                        time.sleep(ra or (0.7 * (2 ** attempt)))
+                        continue
+                except Exception:
+                    pass
+                if attempt < 2 and isinstance(e, (urllib.error.URLError, TimeoutError, OSError)):
+                    time.sleep(0.7 * (2 ** attempt))
+                    continue
+                if attempt >= 2:
+                    if VERBOSE:
+                        import traceback
+                        _say(traceback.format_exc())
+                    _warn(f"  Push failed for {shard} ({type(e).__name__}: {e}) — kept in outbox.")
+                    break
+                time.sleep(0.7 * (2 ** attempt))
+    return pushed
+
+def _push_report(record):
+    return _push_reports_batch([record]) == 1
+
+def cmd_report(args):
+    # gather fields
+    msg = _sanitize_note(getattr(args, "message", None))
+    voice_arg = getattr(args, "voice", None)
+    # build record
+    import uuid, platform
+    report_id = uuid.uuid4().hex
+    ts = _now_iso()
+    voice_name = None
+    if voice_arg:
+        voice_name = voice_arg.strip()
+    # auto-detect version
+    env_info = {"voice_ver": VERSION, "python": platform.python_version()}
+    record = {
+        "v": 1,
+        "report_id": report_id,
+        "ts": ts,
+        "voice": voice_name,
+        "target": None,
+        "operation": getattr(args, "operation", None) or "report",
+        "status": "ok",
+        "message": msg,
+        "env": env_info,
+    }
+    # optional target handling if provided via positional
+    target = getattr(args, "target", None)
+    if target:
+        record["target"] = Path(target).name  # basename only for privacy
+    reporter = _sanitize_reporter(getattr(args, "reporter", None))
+    if reporter:
+        record["reporter"] = reporter
+    # validate size
+    try:
+        rec_json = json.dumps(record, ensure_ascii=False)
+        if len(rec_json) > 4096:
+            _warn("  Note too large — truncating.")
+            record["message"] = _sanitize_note((msg or "")[:240])
+    except Exception:
+        pass
+    _append_report(record)
+    _ok(f"Report saved locally ({report_id[:8]}…) → {REPORTS_JSONL}")
+    _say(f"  Outbox: {REPORTS_OUTBOX / (report_id + '.json')}")
+    # also handle --sync of pending
+    if getattr(args, "sync", False):
+        pending = sorted(REPORTS_OUTBOX.glob("*.json"))
+        if not pending:
+            _say("  No pending reports to sync.")
+            return
+        _step(f"Syncing {len(pending)} pending report(s)…")
+        recs = []
+        for p in pending:
+            try:
+                recs.append(json.loads(p.read_text()))
+            except Exception as e:
+                _warn(f"  Could not read {p.name}: {e}")
+        if recs:
+            n = _push_reports_batch(recs)
+            _ok(f"Synced {n}/{len(recs)} report(s).")
+        return
+    should_push = _prompt_share(args)
+    if should_push:
+        _step("Sharing to Wiself/voice-reports…")
+        ok = _push_report(record)
+        if ok:
+            _ok("Shared to Wiself/voice-reports.")
+            pending = sorted(REPORTS_OUTBOX.glob("*.json"))
+            if pending:
+                # batch remaining (exclude already-pushed id already deleted)
+                recs = []
+                for p in pending:
+                    try:
+                        recs.append(json.loads(p.read_text()))
+                    except Exception:
+                        continue
+                if recs:
+                    _step(f"Syncing {len(recs)} pending report(s)…")
+                    _push_reports_batch(recs)
+            # headroom warning
+            try:
+                sz = REPORTS_JSONL.stat().st_size if REPORTS_JSONL.exists() else 0
+                if sz > 50 * 1024 * 1024:
+                    _warn(f"  reports.jsonl {sz/1e6:.1f} MB — consider archiving (rotation to reports-YYYY-MM.jsonl).")
+                if len(list(REPORTS_OUTBOX.glob("*.json"))) > 5000:
+                    _warn("  Outbox >5000 pending — run voice report --sync --yes to flush.")
+            except Exception:
+                pass
+        else:
+            _warn("  Share pending — will retry on next report or voice doctor.")
+    else:
+        _say("  Saved locally. Outbox retained for later push (rerun with --yes to share).")
+
+
 # ---------------------------------------------------------------------------
 #  CMD: auth
 # ---------------------------------------------------------------------------
@@ -2551,6 +2905,24 @@ def cmd_doctor(_args):
             _say(f"  operations logged: {n} ({OPERATIONS_LOG})")
         except Exception:
             pass
+    if REPORTS_JSONL.exists():
+        try:
+            n = sum(1 for _ in open(REPORTS_JSONL))
+            pending = len(list(REPORTS_OUTBOX.glob("*.json"))) if REPORTS_OUTBOX.exists() else 0
+            _say(f"  reports: {n} local, {pending} pending in outbox ({REPORTS_JSONL})")
+            if pending > 5000:
+                _warn(f"  outbox >5000 pending — run: voice report --sync --yes")
+            # headroom
+            try:
+                sz = REPORTS_JSONL.stat().st_size
+                if sz > 50 * 1024 * 1024:
+                    _warn(f"  reports.jsonl {sz/1e6:.1f} MB — consider archiving")
+            except Exception:
+                pass
+        except Exception:
+            pass
+    else:
+        _say(f"  reports: none yet — run: voice report")
     try:
         req = urllib.request.Request("https://huggingface.co/api/whoami-v2" if tok else "https://huggingface.co",
                                      headers=_hf_auth_headers("https://huggingface.co"))
@@ -2558,6 +2930,11 @@ def cmd_doctor(_args):
             _say(f"  connectivity huggingface.co ok ({resp.status})")
     except Exception as e:
         _warn(f"connectivity failed: {e}")
+    # check push target
+    try:
+        _say(f"  community reports: {REPORTS_DATASET_ID} (share prompt on voice report)")
+    except Exception:
+        pass
 
 
 def _print_version():
@@ -2573,7 +2950,7 @@ def _print_version():
 
 
 def _print_completion(shell):
-    cmds = ["get", "cast", "delta", "list", "info", "remove", "cleanup", "auth", "path", "doctor", "tensor"]
+    cmds = ["get", "cast", "delta", "list", "info", "remove", "cleanup", "auth", "report", "path", "doctor", "tensor"]
     voices = [d.name for d in _iter_voices() if (d / "voice.json").exists()]
     vlist = " ".join(voices)
     clist = " ".join(cmds)
@@ -2718,6 +3095,16 @@ def main():
     p_auth.add_argument("--clear", action="store_true")
     p_auth.add_argument("--show", action="store_true")
 
+    p_report = sub.add_parser("report", help="Save a report locally and optionally share to community")
+    p_report.add_argument("--message", "-m", help="Freeform note (240ch, sanitized)")
+    p_report.add_argument("--voice", help="Voice name context")
+    p_report.add_argument("--target", help="Target file basename context")
+    p_report.add_argument("--reporter", help="Reporter id (optional, 64ch)")
+    p_report.add_argument("--yes", action="store_true", help="Non-interactive: auto-share to community")
+    p_report.add_argument("--no-push", action="store_true", help="Local only, skip share prompt")
+    p_report.add_argument("--sync", action="store_true", help="Sync pending outbox to community")
+    p_report.add_argument("--operation", help=argparse.SUPPRESS)
+
     sub.add_parser("path", help="Put voice on your PATH")
     sub.add_parser("doctor", help="Check your setup")
 
@@ -2739,7 +3126,7 @@ def main():
     dispatch = {
         "get": cmd_get, "cast": cmd_cast, "delta": cmd_delta, "list": cmd_list,
         "info": cmd_info, "remove": cmd_remove, "cleanup": cmd_cleanup, "auth": cmd_auth,
-        "path": cmd_path, "doctor": cmd_doctor,
+        "report": cmd_report, "path": cmd_path, "doctor": cmd_doctor,
     }
     if args.command == "tensor":
         if args.tensor_cmd == "get":