contextzip 0.3.4__tar.gz → 0.3.6__tar.gz

{contextzip-0.3.4 → contextzip-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: contextzip
-Version: 0.3.4
+Version: 0.3.6
 Summary: Intelligently package your codebase for AI tools
 Author-email: Deepesh <akadeepesh@gmail.com>
 License-Expression: MIT
@@ -47,13 +47,13 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 
 ## Features
 
-- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each
+- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each. Detection isn't limited to the project root: a shallow, bounded scan of subdirectories means a monorepo (`frontend/` + `backend/`, etc.) gets every ecosystem it contains detected and excluded correctly, not just whatever sits at the top level
 - **Respects `.gitignore`** — your existing ignore patterns are honoured automatically
 - **Git-aware packaging** — use `--git-changes` to package only modified, staged, and untracked files; perfect for incremental debugging and PR review sessions
 - **AI-powered file selection** — describe your task in plain English with `--prompt` and Gemini selects the minimum relevant files automatically, no manual hunting required
 - **Terminal error watcher** — wrap any dev server with `contextzip watch` to auto-detect errors and package a ready-to-upload debug context in one keypress
-- **End-of-day / handoff prompts** — `contextzip eod` and `contextzip handoff` turn a Claude/ChatGPT conversation export plus today's code changes into a paste-ready prompt, copied straight to your clipboard
-- **Persistent workspace** — all generated ZIPs land in `.contextzip/` at your project root, discoverable, reusable, and git-ignored automatically
+- **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip/config.json`
+- **Persistent workspace** — all generated ZIPs land in `.contextzip/output/`, discoverable, reusable, and git-ignored automatically
 - **Warns before it's a problem** — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload
 - **Handles edge cases** — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped
 - **Full CLI control** — `--include`, `--exclude`, `--dry-run`, `--output`, all composable
@@ -95,7 +95,7 @@ contextzip will:
 
 1. Detect your framework (e.g. `Next.js + Node.js`)
 2. Apply the appropriate exclusion rules
-3. Create a compressed ZIP in `.contextzip/` at your project root
+3. Create a compressed ZIP in `.contextzip/output/` at your project root
 4. Open your file manager with the ZIP selected and ready to copy
 
 ---
@@ -106,6 +106,8 @@ contextzip will:
 contextzip [OPTIONS]
 ```
 
+> `cz` is a shorthand alias for `contextzip` — both commands are identical and support every option and subcommand shown below (e.g. `cz --git-changes`, `cz exclude node_modules`).
+
 | Option | Description |
 |---|---|
 | `-p`, `--prompt TEXT` | Describe your task in plain English — Gemini selects only the relevant files |
@@ -118,7 +120,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `watch`, `config`, `eod`, `handoff` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
 
 ---
 
@@ -226,7 +228,7 @@ contextzip starts your process normally. You see output exactly as you would wit
 ╰───────────────────────────────────────────────────╯
 ```
 
-Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Your server keeps running — no restart, no interruption.
+Press **D** and contextzip immediately writes `.contextzip/output/debug-context.zip`. Your server keeps running — no restart, no interruption.
 
 **What's in the ZIP:**
 
@@ -244,60 +246,109 @@ Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Y
 
 ---
 
-## End-of-day reports and chat handoffs
+## What gets excluded
 
-If you work through a problem in a Claude or ChatGPT conversation and need to either (a) summarize what you did for an end-of-day report, or (b) continue the same work in a fresh chat after hitting a usage limit, `eod` and `handoff` build the prompt for you — contextzip does no summarizing itself; that's left to whichever AI tool you paste the result into.
+contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.
+
+**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, and contextzip's own `.contextzip/` working folder.
+
+**By framework:**
+
+| Stack | Additional exclusions |
+|---|---|
+| Node.js / Next.js | `node_modules/`, `.next/`, `dist/`, `build/`, lock files, `*.min.js`, `*.d.ts` |
+| Python / Django / FastAPI | `__pycache__/`, `.venv/`, `*.pyc`, `migrations/`, `.pytest_cache/`, lock files |
+| Rust | `target/`, `Cargo.lock`, `*.rlib` |
+| Go | `vendor/`, `go.sum`, `bin/` |
+
+Detection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied. Marker files don't have to sit at the project root: contextzip also does a shallow, bounded scan of subdirectories (2 levels deep, skipping `node_modules/`, `.venv/`, `.git/`, and other dependency/build dirs it would never want to look inside anyway), so a layout like
 
-```bash
-contextzip eod
-contextzip handoff
+```
+root/
+  frontend/package.json
+  backend/requirements.txt
 ```
 
-**Setup:** export your conversation (any markdown export works) and drop the `.md` file into `exports/` at your project root. Both commands pick the most recently modified file there automatically.
+detects both Node.js and Python from `root/`, without either marker existing at the top level. Run with default output (not `--dry-run --verbose`) and you'll see which subdirectory each ecosystem came from, e.g. `Next.js (frontend/) + FastAPI (backend/)`.
 
-**What gets built:**
+---
 
-- The conversation itself — pasted directly into the prompt if it's short, or referenced as an attachment if it's long enough that inlining it would burn through the next chat's context budget
-- Whatever code changed, resolved per file in priority order:
-  1. **Not pushed** — diffed against your upstream branch, plus the complete current file
-  2. **Diverged from Claude** — diffed against the version Claude last produced (if you've set up a session key — see below), plus the complete current codebase file
-  3. **Since last run** — diffed against a per-branch checkpoint that `eod`/`handoff` remember automatically, plus the complete current file
-- New, untracked files are included as full content (there's nothing to diff them against)
-- `eod` ends the prompt with a flat instruction to produce a work-log table; `handoff` frames it as continuing the project in a new chat
+## Workspace location
 
-The result is copied straight to your clipboard, and also saved to `.contextzip/` if you want to look it over first.
+By default, `.contextzip/` is created at your git root — that's `_find_git_root()` walking up from the current directory until it finds a `.git` folder; outside a repo, it falls back to the current directory. This can be overridden two ways, in order of priority:
 
-**Optional — diffing against Claude's own version (case 2):** if you give contextzip your Claude.ai session key, `eod`/`handoff` will fetch the files Claude actually produced and compare them against your codebase, catching drift even after everything's pushed and in sync.
+1. **`CONTEXTZIP_WORKSPACE_LOCATION` environment variable** — for a one-off override on a single run
+2. **A committed `.contextzip/config.json` at the project root** — team-shared, applies to everyone who clones the repo:
+   ```json
+   { "workspace_location": "git-root" }
+   ```
+3. **Your personal config** — a per-machine default that doesn't get committed:
+   ```bash
+   contextzip config --set-workspace cwd          # always use ./.contextzip wherever you run it
+   contextzip config --set-workspace git-root      # back to the default
+   contextzip config --set-workspace ~/zips        # a fixed custom location, anywhere
+   contextzip config --reset-workspace             # clear your personal override
+   ```
 
-```bash
-contextzip config --set-session-key
-```
+Accepted values are `"git-root"`, `"cwd"`, or any path (absolute, or relative to the git root). Run `contextzip config` with no flags to see which value is currently active and where it came from.
 
-This is best-effort by design — it depends on an undocumented Claude.ai endpoint, so a missing key, an expired cookie, or the endpoint changing shape just skips this check with a warning rather than failing the whole command.
+This matters most for monorepos where you sometimes run contextzip from a subdirectory (`cd frontend && contextzip`) — with the default `git-root` setting, the workspace still lands at the repo root no matter where you ran it from, so you don't end up with scattered `.contextzip/` folders across `frontend/`, `backend/`, etc. Set `workspace_location: "cwd"` in a project's `.contextzip/config.json` instead if you'd rather each subproject keep its own.
+
+---
+
+## Project configuration
+
+Every project gets a `.contextzip/` workspace at the project root:
 
-```bash
-contextzip eod --dry-run        # preview without advancing the checkpoint
-contextzip handoff --no-fetch   # skip the Claude-artifact fetch for this run
+```
+.contextzip/
+├── config.json     # project preferences — commit this
+├── .gitignore       # keeps output/ untracked, config.json trackable
+└── output/          # generated ZIPs — never committed
+    ├── codebase.zip
+    ├── changes.zip       (--git-changes)
+    └── debug-context.zip (contextzip watch)
 ```
 
----
+`.contextzip/` is **not** committed to Git by default — `.contextzip/.gitignore` is written automatically the first time you run contextzip in a repo, and it ignores everything in the folder *except* `config.json` and itself. That's deliberate: `output/` is per-machine, disposable scratch space, while `config.json` holds team-shared preferences you'll usually want everyone on the same page about.
+
+`config.json` currently supports:
+
+```json
+{
+  "workspace_location": "git-root",
+  "scan_depth": null,
+  "always_include": [],
+  "always_exclude": [],
+  "ai": {
+    "enabled": true,
+    "provider": "gemini",
+    "max_files": 10
+  }
+}
+```
 
-## What gets excluded
+All keys are optional — start with just the ones you need.
 
-contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.
+| Key | What it does |
+| --- | --- |
+| `workspace_location` | Same as `contextzip config --set-workspace`, but team-shared. See [Workspace location](#workspace-location). |
+| `scan_depth` | Reserved for a future bounded-depth scan mode. |
+| `always_include` | A standing "force include" list (gitwildmatch patterns). Files matching it are packaged even if an auto-rule or `.gitignore` would otherwise exclude them — e.g. `["docs/architecture.md"]` to always pull in a doc that lives in an otherwise-excluded folder. |
+| `always_exclude` | A standing exclusion list, applied on every run without retyping `-e`/`--exclude`. |
+| `ai.enabled` | Set to `false` to disable `--prompt` entirely for this project; contextzip will refuse with a clear message instead of silently ignoring it. |
+| `ai.provider` | Reserved for future AI providers. Only `"gemini"` is currently supported. |
+| `ai.max_files` | Caps how many files `--prompt` mode may return, for both the Gemini and keyword-heuristic paths. |
 
-**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, and contextzip's own `.contextzip/` and `exports/` working folders.
+`always_include`/`always_exclude` are additive on top of `--include`/`--exclude` for that run — an explicit `contextzip include PATH` still has the final say over what's actually packaged. Persistent preferences belong in `config.json` rather than an ever-growing list of CLI flags; CLI flags stay for one-off, explicit actions (`--dry-run`, `--prompt "…"`, `--output FILE`, etc.).
 
-**By framework:**
+A **web-based configuration UI** that generates `config.json` for you is on the roadmap — the schema above is designed to grow additively, so future preferences (including ones set visually) won't require another migration.
 
-| Stack | Additional exclusions |
-|---|---|
-| Node.js / Next.js | `node_modules/`, `.next/`, `dist/`, `build/`, lock files, `*.min.js`, `*.d.ts` |
-| Python / Django / FastAPI | `__pycache__/`, `.venv/`, `*.pyc`, `migrations/`, `.pytest_cache/`, lock files |
-| Rust | `target/`, `Cargo.lock`, `*.rlib` |
-| Go | `vendor/`, `go.sum`, `bin/` |
+### Deprecation: `.contextzip.json`
+
+Earlier versions of contextzip read a `.contextzip.json` file at the project root for `workspace_location`/`scan_depth`. That file is now **deprecated** in favor of `.contextzip/config.json` — contextzip still reads it automatically if `.contextzip/config.json` doesn't exist yet (so nothing breaks), and prints a one-time reminder to migrate. To migrate, just move its contents into the `"workspace_location"`/`"scan_depth"` keys of a new `.contextzip/config.json` and delete the old file.
 
-Detection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied.
+`~/.config/contextzip/config.json` (your personal, per-machine config — API key, personal workspace override) is unrelated and unaffected by any of this.
 
 ---
 

{contextzip-0.3.4 → contextzip-0.3.6}/README.md

@@ -18,13 +18,13 @@ contextzip eliminates that entirely. Run it from your project root — it detect
 
 ## Features
 
-- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each
+- **Smart framework detection** — automatically identifies Node.js, Next.js, Python, Django, FastAPI, Rust, Go, and Ruby, applying the right exclusion rules for each. Detection isn't limited to the project root: a shallow, bounded scan of subdirectories means a monorepo (`frontend/` + `backend/`, etc.) gets every ecosystem it contains detected and excluded correctly, not just whatever sits at the top level
 - **Respects `.gitignore`** — your existing ignore patterns are honoured automatically
 - **Git-aware packaging** — use `--git-changes` to package only modified, staged, and untracked files; perfect for incremental debugging and PR review sessions
 - **AI-powered file selection** — describe your task in plain English with `--prompt` and Gemini selects the minimum relevant files automatically, no manual hunting required
 - **Terminal error watcher** — wrap any dev server with `contextzip watch` to auto-detect errors and package a ready-to-upload debug context in one keypress
-- **End-of-day / handoff prompts** — `contextzip eod` and `contextzip handoff` turn a Claude/ChatGPT conversation export plus today's code changes into a paste-ready prompt, copied straight to your clipboard
-- **Persistent workspace** — all generated ZIPs land in `.contextzip/` at your project root, discoverable, reusable, and git-ignored automatically
+- **Configurable workspace location** — `.contextzip/` lives at the git root by default, but you can pin it elsewhere per-machine (`contextzip config --set-workspace`) or for the whole team via a committed `.contextzip/config.json`
+- **Persistent workspace** — all generated ZIPs land in `.contextzip/output/`, discoverable, reusable, and git-ignored automatically
 - **Warns before it's a problem** — flags large (≥ 1 MB) and binary files that AI tools can't read, before you waste an upload
 - **Handles edge cases** — dangling symlinks, unreadable files, and paths outside the project tree are caught and reported, never silently dropped
 - **Full CLI control** — `--include`, `--exclude`, `--dry-run`, `--output`, all composable
@@ -66,7 +66,7 @@ contextzip will:
 
 1. Detect your framework (e.g. `Next.js + Node.js`)
 2. Apply the appropriate exclusion rules
-3. Create a compressed ZIP in `.contextzip/` at your project root
+3. Create a compressed ZIP in `.contextzip/output/` at your project root
 4. Open your file manager with the ZIP selected and ready to copy
 
 ---
@@ -77,6 +77,8 @@ contextzip will:
 contextzip [OPTIONS]
 ```
 
+> `cz` is a shorthand alias for `contextzip` — both commands are identical and support every option and subcommand shown below (e.g. `cz --git-changes`, `cz exclude node_modules`).
+
 | Option | Description |
 |---|---|
 | `-p`, `--prompt TEXT` | Describe your task in plain English — Gemini selects only the relevant files |
@@ -89,7 +91,7 @@ contextzip [OPTIONS]
 | `--no-clipboard` | Skip the clipboard / folder-open step |
 | `--no-gitignore` | Ignore the project's `.gitignore` |
 
-**Subcommands:** `exclude`, `include`, `watch`, `config`, `eod`, `handoff` — run `contextzip --help` for full details.
+**Subcommands:** `exclude`, `include`, `watch`, `config` — run `contextzip --help` for full details.
 
 ---
 
@@ -197,7 +199,7 @@ contextzip starts your process normally. You see output exactly as you would wit
 ╰───────────────────────────────────────────────────╯
 ```
 
-Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Your server keeps running — no restart, no interruption.
+Press **D** and contextzip immediately writes `.contextzip/output/debug-context.zip`. Your server keeps running — no restart, no interruption.
 
 **What's in the ZIP:**
 
@@ -215,60 +217,109 @@ Press **D** and contextzip immediately writes `.contextzip/debug-context.zip`. Y
 
 ---
 
-## End-of-day reports and chat handoffs
+## What gets excluded
 
-If you work through a problem in a Claude or ChatGPT conversation and need to either (a) summarize what you did for an end-of-day report, or (b) continue the same work in a fresh chat after hitting a usage limit, `eod` and `handoff` build the prompt for you — contextzip does no summarizing itself; that's left to whichever AI tool you paste the result into.
+contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.
+
+**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, and contextzip's own `.contextzip/` working folder.
+
+**By framework:**
+
+| Stack | Additional exclusions |
+|---|---|
+| Node.js / Next.js | `node_modules/`, `.next/`, `dist/`, `build/`, lock files, `*.min.js`, `*.d.ts` |
+| Python / Django / FastAPI | `__pycache__/`, `.venv/`, `*.pyc`, `migrations/`, `.pytest_cache/`, lock files |
+| Rust | `target/`, `Cargo.lock`, `*.rlib` |
+| Go | `vendor/`, `go.sum`, `bin/` |
+
+Detection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied. Marker files don't have to sit at the project root: contextzip also does a shallow, bounded scan of subdirectories (2 levels deep, skipping `node_modules/`, `.venv/`, `.git/`, and other dependency/build dirs it would never want to look inside anyway), so a layout like
 
-```bash
-contextzip eod
-contextzip handoff
+```
+root/
+  frontend/package.json
+  backend/requirements.txt
 ```
 
-**Setup:** export your conversation (any markdown export works) and drop the `.md` file into `exports/` at your project root. Both commands pick the most recently modified file there automatically.
+detects both Node.js and Python from `root/`, without either marker existing at the top level. Run with default output (not `--dry-run --verbose`) and you'll see which subdirectory each ecosystem came from, e.g. `Next.js (frontend/) + FastAPI (backend/)`.
 
-**What gets built:**
+---
 
-- The conversation itself — pasted directly into the prompt if it's short, or referenced as an attachment if it's long enough that inlining it would burn through the next chat's context budget
-- Whatever code changed, resolved per file in priority order:
-  1. **Not pushed** — diffed against your upstream branch, plus the complete current file
-  2. **Diverged from Claude** — diffed against the version Claude last produced (if you've set up a session key — see below), plus the complete current codebase file
-  3. **Since last run** — diffed against a per-branch checkpoint that `eod`/`handoff` remember automatically, plus the complete current file
-- New, untracked files are included as full content (there's nothing to diff them against)
-- `eod` ends the prompt with a flat instruction to produce a work-log table; `handoff` frames it as continuing the project in a new chat
+## Workspace location
 
-The result is copied straight to your clipboard, and also saved to `.contextzip/` if you want to look it over first.
+By default, `.contextzip/` is created at your git root — that's `_find_git_root()` walking up from the current directory until it finds a `.git` folder; outside a repo, it falls back to the current directory. This can be overridden two ways, in order of priority:
 
-**Optional — diffing against Claude's own version (case 2):** if you give contextzip your Claude.ai session key, `eod`/`handoff` will fetch the files Claude actually produced and compare them against your codebase, catching drift even after everything's pushed and in sync.
+1. **`CONTEXTZIP_WORKSPACE_LOCATION` environment variable** — for a one-off override on a single run
+2. **A committed `.contextzip/config.json` at the project root** — team-shared, applies to everyone who clones the repo:
+   ```json
+   { "workspace_location": "git-root" }
+   ```
+3. **Your personal config** — a per-machine default that doesn't get committed:
+   ```bash
+   contextzip config --set-workspace cwd          # always use ./.contextzip wherever you run it
+   contextzip config --set-workspace git-root      # back to the default
+   contextzip config --set-workspace ~/zips        # a fixed custom location, anywhere
+   contextzip config --reset-workspace             # clear your personal override
+   ```
 
-```bash
-contextzip config --set-session-key
-```
+Accepted values are `"git-root"`, `"cwd"`, or any path (absolute, or relative to the git root). Run `contextzip config` with no flags to see which value is currently active and where it came from.
 
-This is best-effort by design — it depends on an undocumented Claude.ai endpoint, so a missing key, an expired cookie, or the endpoint changing shape just skips this check with a warning rather than failing the whole command.
+This matters most for monorepos where you sometimes run contextzip from a subdirectory (`cd frontend && contextzip`) — with the default `git-root` setting, the workspace still lands at the repo root no matter where you ran it from, so you don't end up with scattered `.contextzip/` folders across `frontend/`, `backend/`, etc. Set `workspace_location: "cwd"` in a project's `.contextzip/config.json` instead if you'd rather each subproject keep its own.
+
+---
+
+## Project configuration
+
+Every project gets a `.contextzip/` workspace at the project root:
 
-```bash
-contextzip eod --dry-run        # preview without advancing the checkpoint
-contextzip handoff --no-fetch   # skip the Claude-artifact fetch for this run
+```
+.contextzip/
+├── config.json     # project preferences — commit this
+├── .gitignore       # keeps output/ untracked, config.json trackable
+└── output/          # generated ZIPs — never committed
+    ├── codebase.zip
+    ├── changes.zip       (--git-changes)
+    └── debug-context.zip (contextzip watch)
 ```
 
----
+`.contextzip/` is **not** committed to Git by default — `.contextzip/.gitignore` is written automatically the first time you run contextzip in a repo, and it ignores everything in the folder *except* `config.json` and itself. That's deliberate: `output/` is per-machine, disposable scratch space, while `config.json` holds team-shared preferences you'll usually want everyone on the same page about.
+
+`config.json` currently supports:
+
+```json
+{
+  "workspace_location": "git-root",
+  "scan_depth": null,
+  "always_include": [],
+  "always_exclude": [],
+  "ai": {
+    "enabled": true,
+    "provider": "gemini",
+    "max_files": 10
+  }
+}
+```
 
-## What gets excluded
+All keys are optional — start with just the ones you need.
 
-contextzip stacks exclusion rules based on your detected stack, on top of your `.gitignore`.
+| Key | What it does |
+| --- | --- |
+| `workspace_location` | Same as `contextzip config --set-workspace`, but team-shared. See [Workspace location](#workspace-location). |
+| `scan_depth` | Reserved for a future bounded-depth scan mode. |
+| `always_include` | A standing "force include" list (gitwildmatch patterns). Files matching it are packaged even if an auto-rule or `.gitignore` would otherwise exclude them — e.g. `["docs/architecture.md"]` to always pull in a doc that lives in an otherwise-excluded folder. |
+| `always_exclude` | A standing exclusion list, applied on every run without retyping `-e`/`--exclude`. |
+| `ai.enabled` | Set to `false` to disable `--prompt` entirely for this project; contextzip will refuse with a clear message instead of silently ignoring it. |
+| `ai.provider` | Reserved for future AI providers. Only `"gemini"` is currently supported. |
+| `ai.max_files` | Caps how many files `--prompt` mode may return, for both the Gemini and keyword-heuristic paths. |
 
-**Always excluded:** `.git/`, `.env` files, logs, caches, editor config (`.vscode/`, `.idea/`), OS files (`.DS_Store`, `Thumbs.db`), common binary formats, and contextzip's own `.contextzip/` and `exports/` working folders.
+`always_include`/`always_exclude` are additive on top of `--include`/`--exclude` for that run — an explicit `contextzip include PATH` still has the final say over what's actually packaged. Persistent preferences belong in `config.json` rather than an ever-growing list of CLI flags; CLI flags stay for one-off, explicit actions (`--dry-run`, `--prompt "…"`, `--output FILE`, etc.).
 
-**By framework:**
+A **web-based configuration UI** that generates `config.json` for you is on the roadmap — the schema above is designed to grow additively, so future preferences (including ones set visually) won't require another migration.
 
-| Stack | Additional exclusions |
-|---|---|
-| Node.js / Next.js | `node_modules/`, `.next/`, `dist/`, `build/`, lock files, `*.min.js`, `*.d.ts` |
-| Python / Django / FastAPI | `__pycache__/`, `.venv/`, `*.pyc`, `migrations/`, `.pytest_cache/`, lock files |
-| Rust | `target/`, `Cargo.lock`, `*.rlib` |
-| Go | `vendor/`, `go.sum`, `bin/` |
+### Deprecation: `.contextzip.json`
+
+Earlier versions of contextzip read a `.contextzip.json` file at the project root for `workspace_location`/`scan_depth`. That file is now **deprecated** in favor of `.contextzip/config.json` — contextzip still reads it automatically if `.contextzip/config.json` doesn't exist yet (so nothing breaks), and prints a one-time reminder to migrate. To migrate, just move its contents into the `"workspace_location"`/`"scan_depth"` keys of a new `.contextzip/config.json` and delete the old file.
 
-Detection is additive — a monorepo with both `package.json` and `pyproject.toml` gets both rule sets applied.
+`~/.config/contextzip/config.json` (your personal, per-machine config — API key, personal workspace override) is unrelated and unaffected by any of this.
 
 ---
 

{contextzip-0.3.4 → contextzip-0.3.6}/contextzip/__init__.py

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

{contextzip-0.3.4 → contextzip-0.3.6}/contextzip/ai/gemini.py

@@ -70,6 +70,7 @@ def select_files(
     file_tree: list[tuple[str, int]],  # [(rel_path, size_bytes), ...]
     ecosystem: str,
     model: str = DEFAULT_MODEL,
+    max_files: int | None = None,
 ) -> list[str]:
     """
     Ask Gemini which files are relevant to *prompt* and return their paths.
@@ -89,6 +90,11 @@ def select_files(
         Gives the model important context for relevance scoring.
     model:
         Gemini model identifier. Defaults to gemini-2.5-flash-lite.
+    max_files:
+        Hard cap on how many files may be returned, regardless of what the
+        model outputs. Defaults to _MAX_FILES (12) when omitted — typically
+        overridden by a project's `ai.max_files` preference
+        (.contextzip/config.json).
 
     Returns
     -------
@@ -110,7 +116,8 @@ def select_files(
             "Install it with: pip install httpx"
         )
 
-    system_prompt = _build_system_prompt()
+    effective_max_files = max_files if max_files and max_files > 0 else _MAX_FILES
+    system_prompt = _build_system_prompt(effective_max_files)
     user_message = _build_user_message(prompt, file_tree, ecosystem)
 
     url = _API_URL.format(model=model, key=api_key)
@@ -153,7 +160,7 @@ def select_files(
             f"Gemini API returned HTTP {response.status_code}: {response.text[:200]}"
         )
 
-    return _parse_response(response.json(), file_tree)
+    return _parse_response(response.json(), file_tree, effective_max_files)
 
 
 # ---------------------------------------------------------------------------
@@ -161,8 +168,8 @@ def select_files(
 # ---------------------------------------------------------------------------
 
 
-def _build_system_prompt() -> str:
-    return """\
+def _build_system_prompt(max_files: int = _MAX_FILES) -> str:
+    return f"""\
 You are a precise file relevance assistant for software projects.
 
 Your only job: given a developer's task description and a project file tree,
@@ -178,7 +185,7 @@ Rules you must follow:
 - Prefer files that will be MODIFIED over files that are merely referenced.
 - Config files, test files, and documentation should only appear if the
   task explicitly concerns them.
-- Never return more than 10 files. For most tasks 2–5 files is correct.
+- Never return more than {max_files} files. For most tasks 2–5 files is correct.
 - Order by relevance: most directly relevant file first.\
 """
 
@@ -209,13 +216,14 @@ Return only a JSON array of the most relevant file paths for this task.\
 def _parse_response(
     data: dict,
     file_tree: list[tuple[str, int]],
+    max_files: int = _MAX_FILES,
 ) -> list[str]:
     """
     Extract and validate the file list from the Gemini API response.
 
     - Parses the JSON array from the model's text output
     - Drops any path the model hallucinated (not in the real file tree)
-    - Enforces the _MAX_FILES hard cap
+    - Enforces the *max_files* hard cap
     - Warns (via exception) if the model returned mostly invalid paths
     """
     # Navigate the Gemini response structure
@@ -266,7 +274,7 @@ def _parse_response(
         )
 
     # Enforce hard cap
-    return validated[:_MAX_FILES]
+    return validated[:max_files]
 
 
 # ---------------------------------------------------------------------------

{contextzip-0.3.4 → contextzip-0.3.6}/contextzip/ai/heuristic.py

@@ -201,6 +201,7 @@ def select_files(
     *,
     prompt: str,
     file_tree: list[tuple[str, int]],
+    max_files: int | None = None,
 ) -> list[str]:
     """
     Score and rank *file_tree* entries by relevance to *prompt*.
@@ -212,18 +213,24 @@ def select_files(
     file_tree:
         Candidate files as (relative_posix_path, size_bytes) tuples.
         Standard exclusions must already have been applied by the caller.
+    max_files:
+        Cap on how many files may be returned. Defaults to MAX_FILES (8)
+        when omitted — typically overridden by a project's `ai.max_files`
+        preference (.contextzip/config.json).
 
     Returns
     -------
     list[str]
         Relative POSIX paths of the top-scoring files, best first.
-        Files scoring zero are excluded. Result is capped at MAX_FILES.
+        Files scoring zero are excluded. Result is capped at *max_files*.
     """
     tokens = _tokenize(prompt)
     if not tokens:
         # Degenerate prompt — return nothing rather than random files
         return []
 
+    effective_max_files = max_files if max_files and max_files > 0 else MAX_FILES
+
     scored: list[tuple[float, str]] = []
 
     for rel_path, size_bytes in file_tree:
@@ -234,7 +241,7 @@ def select_files(
     # Sort descending by score, then alphabetically for determinism on ties
     scored.sort(key=lambda x: (-x[0], x[1]))
 
-    return [path for _, path in scored[:MAX_FILES]]
+    return [path for _, path in scored[:effective_max_files]]
 
 
 # ---------------------------------------------------------------------------

{contextzip-0.3.4 → contextzip-0.3.6}/contextzip/ai/selector.py

@@ -32,10 +32,15 @@ def ai_select(
     prompt: str,
     ecosystem: str,
     api_key: str,
+    max_files: int | None = None,
 ) -> tuple[list[Path], str, str]:
     """
     Select the minimum relevant files for *prompt* from *resolved.included*.
 
+    *max_files* caps how many files either backend may return — typically a
+    project's `ai.max_files` preference (.contextzip/config.json). None
+    falls back to each backend's own built-in default cap.
+
     Returns
     -------
     (selected_paths, prompt_txt, method)
@@ -54,12 +59,14 @@ def ai_select(
             prompt=prompt,
             file_tree=file_tree,
             ecosystem=ecosystem,
+            max_files=max_files,
         )
     except GeminiRateLimitError:
         # Confirmed HTTP 429 only — fall back to keyword heuristic
         selected_rel = _heuristic.select_files(
             prompt=prompt,
             file_tree=file_tree,
+            max_files=max_files,
         )
         method = USED_HEURISTIC
     # All other GeminiErrors (bad key, network, unexpected status) propagate