codebase-brief 0.1.0__tar.gz → 0.1.2__tar.gz

codebase_brief-0.1.2/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+## 0.1.2
+
+- Add `brief --demo`, which generates a real example brief from temporary sample files without reading or modifying the user's project.
+- Clarify how to try the demo and install the CLI when pipx is not already available.
+- Show the menu's actual `0` exit key correctly in the README.
+
+## 0.1.1
+
+- Clarify the product's best-fit use case as browser-based coding chats that cannot inspect a local working tree.
+- Add a structured GitHub tester-feedback form for install results, file-selection changes, and task outcomes.
+- Add a clear instruction for the receiving assistant to answer the task using the brief as context.
+- Prioritize task-relevant source excerpts ahead of stack details and Git history when the requested budget is small.
+- Let users add a safe repository file by path and print a copyable summary of reviewed file selections.
+- Print review feedback after the generated brief, and prioritize direct local importers of files changed since `--base`.
+- Resolve literal Python dynamic imports and simple JS/TS path aliases when tracing imports.
+
+## 0.1.0
+
+- Generate bounded, local Markdown context briefs from project documentation, manifests, Git history, and selected source files.
+- Add an interactive terminal menu with ranked file selection, output choices, and overwrite confirmation.
+- Explain first-run usage in the menu and CLI help; show why each source file was selected.
+- Follow one level of local Python and JavaScript/TypeScript imports; allow approximate token budgets and clipboard handoff to any coding assistant.
+- Format generated briefs with plain-language section titles, readable documentation excerpts, and code fences only for source/configuration where useful.
+- Exclude common credential files and Git-ignored untracked files, reject credential-named or external symlinks, redact common secret formats, and keep source excerpts within fixed limits.
+- Preserve normal typed password parameters and conditions in source excerpts while redacting quoted credential assignments.
+- Package the CLI as `codebase-brief`, retaining `context-inject` as a compatibility command.
+

{codebase_brief-0.1.0 → codebase_brief-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebase-brief
-Version: 0.1.0
+Version: 0.1.2
 Summary: Local-first CLI that builds task-focused context briefs from code repositories
 Author: Mohamed Maggy
 License-Expression: MIT
@@ -25,13 +25,19 @@ Dynamic: license-file
 
 # Codebase Brief
 
+**Project site:** [codebase-brief](https://mohamed1111111m.github.io/codebase-brief/)
+
 [![Tests](https://github.com/mohamed1111111m/codebase-brief/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/mohamed1111111m/codebase-brief/actions/workflows/test.yml)
+[![Install from PyPI](https://img.shields.io/badge/Install%20from-PyPI-3775A9?logo=pypi&logoColor=white)](https://pypi.org/project/codebase-brief/)
+[![PyPI version](https://img.shields.io/pypi/v/codebase-brief.svg)](https://pypi.org/project/codebase-brief/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
 [![MIT License](https://img.shields.io/badge/license-MIT-8A63D2.svg)](LICENSE)
 
-**Give a coding assistant a clear map of a repository before it starts a task.** Codebase Brief reads a local project and creates a compact Markdown brief with relevant files, recent Git changes, and source paths you can check.
+**Browser-based coding chats cannot see your local repo.** Codebase Brief turns one coding task into a short, reviewable file shortlist—with excerpts, reasons, and source paths—so you can give ChatGPT, Claude, or another chat the project context it cannot inspect itself.
+
+It works locally, without an AI service or account. Review the brief, save it, or paste it into ChatGPT, Claude, or another assistant that cannot inspect your local working tree.
 
-It works locally, without an AI service or account. You choose what to do with the brief: review it, save it, or paste it into Claude Code, Cursor, OpenCode, Codex, or another coding assistant.
+**Best fit:** a browser chat that cannot inspect your local files, or a task where you want to choose exactly what context to share. If your coding agent already reads and indexes the working tree, its built-in repo tools may be enough.
 
 ## See it in action
 
@@ -43,25 +49,29 @@ The first image is a terminal-style rendering of the app's actual numbered menu.
 
 [Watch the 12-second product walkthrough](https://raw.githubusercontent.com/mohamed1111111m/codebase-brief/main/docs/images/product-hunt-demo.mp4).
 
-## Get started
+## Install the latest build
 
-You need Python 3.10 or newer. Git is optional, but it enables recent-history and base-diff details.
+You need Python 3.10 or newer. Git is optional, but required for recent-history and base-diff details.
 
-Once the first PyPI release is available, install it in a virtual environment and launch the menu:
+The current PyPI release is `0.1.2` and includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
 
 ```powershell
-python -m venv .venv
-.venv\Scripts\Activate.ps1
-python -m pip install --upgrade codebase-brief
-codebase-brief
+pipx install codebase-brief
+brief "C:\work\my-app" --task "Trace the login flow" --copy
 ```
 
-Until then, install the current version directly from GitHub:
+The brief is copied to your clipboard for pasting into your assistant. Replace the example path and task with yours. To use the numbered menu, run `brief` with no arguments.
+
+Want to see a real example before choosing your project? Run `brief --demo`. It uses a tiny temporary example project and does not read or change your files.
+
+If you do not have `pipx` installed, skip the command above and use the virtual-environment steps below instead; they work with the project's minimum Python version. To install `pipx` first, follow its [official installation guide](https://pipx.pypa.io/latest/how-to/install-pipx.html). The current pipx installer requires Python 3.11 or newer, while Codebase Brief itself supports Python 3.10 and newer.
+
+Or use a virtual environment:
 
 ```powershell
 python -m venv .venv
 .venv\Scripts\Activate.ps1
-python -m pip install git+https://github.com/mohamed1111111m/codebase-brief.git
+python -m pip install --upgrade codebase-brief
 codebase-brief
 ```
 
@@ -73,12 +83,14 @@ If the `brief` command is not available, use `python -m context_inject` while th
 
 When the menu opens, it uses the folder you launched it from as the starting project. Type a number and press Enter:
 
-1. **Build a context brief** — describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
-2. **Choose a different project** — point the tool at another local repository or source folder.
-3. **Help and examples** — see the workflow and an example command.
-0. **Exit** — close the menu.
+- **1 — Build a context brief:** Describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
+- **2 — Choose a different project:** Point the tool at another local repository or source folder.
+- **3 — Help and examples:** See the workflow and an example command.
+- **0 — Exit:** Close the menu.
+
+In plain terms, Codebase Brief makes a small guide to a project so an AI coding assistant can get oriented before helping with a task. It does not write or fix code. It reads project information locally and prepares a guide for you to review and share.
 
-Before generating the brief, the tool shows suggested files and why they were selected. Press Enter to keep the checked files, type file numbers to toggle selections, or type `none` for an overview without source excerpts. Then choose whether to show the result, save it, choose another output path, or copy it to your clipboard. The menu's save-here choice writes `context.md` in the folder where you launched the menu; if that is the target repository, the file will be created there. Choose the show or copy option to avoid writing a file into that folder.
+Before generating the brief, the tool shows suggested files and why they were selected. Press Enter to keep the checked files, type file numbers to toggle selections, or use `add path/to/file.py` to include another safe text file from the repository. Type `none` for an overview without source excerpts. After the brief is shown, saved, or copied, Codebase Brief prints a copyable summary of files kept, removed, added from suggestions, and manually added. To help improve file selection, paste that summary into the [tester feedback form](https://github.com/mohamed1111111m/codebase-brief/issues/new?template=tester-feedback.yml) along with your task and whether the brief helped. Do not include private source code or secrets. The menu's save-here choice writes `context.md` in the folder where you launched the menu; if that is the target repository, the file will be created there. Choose the show or copy option to avoid writing a file into that folder.
 
 For your first try, choose a project you know and a task you understand. Check whether the suggested files are the ones you would have shown a coding assistant yourself.
 
@@ -98,7 +110,7 @@ To copy the result directly to your clipboard, use `--copy` instead of `--output
 codebase-brief "C:\work\my-app" --task "Find the login flow" --copy
 ```
 
-The generated Markdown is a starting map for your assistant, not a complete copy or analysis of the repository. Review it, then paste it into the coding assistant where you want to work.
+The generated Markdown is a starting map for your assistant, not a complete copy or analysis of the repository. Review it, then paste the whole brief into the coding assistant where you want to work. It tells the assistant to answer the **Task** at the top using the brief as context. Codebase Brief prepares the handoff; the AI chat does the analysis or coding.
 
 ## What it includes
 
@@ -108,7 +120,7 @@ The generated Markdown is a starting map for your assistant, not a complete copy
 - Small excerpts from selected files, within the requested size budget.
 - Source paths throughout the brief so you can open and verify the material.
 
-The file picker uses task words, recent changes, selected Git diffs, common entry points, and direct local Python or JavaScript/TypeScript imports. These are simple heuristics, not semantic code analysis. It traces at most one direct import hop for supported languages, so it can miss relevant files.
+The file picker uses task words, recent changes, selected Git diffs, common entry points, and direct local Python or JavaScript/TypeScript imports. With `--base`, it also scans supported source files for direct imports of changed files. It understands literal dynamic imports, Python `importlib` calls with literal module names, and simple `paths` aliases in `tsconfig.json` or `jsconfig.json`. This is still static analysis: imports assembled from runtime values, complex config inheritance, generated modules, and unsupported languages may be missed.
 
 ## Privacy and limitations
 
@@ -134,5 +146,5 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution notes, [CHANGELOG.md](CH
 
 ## Help shape Codebase Brief
 
-This is an early open-source project. If you try it, feedback about which suggested files were useful or missing is especially helpful. Use [GitHub Issues](https://github.com/mohamed1111111m/codebase-brief/issues) for reproducible bugs and concrete feature requests. The [launch kit](docs/launch-kit.md) has a short demo plan, the [Product Hunt draft](docs/product-hunt-launch.md) contains prepared listing copy, and PyPI setup is in [PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md).
+This is an early open-source project. If you try it, the most useful feedback is which suggested files you kept, removed, or added—and whether the resulting brief gave your assistant enough context. Use the [tester feedback form](https://github.com/mohamed1111111m/codebase-brief/issues/new?template=tester-feedback.yml); use [GitHub Issues](https://github.com/mohamed1111111m/codebase-brief/issues) for reproducible bugs and concrete feature requests. The [launch kit](docs/launch-kit.md) has a short demo plan, the [Product Hunt draft](docs/product-hunt-launch.md) contains prepared listing copy, and PyPI setup is in [PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md).
 

codebase_brief-0.1.2/README.md

@@ -0,0 +1,125 @@
+# Codebase Brief
+
+**Project site:** [codebase-brief](https://mohamed1111111m.github.io/codebase-brief/)
+
+[![Tests](https://github.com/mohamed1111111m/codebase-brief/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/mohamed1111111m/codebase-brief/actions/workflows/test.yml)
+[![Install from PyPI](https://img.shields.io/badge/Install%20from-PyPI-3775A9?logo=pypi&logoColor=white)](https://pypi.org/project/codebase-brief/)
+[![PyPI version](https://img.shields.io/pypi/v/codebase-brief.svg)](https://pypi.org/project/codebase-brief/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
+[![MIT License](https://img.shields.io/badge/license-MIT-8A63D2.svg)](LICENSE)
+
+**Browser-based coding chats cannot see your local repo.** Codebase Brief turns one coding task into a short, reviewable file shortlist—with excerpts, reasons, and source paths—so you can give ChatGPT, Claude, or another chat the project context it cannot inspect itself.
+
+It works locally, without an AI service or account. Review the brief, save it, or paste it into ChatGPT, Claude, or another assistant that cannot inspect your local working tree.
+
+**Best fit:** a browser chat that cannot inspect your local files, or a task where you want to choose exactly what context to share. If your coding agent already reads and indexes the working tree, its built-in repo tools may be enough.
+
+## See it in action
+
+The first image is a terminal-style rendering of the app's actual numbered menu. The sample brief was generated by running Codebase Brief on a small example repository with a Git base ref.
+
+![Codebase Brief's colorful guided menu](https://raw.githubusercontent.com/mohamed1111111m/codebase-brief/main/docs/images/guided-menu.png)
+
+![Example context brief showing task, repository details, recent changes, and cited files](https://raw.githubusercontent.com/mohamed1111111m/codebase-brief/main/docs/images/sample-context-brief.png)
+
+[Watch the 12-second product walkthrough](https://raw.githubusercontent.com/mohamed1111111m/codebase-brief/main/docs/images/product-hunt-demo.mp4).
+
+## Install the latest build
+
+You need Python 3.10 or newer. Git is optional, but required for recent-history and base-diff details.
+
+The current PyPI release is `0.1.2` and includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
+
+```powershell
+pipx install codebase-brief
+brief "C:\work\my-app" --task "Trace the login flow" --copy
+```
+
+The brief is copied to your clipboard for pasting into your assistant. Replace the example path and task with yours. To use the numbered menu, run `brief` with no arguments.
+
+Want to see a real example before choosing your project? Run `brief --demo`. It uses a tiny temporary example project and does not read or change your files.
+
+If you do not have `pipx` installed, skip the command above and use the virtual-environment steps below instead; they work with the project's minimum Python version. To install `pipx` first, follow its [official installation guide](https://pipx.pypa.io/latest/how-to/install-pipx.html). The current pipx installer requires Python 3.11 or newer, while Codebase Brief itself supports Python 3.10 and newer.
+
+Or use a virtual environment:
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install --upgrade codebase-brief
+codebase-brief
+```
+
+On macOS or Linux, activate the environment with `source .venv/bin/activate` after creating it with `python3 -m venv .venv`.
+
+If the `brief` command is not available, use `python -m context_inject` while that same virtual environment is active.
+
+## Use the menu
+
+When the menu opens, it uses the folder you launched it from as the starting project. Type a number and press Enter:
+
+- **1 — Build a context brief:** Describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
+- **2 — Choose a different project:** Point the tool at another local repository or source folder.
+- **3 — Help and examples:** See the workflow and an example command.
+- **0 — Exit:** Close the menu.
+
+In plain terms, Codebase Brief makes a small guide to a project so an AI coding assistant can get oriented before helping with a task. It does not write or fix code. It reads project information locally and prepares a guide for you to review and share.
+
+Before generating the brief, the tool shows suggested files and why they were selected. Press Enter to keep the checked files, type file numbers to toggle selections, or use `add path/to/file.py` to include another safe text file from the repository. Type `none` for an overview without source excerpts. After the brief is shown, saved, or copied, Codebase Brief prints a copyable summary of files kept, removed, added from suggestions, and manually added. To help improve file selection, paste that summary into the [tester feedback form](https://github.com/mohamed1111111m/codebase-brief/issues/new?template=tester-feedback.yml) along with your task and whether the brief helped. Do not include private source code or secrets. The menu's save-here choice writes `context.md` in the folder where you launched the menu; if that is the target repository, the file will be created there. Choose the show or copy option to avoid writing a file into that folder.
+
+For your first try, choose a project you know and a task you understand. Check whether the suggested files are the ones you would have shown a coding assistant yourself.
+
+## Run it with a command
+
+You can skip the menu and generate a brief directly:
+
+```powershell
+codebase-brief "C:\work\my-app" --task "Add authentication middleware" --base main --budget 2400 --output context.md
+```
+
+Replace the example folder and task with your own. `--base main` prioritizes files changed between `main` and the current `HEAD`; omit it if you do not want a Git diff. `--output context.md` saves the result to that path. Without `--output`, the brief is printed in the terminal.
+
+To copy the result directly to your clipboard, use `--copy` instead of `--output`:
+
+```powershell
+codebase-brief "C:\work\my-app" --task "Find the login flow" --copy
+```
+
+The generated Markdown is a starting map for your assistant, not a complete copy or analysis of the repository. Review it, then paste the whole brief into the coding assistant where you want to work. It tells the assistant to answer the **Task** at the top using the brief as context. Codebase Brief prepares the handoff; the AI chat does the analysis or coding.
+
+## What it includes
+
+- Project documentation and common stack manifests, such as `package.json` and `pyproject.toml`.
+- Recent Git commit subjects and changed paths when Git is available.
+- A short list of task-related files with a note explaining each suggestion.
+- Small excerpts from selected files, within the requested size budget.
+- Source paths throughout the brief so you can open and verify the material.
+
+The file picker uses task words, recent changes, selected Git diffs, common entry points, and direct local Python or JavaScript/TypeScript imports. With `--base`, it also scans supported source files for direct imports of changed files. It understands literal dynamic imports, Python `importlib` calls with literal module names, and simple `paths` aliases in `tsconfig.json` or `jsconfig.json`. This is still static analysis: imports assembled from runtime values, complex config inheritance, generated modules, and unsupported languages may be missed.
+
+## Privacy and limitations
+
+- Repository reading and brief generation happen on your computer. The application has no AI calls, telemetry, or hosted service.
+- The tool does not write to the target repository just to read it or generate a brief. It writes a file only when you choose a save option; menu option 2 saves `context.md` in the current working folder, which may be the target repository.
+- Common credential files, ignored files, generated files, and private-key files are excluded. Some recognizable secret formats and assignments are redacted.
+- Filtering is best-effort, not a security guarantee or full secret scan. Review the brief before sharing it, especially when working with private code.
+- The size budget is approximate: it estimates tokens from character count and is not tied to a particular model tokenizer.
+- Without Git, the tool still reads supported documentation and manifests, but cannot include Git history or diff details.
+
+## Development
+
+Clone the repository, create a virtual environment, and install the project in editable mode:
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install --editable .
+python -m unittest discover -s tests -v
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution notes, [CHANGELOG.md](CHANGELOG.md) for project changes, and [LICENSE](LICENSE) for the MIT terms.
+
+## Help shape Codebase Brief
+
+This is an early open-source project. If you try it, the most useful feedback is which suggested files you kept, removed, or added—and whether the resulting brief gave your assistant enough context. Use the [tester feedback form](https://github.com/mohamed1111111m/codebase-brief/issues/new?template=tester-feedback.yml); use [GitHub Issues](https://github.com/mohamed1111111m/codebase-brief/issues) for reproducible bugs and concrete feature requests. The [launch kit](docs/launch-kit.md) has a short demo plan, the [Product Hunt draft](docs/product-hunt-launch.md) contains prepared listing copy, and PyPI setup is in [PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md).
+

{codebase_brief-0.1.0 → codebase_brief-0.1.2}/codebase_brief.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codebase-brief
-Version: 0.1.0
+Version: 0.1.2
 Summary: Local-first CLI that builds task-focused context briefs from code repositories
 Author: Mohamed Maggy
 License-Expression: MIT
@@ -25,13 +25,19 @@ Dynamic: license-file
 
 # Codebase Brief
 
+**Project site:** [codebase-brief](https://mohamed1111111m.github.io/codebase-brief/)
+
 [![Tests](https://github.com/mohamed1111111m/codebase-brief/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/mohamed1111111m/codebase-brief/actions/workflows/test.yml)
+[![Install from PyPI](https://img.shields.io/badge/Install%20from-PyPI-3775A9?logo=pypi&logoColor=white)](https://pypi.org/project/codebase-brief/)
+[![PyPI version](https://img.shields.io/pypi/v/codebase-brief.svg)](https://pypi.org/project/codebase-brief/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
 [![MIT License](https://img.shields.io/badge/license-MIT-8A63D2.svg)](LICENSE)
 
-**Give a coding assistant a clear map of a repository before it starts a task.** Codebase Brief reads a local project and creates a compact Markdown brief with relevant files, recent Git changes, and source paths you can check.
+**Browser-based coding chats cannot see your local repo.** Codebase Brief turns one coding task into a short, reviewable file shortlist—with excerpts, reasons, and source paths—so you can give ChatGPT, Claude, or another chat the project context it cannot inspect itself.
+
+It works locally, without an AI service or account. Review the brief, save it, or paste it into ChatGPT, Claude, or another assistant that cannot inspect your local working tree.
 
-It works locally, without an AI service or account. You choose what to do with the brief: review it, save it, or paste it into Claude Code, Cursor, OpenCode, Codex, or another coding assistant.
+**Best fit:** a browser chat that cannot inspect your local files, or a task where you want to choose exactly what context to share. If your coding agent already reads and indexes the working tree, its built-in repo tools may be enough.
 
 ## See it in action
 
@@ -43,25 +49,29 @@ The first image is a terminal-style rendering of the app's actual numbered menu.
 
 [Watch the 12-second product walkthrough](https://raw.githubusercontent.com/mohamed1111111m/codebase-brief/main/docs/images/product-hunt-demo.mp4).
 
-## Get started
+## Install the latest build
 
-You need Python 3.10 or newer. Git is optional, but it enables recent-history and base-diff details.
+You need Python 3.10 or newer. Git is optional, but required for recent-history and base-diff details.
 
-Once the first PyPI release is available, install it in a virtual environment and launch the menu:
+The current PyPI release is `0.1.2` and includes the review-feedback summary, importer-aware `--base` selection, and a sample demo. Install it with `pipx`:
 
 ```powershell
-python -m venv .venv
-.venv\Scripts\Activate.ps1
-python -m pip install --upgrade codebase-brief
-codebase-brief
+pipx install codebase-brief
+brief "C:\work\my-app" --task "Trace the login flow" --copy
 ```
 
-Until then, install the current version directly from GitHub:
+The brief is copied to your clipboard for pasting into your assistant. Replace the example path and task with yours. To use the numbered menu, run `brief` with no arguments.
+
+Want to see a real example before choosing your project? Run `brief --demo`. It uses a tiny temporary example project and does not read or change your files.
+
+If you do not have `pipx` installed, skip the command above and use the virtual-environment steps below instead; they work with the project's minimum Python version. To install `pipx` first, follow its [official installation guide](https://pipx.pypa.io/latest/how-to/install-pipx.html). The current pipx installer requires Python 3.11 or newer, while Codebase Brief itself supports Python 3.10 and newer.
+
+Or use a virtual environment:
 
 ```powershell
 python -m venv .venv
 .venv\Scripts\Activate.ps1
-python -m pip install git+https://github.com/mohamed1111111m/codebase-brief.git
+python -m pip install --upgrade codebase-brief
 codebase-brief
 ```
 
@@ -73,12 +83,14 @@ If the `brief` command is not available, use `python -m context_inject` while th
 
 When the menu opens, it uses the folder you launched it from as the starting project. Type a number and press Enter:
 
-1. **Build a context brief** — describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
-2. **Choose a different project** — point the tool at another local repository or source folder.
-3. **Help and examples** — see the workflow and an example command.
-0. **Exit** — close the menu.
+- **1 — Build a context brief:** Describe the coding task, optionally enter a Git base ref, then accept or change the approximate size limit.
+- **2 — Choose a different project:** Point the tool at another local repository or source folder.
+- **3 — Help and examples:** See the workflow and an example command.
+- **0 — Exit:** Close the menu.
+
+In plain terms, Codebase Brief makes a small guide to a project so an AI coding assistant can get oriented before helping with a task. It does not write or fix code. It reads project information locally and prepares a guide for you to review and share.
 
-Before generating the brief, the tool shows suggested files and why they were selected. Press Enter to keep the checked files, type file numbers to toggle selections, or type `none` for an overview without source excerpts. Then choose whether to show the result, save it, choose another output path, or copy it to your clipboard. The menu's save-here choice writes `context.md` in the folder where you launched the menu; if that is the target repository, the file will be created there. Choose the show or copy option to avoid writing a file into that folder.
+Before generating the brief, the tool shows suggested files and why they were selected. Press Enter to keep the checked files, type file numbers to toggle selections, or use `add path/to/file.py` to include another safe text file from the repository. Type `none` for an overview without source excerpts. After the brief is shown, saved, or copied, Codebase Brief prints a copyable summary of files kept, removed, added from suggestions, and manually added. To help improve file selection, paste that summary into the [tester feedback form](https://github.com/mohamed1111111m/codebase-brief/issues/new?template=tester-feedback.yml) along with your task and whether the brief helped. Do not include private source code or secrets. The menu's save-here choice writes `context.md` in the folder where you launched the menu; if that is the target repository, the file will be created there. Choose the show or copy option to avoid writing a file into that folder.
 
 For your first try, choose a project you know and a task you understand. Check whether the suggested files are the ones you would have shown a coding assistant yourself.
 
@@ -98,7 +110,7 @@ To copy the result directly to your clipboard, use `--copy` instead of `--output
 codebase-brief "C:\work\my-app" --task "Find the login flow" --copy
 ```
 
-The generated Markdown is a starting map for your assistant, not a complete copy or analysis of the repository. Review it, then paste it into the coding assistant where you want to work.
+The generated Markdown is a starting map for your assistant, not a complete copy or analysis of the repository. Review it, then paste the whole brief into the coding assistant where you want to work. It tells the assistant to answer the **Task** at the top using the brief as context. Codebase Brief prepares the handoff; the AI chat does the analysis or coding.
 
 ## What it includes
 
@@ -108,7 +120,7 @@ The generated Markdown is a starting map for your assistant, not a complete copy
 - Small excerpts from selected files, within the requested size budget.
 - Source paths throughout the brief so you can open and verify the material.
 
-The file picker uses task words, recent changes, selected Git diffs, common entry points, and direct local Python or JavaScript/TypeScript imports. These are simple heuristics, not semantic code analysis. It traces at most one direct import hop for supported languages, so it can miss relevant files.
+The file picker uses task words, recent changes, selected Git diffs, common entry points, and direct local Python or JavaScript/TypeScript imports. With `--base`, it also scans supported source files for direct imports of changed files. It understands literal dynamic imports, Python `importlib` calls with literal module names, and simple `paths` aliases in `tsconfig.json` or `jsconfig.json`. This is still static analysis: imports assembled from runtime values, complex config inheritance, generated modules, and unsupported languages may be missed.
 
 ## Privacy and limitations
 
@@ -134,5 +146,5 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution notes, [CHANGELOG.md](CH
 
 ## Help shape Codebase Brief
 
-This is an early open-source project. If you try it, feedback about which suggested files were useful or missing is especially helpful. Use [GitHub Issues](https://github.com/mohamed1111111m/codebase-brief/issues) for reproducible bugs and concrete feature requests. The [launch kit](docs/launch-kit.md) has a short demo plan, the [Product Hunt draft](docs/product-hunt-launch.md) contains prepared listing copy, and PyPI setup is in [PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md).
+This is an early open-source project. If you try it, the most useful feedback is which suggested files you kept, removed, or added—and whether the resulting brief gave your assistant enough context. Use the [tester feedback form](https://github.com/mohamed1111111m/codebase-brief/issues/new?template=tester-feedback.yml); use [GitHub Issues](https://github.com/mohamed1111111m/codebase-brief/issues) for reproducible bugs and concrete feature requests. The [launch kit](docs/launch-kit.md) has a short demo plan, the [Product Hunt draft](docs/product-hunt-launch.md) contains prepared listing copy, and PyPI setup is in [PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md).