contextzip 0.4.3__tar.gz → 0.4.5__tar.gz

{contextzip-0.4.3 → contextzip-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.4.3
+Version: 0.4.5
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -27,7 +27,11 @@ Requires-Dist: pathspec>=0.12
 Requires-Dist: httpx>=0.27
 Dynamic: license-file
 
-<img width="1536" height="1024" alt="cz" src="https://github.com/user-attachments/assets/a930b49c-34a0-447b-8f3a-1909eae977c8" />
+
+
+https://github.com/user-attachments/assets/91913ad6-6161-430d-9075-b0fa76498021
+
+<!-- <img width="1536" height="1024" alt="cz" src="https://github.com/user-attachments/assets/a930b49c-34a0-447b-8f3a-1909eae977c8" /> -->
 
 # contextzip
 
@@ -87,7 +91,7 @@ Full function reference: [contextzip.vercel.app/cli#python-api](https://contextz
 - [Packaging & detection](https://contextzip.vercel.app/features) — frameworks, exclusion rules, safety
 - [AI-powered file selection](https://contextzip.vercel.app/ai-selection) — `--prompt`, Gemini setup
 - [Terminal error watcher](https://contextzip.vercel.app/watch) — `contextzip watch`
-- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, backups, safety
+- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, manifest diffing, safety
 - [Configuration](https://contextzip.vercel.app/configuration) — personal & project config, visual config UI
 - [CLI & Python API reference](https://contextzip.vercel.app/cli)
 

{contextzip-0.4.3 → contextzip-0.4.5}/README.md

@@ -1,4 +1,8 @@
-<img width="1536" height="1024" alt="cz" src="https://github.com/user-attachments/assets/a930b49c-34a0-447b-8f3a-1909eae977c8" />
+
+
+https://github.com/user-attachments/assets/91913ad6-6161-430d-9075-b0fa76498021
+
+<!-- <img width="1536" height="1024" alt="cz" src="https://github.com/user-attachments/assets/a930b49c-34a0-447b-8f3a-1909eae977c8" /> -->
 
 # contextzip
 
@@ -58,7 +62,7 @@ Full function reference: [contextzip.vercel.app/cli#python-api](https://contextz
 - [Packaging & detection](https://contextzip.vercel.app/features) — frameworks, exclusion rules, safety
 - [AI-powered file selection](https://contextzip.vercel.app/ai-selection) — `--prompt`, Gemini setup
 - [Terminal error watcher](https://contextzip.vercel.app/watch) — `contextzip watch`
-- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, backups, safety
+- [Applying changes back](https://contextzip.vercel.app/apply-zip) — `apply-zip`, manifest diffing, safety
 - [Configuration](https://contextzip.vercel.app/configuration) — personal & project config, visual config UI
 - [CLI & Python API reference](https://contextzip.vercel.app/cli)
 

{contextzip-0.4.3 → contextzip-0.4.5}/contextzip/__init__.py

@@ -1,6 +1,6 @@
 """contextzip — intelligent codebase packager for AI tools."""
 
-__version__ = "0.4.3"
+__version__ = "0.4.5"
 
 from contextzip.api import (
     FileCollection,

{contextzip-0.4.3 → contextzip-0.4.5}/contextzip/api.py

@@ -43,12 +43,15 @@ from contextzip.applier import ApplyResult
 from contextzip.detector import DetectionResult, detect
 from contextzip.filters import (
     ResolveResult,
+    build_force_include_spec,
     build_spec,
+    normalize_pattern,
     resolve_files,
     resolve_files_from_git,
 )
 from contextzip.git import GitError, GitErrorKind, get_changed_files
 from contextzip.packager import PackageResult, create_zip_silent
+from contextzip.project_config import load_project_config
 
 
 # ---------------------------------------------------------------------------
@@ -139,19 +142,27 @@ class ZipNotFoundError(ContextzipError):
 
 def get_git_changes(
     path: str | Path | None = None,
+    *,
+    use_project_config: bool = True,
 ) -> FileCollection:
     """
     Return the files that git reports as modified, added, or untracked.
 
     The git root is found automatically by walking up from *path* (or the
     current working directory). Files are filtered through contextzip's base
-    safety rules so secrets, binaries, and similar files are always excluded.
+    safety rules so secrets, binaries, and similar files are always excluded,
+    and through the project's ``.contextzip/config.json``
+    (``always_include`` / ``always_exclude`` / ``limits``) — the same as the
+    CLI's ``--git-changes``.
 
     Parameters
     ----------
     path:
         Directory to start from. Defaults to ``Path.cwd()``. The actual
         git root may be a parent of this directory.
+    use_project_config:
+        Apply the project's ``.contextzip/config.json``. Defaults to
+        ``True``; pass ``False`` to use only the built-in rules.
 
     Returns
     -------
@@ -192,9 +203,12 @@ def get_git_changes(
     if git_result.is_empty:
         return FileCollection(project_dir=project_dir)
 
+    cfg = load_project_config(project_dir) if use_project_config else None
+
     resolved = resolve_files_from_git(
         git_files=git_result.files,
         project_dir=project_dir,
+        **_config_kwargs(cfg),
     )
 
     detection = detect(project_dir)
@@ -212,6 +226,7 @@ def get_files(
     include: list[str] | None = None,
     exclude: list[str] | None = None,
     use_gitignore: bool = True,
+    use_project_config: bool = True,
 ) -> FileCollection:
     """
     Return all project files after applying contextzip's standard exclusion rules.
@@ -229,6 +244,11 @@ def get_files(
     use_gitignore:
         Whether to apply the project's ``.gitignore`` file.
         Defaults to ``True``.
+    use_project_config:
+        Apply the project's ``.contextzip/config.json`` (``always_include``,
+        ``always_exclude``, ``limits``), the same as the CLI. Defaults to
+        ``True``; pass ``False`` to use only the built-in rules and the
+        arguments above.
 
     Returns
     -------
@@ -256,9 +276,12 @@ def get_files(
 
     gitignore_path = (project_dir / ".gitignore") if use_gitignore else None
 
+    cfg = load_project_config(project_dir) if use_project_config else None
+    cfg_kwargs = _config_kwargs(cfg, extra_exclude=exclude)
+
     spec = build_spec(
         rule_modules=detection.rule_modules,
-        extra_exclude=exclude or None,
+        extra_exclude=cfg_kwargs["extra_exclude"],
         gitignore_path=gitignore_path,
     )
 
@@ -266,6 +289,8 @@ def get_files(
         project_dir=project_dir,
         spec=spec,
         include_only=include or None,
+        force_include=cfg_kwargs["force_include"],
+        large_file_warn_bytes=cfg_kwargs["large_file_warn_bytes"],
     )
 
     return _resolve_result_to_collection(resolved, project_dir, detection)
@@ -354,8 +379,6 @@ def apply_zip(
     classify every file as new, modified, unchanged, or one with no safe
     baseline (locally edited since zipping, or never part of the original
     manifest). Only adds and modifies files — nothing is ever deleted.
-    Every overwritten file is backed up first, under
-    ``.contextzip/backups/<timestamp>/``.
 
     Unlike the CLI, this applies immediately and does not prompt — check
     ``contextzip.applier.build_plan()`` yourself first if you want to
@@ -375,8 +398,7 @@ def apply_zip(
     Returns
     -------
     ApplyResult
-        ``written`` (list of relative paths written), ``backup_dir``
-        (``Path`` or ``None`` if nothing needed backing up), and
+        ``written`` (list of relative paths written) and
         ``applied_zip_path`` (where the consumed zip ended up).
 
     Raises
@@ -393,8 +415,6 @@ def apply_zip(
 
         result = apply_zip()  # picks up .contextzip/inbox/*.zip
         print(f"Wrote {len(result.written)} files")
-        if result.backup_dir:
-            print(f"Backup at {result.backup_dir}")
     """
     from contextzip.applier import (
         ApplyError,
@@ -452,6 +472,31 @@ def detect_ecosystem(
 # ---------------------------------------------------------------------------
 
 
+def _config_kwargs(cfg, extra_exclude: list[str] | None = None) -> dict:
+    """
+    Translate a ProjectConfig (or None) into the shared filter inputs:
+    extra_exclude (caller patterns + always_exclude), force_include
+    (always_include) and large_file_warn_bytes (limits.max_file_size_mb).
+    """
+    from contextzip.filters import LARGE_FILE_WARN_BYTES
+
+    patterns = [normalize_pattern(p) for p in extra_exclude or []]
+    if cfg is None:
+        return {
+            "extra_exclude": patterns or None,
+            "force_include": None,
+            "large_file_warn_bytes": LARGE_FILE_WARN_BYTES,
+        }
+    patterns += [normalize_pattern(p) for p in cfg.always_exclude]
+    return {
+        "extra_exclude": patterns or None,
+        "force_include": build_force_include_spec(
+            [normalize_pattern(p) for p in cfg.always_include]
+        ),
+        "large_file_warn_bytes": int(cfg.limits.max_file_size_mb * 1024 * 1024),
+    }
+
+
 def _resolve_dir(path: str | Path | None) -> Path:
     if path is None:
         return Path(os.getcwd()).resolve()

{contextzip-0.4.3 → contextzip-0.4.5}/contextzip/applier.py

@@ -48,8 +48,86 @@ from pathlib import Path
 _MANIFEST_SUFFIX = ".manifest.json"
 _INBOX_DIRNAME = "inbox"
 _APPLIED_DIRNAME = "applied"
-_BACKUPS_DIRNAME = "backups"
 _OUTPUT_DIRNAME = "output"  # must match packager._OUTPUT_DIRNAME
+_INBOX_README_NAME = "README.txt"
+
+_INBOX_README_CONTENTS = """\
+Drop your zip here which you want to apply.
+============================================
+
+This folder is contextzip's inbox — the one place `apply-zip` looks for
+a zip to bring back into your project.
+
+HOW TO USE IT
+  1. Take the zip your AI tool (Claude, ChatGPT, etc.) gave you back,
+     after you sent it a codebase package contextzip made for you.
+  2. Drop that zip file directly into this folder — no need to rename
+     it or unzip it first.
+  3. Run:  contextzip apply-zip     (short alias:  cz apply-zip)
+  4. contextzip finds it automatically, compares every file inside it
+     against your project's manifest, and shows you exactly what's
+     new, modified, or unchanged before writing anything to disk.
+
+WHAT HAPPENS TO THE ZIP AFTERWARDS
+  Once applied, contextzip moves it into inbox/applied/ instead of
+  deleting it, so there's always a record of exactly what was applied
+  and when. Old entries there are pruned automatically over time — see
+  the `cleanup` and `applied_zip_retention` settings in
+  .contextzip/config.json if you'd like to keep more of them.
+
+A FEW THINGS WORTH KNOWING
+  - Only .zip files placed directly in this folder are picked up —
+    not ones inside a subfolder.
+  - If more than one zip ends up here at once, contextzip will ask you
+    to say which one: contextzip apply-zip <name>.zip
+  - You can also point apply-zip at a zip anywhere else on disk instead
+    of using this folder: contextzip apply-zip /path/to/file.zip
+  - This whole .contextzip/ folder is local to your machine and is
+    never committed to git (see .contextzip/.gitignore) — nothing here
+    leaves your computer unless you explicitly share it yourself.
+  - This file is just documentation — it's fine to edit it, and it
+    won't affect anything if you do. If it ever goes missing, though,
+    contextzip will put a fresh copy back the next time it touches this
+    folder; it never touches an actual pending zip, only this file.
+
+Full docs: https://contextzip.vercel.app/apply-zip
+"""
+
+
+def ensure_inbox_scaffolding(workspace: Path) -> None:
+    """
+    Make sure <workspace>/inbox/ exists, with its README.txt explaining
+    what the folder is for.
+
+    Called at the same moment the rest of the .contextzip/ workspace gets
+    set up (see packager.py's `_workspace_output_path[_silent]`), so the
+    inbox is ready and self-explanatory from the very first run — rather
+    than a bare, unexplained folder someone only discovers by reading the
+    docs, or worse, one that doesn't exist yet the first time `apply-zip`
+    goes looking for it.
+
+    Idempotent, same rule as the workspace .gitignore (see
+    `_ensure_workspace_gitignore` in packager.py): leaves an
+    already-correct README.txt untouched, and (re)writes it whenever it's
+    missing or doesn't match, so it stays reliable documentation rather
+    than something that quietly rots or disappears. Never touches
+    anything else already in the inbox — pending zips, `applied/`, past
+    reports.
+    """
+    inbox = workspace / _INBOX_DIRNAME
+    inbox.mkdir(parents=True, exist_ok=True)
+
+    readme_path = inbox / _INBOX_README_NAME
+    if readme_path.is_file():
+        try:
+            if readme_path.read_text(encoding="utf-8", errors="replace") == _INBOX_README_CONTENTS:
+                return
+        except OSError:
+            return
+    try:
+        readme_path.write_text(_INBOX_README_CONTENTS, encoding="utf-8")
+    except OSError:
+        pass
 
 # Files contextzip itself writes into outgoing ZIPs that should never be
 # written back into the project even if an AI tool echoes them back.
@@ -146,7 +224,6 @@ class ApplyPlan:
 @dataclass
 class ApplyResult:
     written: list[str]
-    backup_dir: Path | None
     applied_zip_path: Path
 
 
@@ -266,10 +343,17 @@ def find_zip_to_apply(
 
     inbox = inbox_dir(project_dir)
     if not inbox.is_dir():
+        # Normally created alongside the rest of .contextzip/ the first
+        # time any contextzip command runs (see
+        # ensure_inbox_scaffolding), so this only fires if apply-zip is
+        # somehow the very first command run in a project. Create it now
+        # rather than just describing where it should be — so the folder
+        # (and its README) are actually there for the person to drop a
+        # zip into right after reading this message.
+        ensure_inbox_scaffolding(_workspace_dir(project_dir))
         raise NoZipFoundError(
-            f"No zip found. Drop the AI-returned zip into {inbox} "
-            "(created the first time you run contextzip), or pass a path "
-            "directly: contextzip apply-zip <path>"
+            f"No zip found. Drop the AI-returned zip into {inbox}, "
+            "or pass a path directly: contextzip apply-zip <path>"
         )
 
     candidates = sorted(p for p in inbox.glob("*.zip") if p.is_file())
@@ -417,6 +501,31 @@ def _match_rate(names: list[str], manifest_files: dict) -> float:
 # ---------------------------------------------------------------------------
 
 
+def _top_level_dir_match_rate(names: list[str], project_dir: Path) -> float:
+    """
+    Fraction of *names*' unique top-level path segments that exist as a
+    real file or directory directly under *project_dir* right now.
+
+    Used as a fallback signal for wrapper-stripping when the manifest
+    can't settle it — e.g. the freshest manifest on disk is a narrow,
+    git-diff-scoped one (`.contextzip/output/git-changes/...`) that only
+    ever listed a handful of touched files, so a zip full of brand-new
+    files matches it at ~0% whether or not the wrapper is stripped. The
+    manifest is silent either way, but the project's actual top-level
+    layout — `app/`, `components/`, `lib/`, and so on — usually isn't:
+    a genuine wrapper's contents line up with it once stripped, while
+    the raw, unstripped paths (starting with the wrapper's own name)
+    essentially never do.
+    """
+    if not names:
+        return 0.0
+    tops = {n.split("/", 1)[0] for n in names}
+    if not tops:
+        return 0.0
+    existing = sum(1 for t in tops if t and (project_dir / t).exists())
+    return existing / len(tops)
+
+
 def build_plan(
     zip_path: Path,
     project_dir: Path,
@@ -447,6 +556,9 @@ def build_plan(
     wrapper_note: str | None = None
     candidate = _detect_common_wrapper(raw_names)
     if candidate:
+        stripped_names = [n[len(candidate) + 1:] for n in raw_names]
+        candidate_is_real_dir = (project_dir / candidate).is_dir()
+
         if manifest_files:
             # Decide using the manifest — actual ground truth about what
             # paths this project has — rather than whether a directory of
@@ -465,7 +577,6 @@ def build_plan(
             # better *unstripped*, since those paths are already in the
             # manifest as-is.
             unstripped_rate = _match_rate(raw_names, manifest_files)
-            stripped_names = [n[len(candidate) + 1:] for n in raw_names]
             stripped_rate = _match_rate(stripped_names, manifest_files)
             # Only strip when it clearly helps — meaningfully better match
             # against paths we know this project actually has, not just a
@@ -478,18 +589,53 @@ def build_plan(
                     f"project manifest after stripping vs {unstripped_rate:.0%} "
                     "before."
                 )
-        elif not (project_dir / candidate).is_dir():
+            elif stripped_rate == unstripped_rate and not candidate_is_real_dir:
+                # The manifest didn't help decide either way — most often
+                # because the manifest in use is scoped to a small subset
+                # of the project (e.g. a git-diff manifest from
+                # output/git-changes/, which only ever tracked the files
+                # touched in one change) rather than the whole tree, so a
+                # zip of brand-new files matches it at 0% regardless of
+                # stripping. Fall back to checking whether the paths line
+                # up with the project's real, current top-level layout
+                # instead of giving up and leaving the wrapper in place.
+                dir_unstripped_rate = _top_level_dir_match_rate(raw_names, project_dir)
+                dir_stripped_rate = _top_level_dir_match_rate(stripped_names, project_dir)
+                if dir_stripped_rate > dir_unstripped_rate and dir_stripped_rate >= 0.5:
+                    strip_prefix = candidate
+                    wrapper_note = (
+                        f"Removed wrapping folder '{candidate}/' present in "
+                        "every zip entry — the project manifest in use didn't "
+                        "cover enough of these paths to tell either way "
+                        "(likely scoped to a specific change rather than the "
+                        "whole project), but "
+                        f"{dir_stripped_rate:.0%} of the stripped paths' "
+                        "top-level folders match this project's real layout "
+                        f"vs {dir_unstripped_rate:.0%} before — double-check "
+                        "the result before trusting it."
+                    )
+        elif not candidate_is_real_dir:
             # No manifest to confirm against, so this is a softer call —
             # still strip (matches how `tar` and GitHub's own zip downloads
             # behave) as long as the project doesn't already have a real
             # folder of that name, but say so plainly since it's not
-            # manifest-verified.
+            # manifest-verified. Where the on-disk layout backs it up, say
+            # that too rather than leaving the caveat maximally vague.
             strip_prefix = candidate
-            wrapper_note = (
-                f"Removed wrapping folder '{candidate}/' present in every zip "
-                "entry (no manifest available to confirm — double-check the "
-                "result before trusting it)."
-            )
+            dir_stripped_rate = _top_level_dir_match_rate(stripped_names, project_dir)
+            if dir_stripped_rate >= 0.5:
+                wrapper_note = (
+                    f"Removed wrapping folder '{candidate}/' present in every "
+                    f"zip entry — {dir_stripped_rate:.0%} of the stripped "
+                    "paths' top-level folders match this project's real "
+                    "layout (no manifest available to confirm further)."
+                )
+            else:
+                wrapper_note = (
+                    f"Removed wrapping folder '{candidate}/' present in every zip "
+                    "entry (no manifest available to confirm — double-check the "
+                    "result before trusting it)."
+                )
 
     extraction_dir = Path(tempfile.mkdtemp(prefix="contextzip-apply-"))
     _safe_extract(zip_path, extraction_dir, strip_prefix=strip_prefix)
@@ -538,16 +684,31 @@ def build_plan(
         known = sum(1 for e in entries if e.rel_path in manifest_files)
         rate = known / len(entries)
         if rate < 0.1:
-            structure_warning = (
-                f"Only {known} of {len(entries)} files in this zip match paths "
-                "from the project manifest, even after checking for a wrapping "
-                "folder. That usually means the zip's internal structure "
-                "doesn't line up with this project — the wrong zip, or one "
-                "built with an unexpected layout. Applying it as-is will "
-                "likely create a pile of unrelated new files rather than "
-                "update the ones you meant to change. Double-check the zip "
-                "before proceeding."
-            )
+            if strip_prefix and "top-level folders match" in (wrapper_note or ""):
+                # The wrapper was already resolved via the on-disk layout
+                # fallback above, so don't re-cast that as if the wrapper
+                # check itself came up empty — it didn't, the manifest just
+                # doesn't happen to cover these particular files.
+                structure_warning = (
+                    f"Only {known} of {len(entries)} files in this zip match "
+                    "paths from the project manifest. The wrapper folder was "
+                    "still resolved using the project's real directory "
+                    "layout (see above), but none of these exact files were "
+                    "in the manifest, so this may be new work the manifest "
+                    "predates rather than a mismatch — worth a quick look "
+                    "before applying."
+                )
+            else:
+                structure_warning = (
+                    f"Only {known} of {len(entries)} files in this zip match paths "
+                    "from the project manifest, even after checking for a wrapping "
+                    "folder. That usually means the zip's internal structure "
+                    "doesn't line up with this project — the wrong zip, or one "
+                    "built with an unexpected layout. Applying it as-is will "
+                    "likely create a pile of unrelated new files rather than "
+                    "update the ones you meant to change. Double-check the zip "
+                    "before proceeding."
+                )
 
     return ApplyPlan(
         zip_path=zip_path,
@@ -570,29 +731,6 @@ def discard_plan(plan: ApplyPlan) -> None:
 # ---------------------------------------------------------------------------
 
 
-def _backup_entries(
-    entries: list[ApplyEntry], project_dir: Path, workspace_root: Path
-) -> Path | None:
-    """
-    Copy the current, pre-apply version of every existing file about to be
-    touched into .contextzip/backups/<timestamp>/, preserving relative
-    paths. Files that don't exist yet locally (new files) have nothing to
-    back up. Returns the backup directory, or None if nothing needed one.
-    """
-    to_backup = [e for e in entries if (project_dir / e.rel_path).is_file()]
-    if not to_backup:
-        return None
-
-    stamp = time.strftime("%Y%m%d-%H%M%S")
-    backup_dir = workspace_root / _BACKUPS_DIRNAME / stamp
-    for entry in to_backup:
-        src = project_dir / entry.rel_path
-        dst = backup_dir / entry.rel_path
-        dst.parent.mkdir(parents=True, exist_ok=True)
-        shutil.copy2(src, dst)
-    return backup_dir
-
-
 def _move_zip_to_applied(
     zip_path: Path, project_dir: Path, workspace_root: Path, retain: int = 1
 ) -> Path:
@@ -639,9 +777,14 @@ def execute_plan(plan: ApplyPlan, project_dir: Path, retain: int = 1) -> ApplyRe
     """
     Write every non-unchanged entry from *plan* into the project.
 
-    Backs up whatever's about to be overwritten first. Assumes the caller
-    has already decided to proceed — dry-run and confirmation prompts are
-    handled upstream (see cli.py's `apply-zip` command).
+    Assumes the caller has already decided to proceed — dry-run and
+    confirmation prompts are handled upstream (see cli.py's `apply-zip`
+    command). Files are overwritten directly, with no backup taken first:
+    `build_plan`'s manifest diff and the confirmation prompt it drives
+    (see `ApplyPlan.is_risky`) are the safety net here, and the zip you
+    just applied is itself always recoverable — it's archived to
+    `.contextzip/inbox/applied/` (or left wherever you pointed at it)
+    rather than deleted.
 
     *retain* caps how many applied zips are kept in
     .contextzip/inbox/applied/ — typically a project's
@@ -650,8 +793,6 @@ def execute_plan(plan: ApplyPlan, project_dir: Path, retain: int = 1) -> ApplyRe
     workspace_root = _workspace_dir(project_dir)
     to_write = plan.writable_entries
 
-    backup_dir = _backup_entries(to_write, project_dir, workspace_root)
-
     written: list[str] = []
     for entry in to_write:
         dest = project_dir / entry.rel_path
@@ -664,6 +805,4 @@ def execute_plan(plan: ApplyPlan, project_dir: Path, retain: int = 1) -> ApplyRe
     )
     shutil.rmtree(plan.extraction_dir, ignore_errors=True)
 
-    return ApplyResult(
-        written=written, backup_dir=backup_dir, applied_zip_path=applied_zip_path
-    )
+    return ApplyResult(written=written, applied_zip_path=applied_zip_path)

{contextzip-0.4.3 → contextzip-0.4.5}/contextzip/cleanup.py

@@ -2,21 +2,16 @@
 cleanup.py — Automatic workspace housekeeping for contextzip.
 
 .contextzip/ accumulates disposable artifacts over time: a zip+manifest+report
-set every run, a timestamped backup folder every risky `apply-zip`, and (until
-pruned) old archived applied-zips. None of it is precious — every zip is
-trivially reproducible by just re-running contextzip, and a backup only
-matters until the apply that made it is confirmed good. So cleanup here is
-deliberately brutal rather than cautious: it runs automatically after every
-successful command (see `_auto_cleanup` in cli.py), with no prompt and no
-separate command to remember, and keeps only the most recent
-`cleanup.keep_recent` item(s) in each category — everything else is deleted
-immediately, every time.
-
-The heavier caution used elsewhere in contextzip (backing up before overwrite
-in apply-zip, never inferring deletions) is reserved for the project's own
-files, where losing something can mean losing real work. Nothing here ever
-touches the project — only disposable metadata under .contextzip/ that costs
-nothing to regenerate.
+set every run, and (until pruned) old archived applied-zips and loose apply
+reports. None of it is precious — every zip is trivially reproducible by just
+re-running contextzip. So cleanup here is deliberately brutal rather than
+cautious: it runs automatically after every successful command (see
+`_auto_cleanup` in cli.py), with no prompt and no separate command to
+remember, and keeps only the most recent `cleanup.keep_recent` item(s) in
+each category — everything else is deleted immediately, every time.
+
+Nothing here ever touches the project — only disposable metadata under
+.contextzip/ that costs nothing to regenerate.
 
 Never touched, under any settings:
   - .contextzip/config.json (project preferences)
@@ -28,11 +23,22 @@ Never touched, under any settings:
 Kept only-the-most-recent-N, everything older deleted immediately:
   - zip/manifest/report sets under .contextzip/output/<mode>/, per mode
     folder
-  - timestamped folders under .contextzip/backups/
   - archived zips under .contextzip/inbox/applied/ (this is also governed
     by `applied_zip_retention`, already enforced on every apply-zip run —
     scanning it here too just catches the case where zips piled up before
     that setting existed, or the setting was since lowered)
+  - loose `*.apply-report.txt` files sitting directly in .contextzip/inbox/
+    (as opposed to inbox/applied/) — these are written next to wherever
+    apply-zip resolved its zip from, decoupled from the zip's own
+    lifecycle (a zip gets archived into applied/ or left where the user
+    put it; its report always lands in inbox/ itself), so nothing else
+    here would ever catch them piling up run after run
+
+Removed outright, no matter how recent:
+  - .contextzip/backups/ in its entirety. apply-zip no longer creates
+    per-run backups there at all — this only ever catches a leftover
+    folder from a project that used an older contextzip version, and it's
+    dead weight the moment that version is gone.
 
 Scanning only ever touches .contextzip/ directory listings and file mtimes —
 no hashing, no reading file contents — so this stays fast even called on
@@ -47,7 +53,7 @@ from pathlib import Path
 
 
 _OUTPUT_DIRNAME = "output"
-_BACKUPS_DIRNAME = "backups"
+_LEGACY_BACKUPS_DIRNAME = "backups"
 _INBOX_DIRNAME = "inbox"
 _APPLIED_DIRNAME = "applied"
 
@@ -60,7 +66,7 @@ _APPLIED_DIRNAME = "applied"
 @dataclass
 class CleanupItem:
     path: Path
-    kind: str  # "zip-set" | "backup" | "applied-zip"
+    kind: str  # "zip-set" | "applied-zip" | "apply-report" | "legacy-backups"
     size_bytes: int
 
 
@@ -160,14 +166,14 @@ def scan(
             for f in _zip_set_files(zp):
                 items.append(CleanupItem(path=f, kind="zip-set", size_bytes=_size_of(f)))
 
-    # ── backups/<timestamp>/ ─────────────────────────────────────────────
-    backups_root = workspace / _BACKUPS_DIRNAME
+    # ── backups/ — the feature that created these is gone entirely; wipe
+    #    the whole folder outright rather than pruning it, so upgrading
+    #    from an older contextzip version doesn't leave it behind forever ──
+    backups_root = workspace / _LEGACY_BACKUPS_DIRNAME
     if backups_root.is_dir():
-        backups = _newest_first([p for p in backups_root.iterdir() if p.is_dir()])
-        for backup_dir in backups[keep:]:
-            items.append(
-                CleanupItem(path=backup_dir, kind="backup", size_bytes=_size_of(backup_dir))
-            )
+        items.append(
+            CleanupItem(path=backups_root, kind="legacy-backups", size_bytes=_size_of(backups_root))
+        )
 
     # ── inbox/applied/ ───────────────────────────────────────────────────
     applied_root = workspace / _INBOX_DIRNAME / _APPLIED_DIRNAME
@@ -177,6 +183,19 @@ def scan(
         for zp in applied_zips[retain:]:
             items.append(CleanupItem(path=zp, kind="applied-zip", size_bytes=_size_of(zp)))
 
+    # ── inbox/*.apply-report.txt ─────────────────────────────────────────
+    # Loose report files written directly in the inbox root (see
+    # report.py's write_apply_report) — decoupled from any single zip's
+    # own path, so nothing above ever catches these. Every apply-zip run
+    # writes one, so left alone they'd accumulate forever.
+    inbox_root = workspace / _INBOX_DIRNAME
+    if inbox_root.is_dir():
+        reports = _newest_first(
+            [p for p in inbox_root.glob("*.apply-report.txt") if p.is_file()]
+        )
+        for rp in reports[keep:]:
+            items.append(CleanupItem(path=rp, kind="apply-report", size_bytes=_size_of(rp)))
+
     return CleanupPlan(workspace=workspace, items=items)