contextzip 0.4.7__tar.gz → 0.5.1__tar.gz

{contextzip-0.4.7 → contextzip-0.5.1}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.4.7
+Version: 0.5.1
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
-Project-URL: Homepage, https://github.com/akadeepesh/contextzip
+Project-URL: Homepage, https://www.contextzipcli.com
+Project-URL: Documentation, https://www.contextzipcli.com/getting-started
 Project-URL: Repository, https://github.com/akadeepesh/contextzip
 Project-URL: Issues, https://github.com/akadeepesh/contextzip/issues
 Keywords: ai,cli,developer-tools,context,zip,llm,claude,chatgpt,code-packaging
@@ -38,7 +39,7 @@ Dynamic: license-file
 [![Downloads](https://static.pepy.tech/badge/contextzip/month)](https://pepy.tech/project/contextzip)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/akadeepesh/contextzip/blob/main/LICENSE)
 
-[Documentation](https://contextzip.vercel.app) ·
+[Documentation](https://www.contextzipcli.com) ·
 [CLI reference](https://github.com/akadeepesh/contextzip/blob/main/CLI.md) ·
 [Changelog](https://github.com/akadeepesh/contextzip/blob/main/CHANGELOG.md) ·
 [Report a bug](https://github.com/akadeepesh/contextzip/issues/new/choose)
@@ -65,6 +66,7 @@ When the AI sends changed files back, `contextzip apply-zip` writes them into yo
 ## Table of contents
 
 - [Installation](#installation)
+  - ["`cz` is not recognized"](#cz-is-not-recognized--command-not-found)
 - [Quick start](#quick-start)
 - [Features](#features)
   - [Smart packaging](#smart-packaging)
@@ -103,6 +105,20 @@ This installs two commands that do the same thing: `contextzip` and the shorter
 
 To update later, run `contextzip update`. It works out whether you installed with pip, pipx or uv and upgrades the right one.
 
+### "`cz` is not recognized" / "command not found"
+
+pip installed contextzip, but put the `cz` command in a folder your terminal doesn't search. This is common with Python from the Microsoft Store or the Python install manager on Windows, and with `pip install --user` on macOS and Linux. Look for pip's `WARNING: The scripts cz.exe and contextzip.exe are installed in '…' which is not on PATH.`
+
+Python itself always works, so run contextzip through it and let it fix PATH for you:
+
+```bash
+python -m contextzip setup-path     # macOS / Linux: python3 -m contextzip setup-path
+```
+
+On Windows this adds the folder to your user PATH (no admin needed). On macOS and Linux it adds one line to your shell's startup file. Open a new terminal and `cz` works. Until then, `python -m contextzip` does everything `cz` does.
+
+If you installed with pipx, run `pipx ensurepath`. With uv, run `uv tool update-shell`.
+
 ## Quick start
 
 ```bash
@@ -120,6 +136,7 @@ contextzip --git-changes                    # only what you've changed
 contextzip --prompt "fix the login redirect bug"   # let AI pick the relevant files
 contextzip include src/ app/                # only these folders
 contextzip include src/ .env                # .env too, values redacted
+contextzip --here                           # only the folder you're in (monorepos)
 contextzip exclude tests/ '*.snap'          # everything except these
 contextzip apply-zip                        # write the AI's changes back
 ```
@@ -163,7 +180,7 @@ Describe your task in plain language and [Gemini](https://ai.google.dev/) picks
 
 - **Setup:** you need a free Gemini API key. contextzip walks you through it the first time you use `--prompt`, or you can set the `GEMINI_API_KEY` environment variable.
 - **What is sent:** only the list of file **paths and sizes** that already passed the exclusion rules, plus your prompt. File contents never leave your machine.
-- **Fallback:** if Gemini is rate-limited or unreachable, a local keyword-based selector takes over, so `--prompt` keeps working.
+- **Fallback:** if Gemini is rate-limited, a local keyword-based selector takes over, so `--prompt` keeps working. Other errors (a bad key, no network) stop with a clear message.
 - **Model:** `gemini-2.5-flash-lite` by default.
 
 ### Applying AI changes back
@@ -174,17 +191,25 @@ contextzip apply-zip fix.zip      # or point at one directly
 contextzip apply-zip --dry-run    # preview without writing anything
 ```
 
-Every ZIP contextzip creates gets a **local manifest** containing a hash of each file. It's stored next to the ZIP and never inside it, so the AI tool never sees it. When a ZIP comes back, `apply-zip` compares every file against that manifest:
+AI tools return ZIPs in every shape: wrapped in an extra folder, relative to a subfolder, flattened, with Windows separators. `apply-zip` matches each file to its real place in your project anyway, and new files follow their siblings.
+
+Every ZIP contextzip makes gets a **local snapshot** (a hash of each file, never uploaded). `apply-zip` picks the snapshot that best matches the returned ZIP and compares three versions of each file: what you sent, what's on disk now, and what came back.
 
-| Status | Meaning | Action |
+| Status | Meaning | Default |
 |---|---|---|
-| **New** | File didn't exist before | Written |
-| **Modified** | AI changed it, and you haven't touched it locally | Written |
-| **Unchanged** | Identical to what's on disk | Skipped |
-| **Drifted** | *You* edited it locally since zipping | ⚠️ Asks before overwriting |
-| **Untracked** | Exists locally but wasn't in the original ZIP | ⚠️ Asks before overwriting |
+| **New** / **Modified** | New file, or only the AI changed it | Written |
+| **Merged** | You both changed it, in different places | Written (three-way merge) |
+| **Unchanged** | Already matches — including changes you already applied | Skipped |
+| **Conflict** | You both changed the same or neighbouring lines | Needs your call |
+| **Partial** | The AI returned a cut-down file (`// ... rest unchanged`) | Needs your call |
+| **Moved** | The AI moved or renamed it | Written at the new path; the old file is kept unless you say otherwise |
+| **Drifted** / **Deleted** / **Untracked** / **Ambiguous** / **Delete requested** | Can't be applied safely without you | Needs your call |
+
+When something needs a decision you choose: apply the safe changes now, **review side by side in your browser** (`--review`), **resolve in VS Code's merge editor** (`--editor`), or apply everything. Line endings never count as a change, redacted secrets are never overwritten with placeholders, and **files are only removed with your explicit OK** — never one you've changed since.
+
+### Snapshots and CONTEXTZIP.md
 
-`apply-zip` only adds and modifies files. **It never deletes anything.** It also unwraps the extra top-level folder that AI tools and "Download ZIP" buttons often add.
+Every package is kept locally as a numbered **snapshot** (`#14`), so a reply can be merged against exactly what you sent, even after you've packaged again. Each ZIP also carries a short **`CONTEXTZIP.md`** for the AI: the snapshot ID, and how to reply so the answer applies cleanly (complete files, same paths, secrets left as `[REDACTED]`, moves and deletions listed). When the reply echoes it back, `apply-zip` knows the exact snapshot. `contextzip snapshots` lists them; turn the file off with `"zip_guide": false`.
 
 ### Terminal error watcher
 
@@ -240,7 +265,7 @@ This opens a local browser tab where you can tick files and folders to always in
 
 Every command supports `-h` / `--help`, and `contextzip --version` prints the installed version.
 
-For every flag of every subcommand (`apply-zip`, `watch`, `config`, `update`), see **[CLI.md](https://github.com/akadeepesh/contextzip/blob/main/CLI.md)** or the [online CLI reference](https://contextzip.vercel.app/cli).
+For every flag of every subcommand (`apply-zip`, `watch`, `config`, `update`), see **[CLI.md](https://github.com/akadeepesh/contextzip/blob/main/CLI.md)** or the [online CLI reference](https://www.contextzipcli.com/cli).
 
 ## Configuration
 
@@ -266,6 +291,8 @@ This holds per-project settings. Edit it by hand or with `contextzip config --ui
   },
   "applied_zip_retention": 1,                  // past apply-zip archives to keep
   "cleanup": { "enabled": true, "keep_recent": 1 },
+  "snapshots": { "keep": 10, "max_age_days": 14 },  // history apply-zip merges against
+  "zip_guide": true,                           // add CONTEXTZIP.md to every ZIP
   "webui": { "auto_open": true, "port": null }
 }
 ```
@@ -288,7 +315,7 @@ contextzip config --set-workspace cwd      # put .contextzip/ in the current dir
 contextzip config --show-key-path          # print the config file location
 ```
 
-The full option-by-option guide is at [contextzip.vercel.app/configuration](https://contextzip.vercel.app/configuration).
+The full option-by-option guide is at [contextzipcli.com/configuration](https://www.contextzipcli.com/configuration).
 
 ## What is always excluded
 
@@ -328,11 +355,12 @@ contextzip keeps everything in a `.contextzip/` folder at your git root (change
 │   ├── git-changes/   changes.zip + manifest + report    (--git-changes)
 │   ├── prompt/        vibe.zip + manifest + report       (--prompt)
 │   └── watch/         debug-context.zip                  (contextzip watch)
+├── snapshots/         numbered copies of what you sent   (contextzip snapshots)
 ├── inbox/             drop AI-returned ZIPs here for apply-zip
 └── config.json        project config (optional)
 ```
 
-Old outputs are cleaned up automatically, and only the most recent set is kept. You can change this with the `cleanup` setting.
+Old outputs are cleaned up automatically: `output/` keeps the latest ZIP per mode (`cleanup`), and `snapshots/` keeps the newest 10 or anything under 14 days old (`snapshots`) — never one a reply in the inbox is waiting on.
 
 ## Python API
 
@@ -365,7 +393,7 @@ print(detect_ecosystem("."))
 
 All exceptions inherit from `ContextzipError`: `NotARepositoryError`, `GitNotFoundError`, `GitCommandError`, `NoFilesError` and `ZipNotFoundError`.
 
-For full signatures, see [contextzip.vercel.app/cli#python-api](https://contextzip.vercel.app/cli#python-api).
+For full signatures, see [contextzipcli.com/cli#python-api](https://www.contextzipcli.com/cli#python-api).
 
 ## Privacy & security
 
@@ -391,7 +419,7 @@ If the clipboard can't be used, contextzip opens the output folder with the ZIP
 
 ## Contributing
 
-Contributions are welcome, especially **new framework rule sets** and edge-case fixes. Not up for writing code? [Request a feature](https://contextzip.vercel.app/request-feature) or [request your language](https://contextzip.vercel.app/request-language). Both turn into GitHub issues ranked by 👍. To set up a local copy:
+Contributions are welcome, especially **new framework rule sets** and edge-case fixes. Not up for writing code? [Request a feature](https://www.contextzipcli.com/request-feature) or [request your language](https://www.contextzipcli.com/request-language). Both turn into GitHub issues ranked by 👍. To set up a local copy:
 
 ```bash
 git clone https://github.com/akadeepesh/contextzip

{contextzip-0.4.7 → contextzip-0.5.1}/README.md

@@ -9,7 +9,7 @@
 [![Downloads](https://static.pepy.tech/badge/contextzip/month)](https://pepy.tech/project/contextzip)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/akadeepesh/contextzip/blob/main/LICENSE)
 
-[Documentation](https://contextzip.vercel.app) ·
+[Documentation](https://www.contextzipcli.com) ·
 [CLI reference](https://github.com/akadeepesh/contextzip/blob/main/CLI.md) ·
 [Changelog](https://github.com/akadeepesh/contextzip/blob/main/CHANGELOG.md) ·
 [Report a bug](https://github.com/akadeepesh/contextzip/issues/new/choose)
@@ -36,6 +36,7 @@ When the AI sends changed files back, `contextzip apply-zip` writes them into yo
 ## Table of contents
 
 - [Installation](#installation)
+  - ["`cz` is not recognized"](#cz-is-not-recognized--command-not-found)
 - [Quick start](#quick-start)
 - [Features](#features)
   - [Smart packaging](#smart-packaging)
@@ -74,6 +75,20 @@ This installs two commands that do the same thing: `contextzip` and the shorter
 
 To update later, run `contextzip update`. It works out whether you installed with pip, pipx or uv and upgrades the right one.
 
+### "`cz` is not recognized" / "command not found"
+
+pip installed contextzip, but put the `cz` command in a folder your terminal doesn't search. This is common with Python from the Microsoft Store or the Python install manager on Windows, and with `pip install --user` on macOS and Linux. Look for pip's `WARNING: The scripts cz.exe and contextzip.exe are installed in '…' which is not on PATH.`
+
+Python itself always works, so run contextzip through it and let it fix PATH for you:
+
+```bash
+python -m contextzip setup-path     # macOS / Linux: python3 -m contextzip setup-path
+```
+
+On Windows this adds the folder to your user PATH (no admin needed). On macOS and Linux it adds one line to your shell's startup file. Open a new terminal and `cz` works. Until then, `python -m contextzip` does everything `cz` does.
+
+If you installed with pipx, run `pipx ensurepath`. With uv, run `uv tool update-shell`.
+
 ## Quick start
 
 ```bash
@@ -91,6 +106,7 @@ contextzip --git-changes                    # only what you've changed
 contextzip --prompt "fix the login redirect bug"   # let AI pick the relevant files
 contextzip include src/ app/                # only these folders
 contextzip include src/ .env                # .env too, values redacted
+contextzip --here                           # only the folder you're in (monorepos)
 contextzip exclude tests/ '*.snap'          # everything except these
 contextzip apply-zip                        # write the AI's changes back
 ```
@@ -134,7 +150,7 @@ Describe your task in plain language and [Gemini](https://ai.google.dev/) picks
 
 - **Setup:** you need a free Gemini API key. contextzip walks you through it the first time you use `--prompt`, or you can set the `GEMINI_API_KEY` environment variable.
 - **What is sent:** only the list of file **paths and sizes** that already passed the exclusion rules, plus your prompt. File contents never leave your machine.
-- **Fallback:** if Gemini is rate-limited or unreachable, a local keyword-based selector takes over, so `--prompt` keeps working.
+- **Fallback:** if Gemini is rate-limited, a local keyword-based selector takes over, so `--prompt` keeps working. Other errors (a bad key, no network) stop with a clear message.
 - **Model:** `gemini-2.5-flash-lite` by default.
 
 ### Applying AI changes back
@@ -145,17 +161,25 @@ contextzip apply-zip fix.zip      # or point at one directly
 contextzip apply-zip --dry-run    # preview without writing anything
 ```
 
-Every ZIP contextzip creates gets a **local manifest** containing a hash of each file. It's stored next to the ZIP and never inside it, so the AI tool never sees it. When a ZIP comes back, `apply-zip` compares every file against that manifest:
+AI tools return ZIPs in every shape: wrapped in an extra folder, relative to a subfolder, flattened, with Windows separators. `apply-zip` matches each file to its real place in your project anyway, and new files follow their siblings.
+
+Every ZIP contextzip makes gets a **local snapshot** (a hash of each file, never uploaded). `apply-zip` picks the snapshot that best matches the returned ZIP and compares three versions of each file: what you sent, what's on disk now, and what came back.
 
-| Status | Meaning | Action |
+| Status | Meaning | Default |
 |---|---|---|
-| **New** | File didn't exist before | Written |
-| **Modified** | AI changed it, and you haven't touched it locally | Written |
-| **Unchanged** | Identical to what's on disk | Skipped |
-| **Drifted** | *You* edited it locally since zipping | ⚠️ Asks before overwriting |
-| **Untracked** | Exists locally but wasn't in the original ZIP | ⚠️ Asks before overwriting |
+| **New** / **Modified** | New file, or only the AI changed it | Written |
+| **Merged** | You both changed it, in different places | Written (three-way merge) |
+| **Unchanged** | Already matches — including changes you already applied | Skipped |
+| **Conflict** | You both changed the same or neighbouring lines | Needs your call |
+| **Partial** | The AI returned a cut-down file (`// ... rest unchanged`) | Needs your call |
+| **Moved** | The AI moved or renamed it | Written at the new path; the old file is kept unless you say otherwise |
+| **Drifted** / **Deleted** / **Untracked** / **Ambiguous** / **Delete requested** | Can't be applied safely without you | Needs your call |
+
+When something needs a decision you choose: apply the safe changes now, **review side by side in your browser** (`--review`), **resolve in VS Code's merge editor** (`--editor`), or apply everything. Line endings never count as a change, redacted secrets are never overwritten with placeholders, and **files are only removed with your explicit OK** — never one you've changed since.
+
+### Snapshots and CONTEXTZIP.md
 
-`apply-zip` only adds and modifies files. **It never deletes anything.** It also unwraps the extra top-level folder that AI tools and "Download ZIP" buttons often add.
+Every package is kept locally as a numbered **snapshot** (`#14`), so a reply can be merged against exactly what you sent, even after you've packaged again. Each ZIP also carries a short **`CONTEXTZIP.md`** for the AI: the snapshot ID, and how to reply so the answer applies cleanly (complete files, same paths, secrets left as `[REDACTED]`, moves and deletions listed). When the reply echoes it back, `apply-zip` knows the exact snapshot. `contextzip snapshots` lists them; turn the file off with `"zip_guide": false`.
 
 ### Terminal error watcher
 
@@ -211,7 +235,7 @@ This opens a local browser tab where you can tick files and folders to always in
 
 Every command supports `-h` / `--help`, and `contextzip --version` prints the installed version.
 
-For every flag of every subcommand (`apply-zip`, `watch`, `config`, `update`), see **[CLI.md](https://github.com/akadeepesh/contextzip/blob/main/CLI.md)** or the [online CLI reference](https://contextzip.vercel.app/cli).
+For every flag of every subcommand (`apply-zip`, `watch`, `config`, `update`), see **[CLI.md](https://github.com/akadeepesh/contextzip/blob/main/CLI.md)** or the [online CLI reference](https://www.contextzipcli.com/cli).
 
 ## Configuration
 
@@ -237,6 +261,8 @@ This holds per-project settings. Edit it by hand or with `contextzip config --ui
   },
   "applied_zip_retention": 1,                  // past apply-zip archives to keep
   "cleanup": { "enabled": true, "keep_recent": 1 },
+  "snapshots": { "keep": 10, "max_age_days": 14 },  // history apply-zip merges against
+  "zip_guide": true,                           // add CONTEXTZIP.md to every ZIP
   "webui": { "auto_open": true, "port": null }
 }
 ```
@@ -259,7 +285,7 @@ contextzip config --set-workspace cwd      # put .contextzip/ in the current dir
 contextzip config --show-key-path          # print the config file location
 ```
 
-The full option-by-option guide is at [contextzip.vercel.app/configuration](https://contextzip.vercel.app/configuration).
+The full option-by-option guide is at [contextzipcli.com/configuration](https://www.contextzipcli.com/configuration).
 
 ## What is always excluded
 
@@ -299,11 +325,12 @@ contextzip keeps everything in a `.contextzip/` folder at your git root (change
 │   ├── git-changes/   changes.zip + manifest + report    (--git-changes)
 │   ├── prompt/        vibe.zip + manifest + report       (--prompt)
 │   └── watch/         debug-context.zip                  (contextzip watch)
+├── snapshots/         numbered copies of what you sent   (contextzip snapshots)
 ├── inbox/             drop AI-returned ZIPs here for apply-zip
 └── config.json        project config (optional)
 ```
 
-Old outputs are cleaned up automatically, and only the most recent set is kept. You can change this with the `cleanup` setting.
+Old outputs are cleaned up automatically: `output/` keeps the latest ZIP per mode (`cleanup`), and `snapshots/` keeps the newest 10 or anything under 14 days old (`snapshots`) — never one a reply in the inbox is waiting on.
 
 ## Python API
 
@@ -336,7 +363,7 @@ print(detect_ecosystem("."))
 
 All exceptions inherit from `ContextzipError`: `NotARepositoryError`, `GitNotFoundError`, `GitCommandError`, `NoFilesError` and `ZipNotFoundError`.
 
-For full signatures, see [contextzip.vercel.app/cli#python-api](https://contextzip.vercel.app/cli#python-api).
+For full signatures, see [contextzipcli.com/cli#python-api](https://www.contextzipcli.com/cli#python-api).
 
 ## Privacy & security
 
@@ -362,7 +389,7 @@ If the clipboard can't be used, contextzip opens the output folder with the ZIP
 
 ## Contributing
 
-Contributions are welcome, especially **new framework rule sets** and edge-case fixes. Not up for writing code? [Request a feature](https://contextzip.vercel.app/request-feature) or [request your language](https://contextzip.vercel.app/request-language). Both turn into GitHub issues ranked by 👍. To set up a local copy:
+Contributions are welcome, especially **new framework rule sets** and edge-case fixes. Not up for writing code? [Request a feature](https://www.contextzipcli.com/request-feature) or [request your language](https://www.contextzipcli.com/request-language). Both turn into GitHub issues ranked by 👍. To set up a local copy:
 
 ```bash
 git clone https://github.com/akadeepesh/contextzip

{contextzip-0.4.7 → contextzip-0.5.1}/contextzip/__init__.py

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

contextzip-0.5.1/contextzip/__main__.py

@@ -0,0 +1,37 @@
+"""
+`python -m contextzip` — works even when the `cz` command isn't on PATH.
+
+When that's why it's being used, a one-line tip points to `setup-path`.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def _path_tip() -> None:
+    if len(sys.argv) > 1 and sys.argv[1] == "setup-path":
+        return
+    if not sys.stderr.isatty():
+        return
+    try:
+        from contextzip import pathsetup
+
+        st = pathsetup.status()
+        if st.directory is None or st.on_path or st.manager or st.in_venv:
+            return
+    except Exception:  # noqa: BLE001 — a tip must never break the run
+        return
+    from rich.console import Console
+
+    Console(stderr=True).print(
+        "[dim]Tip: the cz command isn't on your PATH yet — run "
+        "[bold]python -m contextzip setup-path[/] to fix that.[/]"
+    )
+
+
+if __name__ == "__main__":
+    from contextzip.cli import main
+
+    _path_tip()
+    main()

{contextzip-0.4.7 → contextzip-0.5.1}/contextzip/api.py

@@ -35,7 +35,6 @@ Quickstart
 
 from __future__ import annotations
 
-import os
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -158,7 +157,7 @@ def get_git_changes(
     Parameters
     ----------
     path:
-        Directory to start from. Defaults to ``Path.cwd()``. The actual
+        Directory to start from. Defaults to the project root found from the current folder. The actual
         git root may be a parent of this directory.
     use_project_config:
         Apply the project's ``.contextzip/config.json``. Defaults to
@@ -234,7 +233,7 @@ def get_files(
     Parameters
     ----------
     path:
-        Project root to scan. Defaults to ``Path.cwd()``.
+        Project root to scan. Defaults to the project root found from the current folder.
     include:
         If given, only files under these paths are returned (e.g.
         ``["src/", "app/"]``). Matched as exact path prefixes.
@@ -358,10 +357,14 @@ def create_zip(
 
     output_path = Path(output).resolve() if output is not None else None
 
+    project_cfg = load_project_config(collection.project_dir)
     return create_zip_silent(
         resolve_result=resolve_result,
         project_dir=collection.project_dir,
         output_path=output_path,
+        redact_secrets_enabled=project_cfg.limits.redact_secrets,
+        ecosystem=collection.ecosystem,
+        guide=project_cfg.zip_guide,
     )
 
 
@@ -370,20 +373,23 @@ def apply_zip(
     *,
     project_dir: str | Path | None = None,
     manifest: str | Path | None = None,
+    include_risky: bool = False,
 ) -> ApplyResult:
     """
     Apply an AI-returned ZIP back into *project_dir* (defaults to cwd).
 
-    Diffs the zip against the local sidecar manifest most recently written
-    to ``.contextzip/output/`` (or the one at *manifest*, if given) to
-    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.
+    Each file is matched to its place in the project (even when the zip is
+    wrapped, relative to a subfolder, or flattened), then compared with the
+    snapshot of what was sent and with the file on disk. New, modified and
+    cleanly merged files are written. Files that need a decision —
+    conflicts, partial files, ones you deleted or that weren't sent, and
+    ambiguous ones — are left alone unless *include_risky* is True, in which
+    case the AI's version wins. Nothing is removed — moved files keep their
+    old copy and requested deletions are skipped; use
+    ``execute_plan(..., remove_moved=True, allow_delete=True)`` to opt in.
 
-    Unlike the CLI, this applies immediately and does not prompt — check
-    ``contextzip.applier.build_plan()`` yourself first if you want to
-    inspect risk before writing (see ``ApplyPlan.is_risky`` /
-    ``.risky_entries``).
+    Doesn't prompt. To inspect first, use ``contextzip.applier.build_plan()``
+    and ``execute_plan(..., decisions=...)`` directly.
 
     Parameters
     ----------
@@ -391,15 +397,20 @@ def apply_zip(
         Path to the returned zip. If omitted, auto-detects from
         ``.contextzip/inbox/`` — exactly one zip must be present there.
     project_dir:
-        Project root to apply into. Defaults to ``Path.cwd()``.
+        Project root to apply into. Defaults to the project root found from the current folder.
     manifest:
-        Explicit manifest path to diff against, overriding auto-detection.
+        Snapshot (manifest) to compare against. By default the one that
+        best matches the zip is picked automatically.
+    include_risky:
+        Also write files that need a decision, with the AI's version
+        winning. Defaults to False.
 
     Returns
     -------
     ApplyResult
-        ``written`` (list of relative paths written) and
-        ``applied_zip_path`` (where the consumed zip ended up).
+        ``written`` (relative paths written), ``skipped`` (paths left alone)
+        and ``applied_zip_path`` (where the zip ended up — it stays in the
+        inbox while something still needs a decision).
 
     Raises
     ------
@@ -431,9 +442,9 @@ def apply_zip(
     except ApplyError as exc:
         raise ZipNotFoundError(str(exc)) from exc
 
-    manifest_path = find_latest_manifest(pdir, manifest)
+    manifest_path = find_latest_manifest(pdir, manifest) if manifest is not None else None
     plan = build_plan(resolved_zip, pdir, manifest_path)
-    return execute_plan(plan, pdir)
+    return execute_plan(plan, pdir, include_risky=include_risky)
 
 
 def detect_ecosystem(
@@ -445,7 +456,7 @@ def detect_ecosystem(
     Parameters
     ----------
     path:
-        Directory to inspect. Defaults to ``Path.cwd()``.
+        Directory to inspect. Defaults to the project root found from the current folder.
 
     Returns
     -------
@@ -498,8 +509,16 @@ def _config_kwargs(cfg, extra_exclude: list[str] | None = None) -> dict:
 
 
 def _resolve_dir(path: str | Path | None) -> Path:
+    """
+    An explicit *path* is used exactly as given. Without one, resolve the
+    project root from the current folder — the same root the CLI uses (see
+    root.find_project_root) — so a script run from a subfolder of a
+    monorepo still works on the whole project with root-relative paths.
+    """
     if path is None:
-        return Path(os.getcwd()).resolve()
+        from contextzip.root import find_project_root
+
+        return find_project_root().root
     return Path(path).resolve()