gwc-pybundle 0.4.2__tar.gz → 1.1.1__tar.gz

{gwc_pybundle-0.4.2 → gwc_pybundle-1.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gwc-pybundle
-Version: 0.4.2
+Version: 1.1.1
 Summary: Deterministic Python project context bundling for humans, automation, and AI
 Author: Jessica Brown
 License: The MIT License (MIT)
@@ -31,7 +31,7 @@ License: The MIT License (MIT)
 Project-URL: Homepage, https://github.com/girls-whocode/pybundle
 Project-URL: Repository, https://github.com/girls-whocode/pybundle
 Project-URL: Issues, https://github.com/girls-whocode/pybundle/issues
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -47,9 +47,21 @@ Description-Content-Type: text/markdown
 License-File: LICENSE.md
 Dynamic: license-file
 
-# 🧳 pybundle
- 
-**pybundle** is a deterministic, automation-friendly tool for collecting Python project context into a single, shareable bundle - ideal for debugging, audits, AI assistance, CI artifacts, or handoff between engineers.
+# 🧳 pybundle [![PyPI version](https://img.shields.io/pypi/v/gwc-pybundle.svg?color=2ea44f)](https://pypi.org/project/gwc-pybundle/)
+![GitHub Release Date](https://img.shields.io/github/release-date/girls-whocode/pybundle?color=orange)
+
+[![Python versions](https://img.shields.io/pypi/pyversions/gwc-pybundle.svg?color=3776AB)](https://pypi.org/project/gwc-pybundle/)
+[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE.md)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/gwc-pybundle?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLUE&right_color=GREY&left_text=downloads)](https://pepy.tech/projects/gwc-pybundle)
+![GitHub Sponsors](https://img.shields.io/github/sponsors/girls-whocode?color=ec4899)
+
+[![CI](https://github.com/girls-whocode/pybundle/actions/workflows/publish.yml/badge.svg?color=fb923c)](https://github.com/girls-whocode/pybundle/actions)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-14b8a6.svg)](https://github.com/astral-sh/ruff)
+[![Type checked](https://img.shields.io/badge/type%20checked-mypy-0ea5e9.svg)](https://mypy-lang.org/)
+![Commit Activity](https://img.shields.io/github/commit-activity/t/girls-whocode/pybundle?color=f59e0b)
+
+
+**pybundle** is a deterministic, automation-friendly CLI that captures Python project context into a single, reproducible bundle — ideal for debugging, CI artifacts, audits, and AI-assisted workflows.
 
 It produces **machine-readable outputs first**, with optional human-readable summaries layered on top.
 
@@ -111,7 +123,8 @@ For humans, automation, and AI alike.
 * 🧾 **Structured summaries** (`SUMMARY.json`)
 * 🧭 **Respects `.gitignore`** exactly when available
 * 🛑 **Safely ignores virtualenvs and caches** (even with non-standard names)
-* 🔍 Optional tooling checks (ruff, mypy, pytest, ripgrep scans)
+* 🔍 Optional tooling checks (ruff, mypy, pytest, pylance, bandit, pip-audit, coverage)
+* 🛡️ Security scanning (bandit for code issues, pip-audit for dependency CVEs)
 * 🧪 Deterministic output (stable paths, timestamps, schemas)
 * 🔒 Secret-safe (optional redaction)
 
@@ -125,7 +138,7 @@ At minimum, a bundle contains:
 MANIFEST.json        # stable, machine-readable metadata
 SUMMARY.json         # structured summary of collected data
 src/                 # filtered project source snapshot
-logs/                # tool outputs (ruff, mypy, etc.)
+logs/                # tool outputs (ruff, mypy, pytest, pylance, bandit, pip-audit, coverage, rg scans)
 meta/                # environment + tool detection
 ```
 
@@ -157,7 +170,10 @@ Create a dedicated requirements file in the root of your project:
 ruff
 mypy
 pytest
-gwc-pybundle==0.4.2
+pytest-cov
+bandit
+pip-audit
+gwc-pybundle==1.1.1
 ```
 
 Then install:
@@ -194,7 +210,7 @@ See **Usage** for more details.
 #### From GitHub
 
 ```bash
-pip install "gwc-pybundle @ git+https://github.com/girls-whocode/pybundle.git@v0.4.2"
+pip install "gwc-pybundle @ git+https://github.com/girls-whocode/pybundle.git@v1.1.1"
 ```
 
 Pinning to a tag ensures reproducible behavior.
@@ -225,7 +241,7 @@ Available profiles include:
 
 * `analysis` - **full diagnostics** (lint, type-check, tests, scans)
 * `debug` - **analysis + additional environment validation**
-* `backup` - **minimal environment snapshot**
+* `backup` - **minimal source + environment snapshot** (no analysis tools)
 * `ai` - **AI-optimized context bundle** (lean, source-first)
 
 To list all available profiles:
@@ -239,6 +255,132 @@ Profiles are always invoked via:
 ```bash
 pybundle run <profile>
 ```
+
+---
+
+### 💾 Backup profile
+
+The `backup` profile creates a minimal, lightweight snapshot ideal for version archival or disaster recovery.
+
+Run it with:
+
+```bash
+pybundle run backup
+```
+
+#### What `backup` includes
+
+* ✅ Full source code snapshot (respects `.gitignore`)
+* ✅ Git status and diff (`meta/00_git_status.txt`, `meta/01_git_diff.txt`)
+* ✅ Python version (`meta/20_python_version.txt`)
+* ✅ Installed packages (`meta/22_pip_freeze.txt`)
+* ✅ Copy manifest (`meta/50_copy_manifest.txt`)
+* ❌ No linting, type-checking, or tests
+* ❌ No security scanning
+* ❌ No ripgrep scans
+
+The result is a **fast, small, restorable archive** with just source code and environment context.
+
+#### Restoring a backup
+
+Backups are created as either `.zip` or `.tar.gz` archives (see Archive Format below).
+
+To extract and inspect:
+
+**For .zip archives:**
+```bash
+# Look for filename with *_backup_<TIMESTAMP>.zip
+unzip <FILENAME>.zip -d restored/
+cd restored/<FILENAME>/
+```
+
+**For .tar.gz archives:**
+```bash
+# Look for filename with *_backup_<TIMESTAMP>.tar.gz
+tar -xzf <FILENAME>.tar.gz -C restored/
+cd restored/<FILENAME>/
+```
+
+Inside the extracted directory:
+
+```text
+src/                      # Your project source code
+meta/
+  00_git_status.txt       # Git working tree status at backup time
+  01_git_diff.txt         # Uncommitted changes (if any)
+  20_python_version.txt   # Python version used
+  22_pip_freeze.txt       # Exact package versions
+  50_copy_manifest.txt    # List of files included
+MANIFEST.json             # Machine-readable metadata
+SUMMARY.json              # Structured summary
+RUN_LOG.txt               # Execution log
+```
+
+The `src/` directory contains your complete project structure.
+The `meta/22_pip_freeze.txt` file can be used to recreate the exact environment:
+
+```bash
+python -m venv venv
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -r meta/22_pip_freeze.txt
+```
+
+Then copy your source code back:
+
+```bash
+cp -r src/* /path/to/your/project/
+```
+
+#### Archive format fallback
+
+pybundle uses **zip** by default for maximum portability.
+
+If the `zip` command is not available on your system, pybundle **automatically falls back to tar.gz** format without requiring configuration.
+
+This ensures backups can be created on any system, regardless of installed compression tools.
+
+To explicitly control the format:
+
+```bash
+pybundle run backup --format zip      # Force zip (requires zip command)
+pybundle run backup --format tar.gz   # Force tar.gz (requires tar command)
+pybundle run backup --format auto     # Auto-detect (default behavior)
+```
+
+Both formats preserve the same internal structure and metadata.
+
+---
+
+### 🔍 Analysis Tools
+
+The `analysis` and `debug` profiles run comprehensive quality and security checks:
+
+#### Code Quality
+* **ruff** - Fast Python linter and formatter checks
+* **mypy** - Static type checking for type hints
+* **pylance** - Syntax error detection and import analysis
+
+#### Testing & Coverage
+* **pytest** - Test execution and results
+* **coverage** - Code coverage analysis (shows tested vs untested code)
+
+#### Security
+* **bandit** - Security vulnerability scanning for Python code
+* **pip-audit** - Dependency vulnerability checking against known CVEs
+
+#### Pattern Scanning
+* **ripgrep scans** - TODO detection, print statements, bare excepts
+
+All tools gracefully skip if not installed. Install recommended tools:
+
+```bash
+pip install ruff mypy pytest pytest-cov bandit pip-audit
+```
+
+For ripgrep (system dependency):
+* macOS: `brew install ripgrep`
+* Ubuntu/Debian: `sudo apt install ripgrep`
+
 ---
 
 ### 🤖 AI profile (NEW)
@@ -311,7 +453,11 @@ Tool execution can be selectively disabled:
 ```bash
 --no-ruff
 --no-mypy
+--no-pylance
 --no-pytest
+--no-bandit
+--no-pip-audit
+--no-coverage
 --no-rg
 --no-error-refs
 --no-context
@@ -373,7 +519,109 @@ pybundle falls back to safe structural rules:
 * detects virtual environments by structure (`pyvenv.cfg`, `bin/activate`), not by name
   → works with `.venv`, `.pybundle-venv`, `env-prod-2025`, etc.
 
-No filename guessing. No surprises.
+---
+
+## 🧾 Machine-Readable Output (`--json`)
+
+All `pybundle` commands support a **machine-readable JSON output mode** via the `--json` flag.
+
+When enabled, `pybundle` emits **exactly one JSON object to stdout**, with a **stable schema** intended for:
+
+* CI pipelines
+* automation scripts
+* external tooling
+* AI orchestration
+* reproducible analysis
+
+No human text, spinners, or formatting are mixed into the output.
+
+### Example
+
+```bash
+pybundle run analysis --json
+```
+
+Output:
+
+```json
+{
+  "status": "ok",
+  "command": "run",
+  "profile": "analysis",
+  "files_included": 39,
+  "files_excluded": 0,
+  "duration_ms": 394,
+  "bundle_path": "/home/jessica/repositories/python/pybundle/artifacts/pybundle_analysis_20260103T102440Z.zip"
+}
+```
+
+The same structure applies to **all profiles**:
+
+```bash
+pybundle run ai --json
+pybundle run debug --json
+pybundle run backup --json
+```
+
+---
+
+### JSON Field Definitions
+
+| Field            | Description                                        |
+| ---------------- | -------------------------------------------------- |
+| `status`         | `"ok"` or `"fail"` based on execution result       |
+| `command`        | The command executed (`run` or `doctor`)           |
+| `profile`        | The profile used (`analysis`, `ai`, `debug`, etc.) |
+| `files_included` | Number of files copied into the bundle             |
+| `files_excluded` | Number of *evaluated* files skipped by policy      |
+| `duration_ms`    | Total execution time in milliseconds               |
+| `bundle_path`    | Absolute path to the generated archive             |
+
+---
+
+### Important Semantics: `files_excluded`
+
+`files_excluded` **does not** mean “everything in the repository that was not bundled.”
+
+Instead, it means:
+
+> Files that were **eligible under the active profile’s policy** and were *explicitly skipped* after evaluation.
+
+Files and directories that are **intentionally out of scope** — such as:
+
+* `.git/`
+* `node_modules/`
+* virtual environments
+* build artifacts
+* caches
+
+are **never considered**, and therefore are **not counted as excluded**.
+
+This design keeps metrics honest and avoids inflating counts with known-irrelevant infrastructure.
+
+A value of `files_excluded = 0` simply means:
+
+> *Everything that was evaluated was worth keeping.*
+
+This is expected and normal for clean, well-structured projects — especially in `ai` mode.
+
+---
+
+### JSON Stability Guarantee
+
+The JSON schema emitted by `--json` is considered **part of the public API**.
+
+Starting with **v1.0**, field names and meanings will remain stable.
+New fields may be added, but existing fields will not be renamed or removed.
+
+This allows `pybundle` to be safely embedded into:
+
+* CI workflows
+* automation scripts
+* AI pipelines
+* external tooling
+
+without fear of breaking changes.
 
 ---
 
@@ -446,7 +694,7 @@ pybundle follows **Semantic Versioning**.
 Pinned Git tags are recommended when used as a dependency:
 
 ```txt
-gwc-pybundle @ git+https://github.com/girls-whocode/pybundle.git@v0.4.2
+gwc-pybundle @ git+https://github.com/girls-whocode/pybundle.git@v1.1.1
 ```
 
 ---
@@ -469,7 +717,7 @@ The project name, imports, and CLI remain **`pybundle`**.
 pip install gwc-pybundle
 pybundle run analysis
 ```
- Look in the autocreated `artifacts/` folder
+Look in the autocreated `artifacts/` folder.
 
 ## 📄 License
 

{gwc_pybundle-0.4.2 → gwc_pybundle-1.1.1}/README.md

@@ -1,6 +1,18 @@
-# 🧳 pybundle
- 
-**pybundle** is a deterministic, automation-friendly tool for collecting Python project context into a single, shareable bundle - ideal for debugging, audits, AI assistance, CI artifacts, or handoff between engineers.
+# 🧳 pybundle [![PyPI version](https://img.shields.io/pypi/v/gwc-pybundle.svg?color=2ea44f)](https://pypi.org/project/gwc-pybundle/)
+![GitHub Release Date](https://img.shields.io/github/release-date/girls-whocode/pybundle?color=orange)
+
+[![Python versions](https://img.shields.io/pypi/pyversions/gwc-pybundle.svg?color=3776AB)](https://pypi.org/project/gwc-pybundle/)
+[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE.md)
+[![PyPI Downloads](https://static.pepy.tech/personalized-badge/gwc-pybundle?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLUE&right_color=GREY&left_text=downloads)](https://pepy.tech/projects/gwc-pybundle)
+![GitHub Sponsors](https://img.shields.io/github/sponsors/girls-whocode?color=ec4899)
+
+[![CI](https://github.com/girls-whocode/pybundle/actions/workflows/publish.yml/badge.svg?color=fb923c)](https://github.com/girls-whocode/pybundle/actions)
+[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-14b8a6.svg)](https://github.com/astral-sh/ruff)
+[![Type checked](https://img.shields.io/badge/type%20checked-mypy-0ea5e9.svg)](https://mypy-lang.org/)
+![Commit Activity](https://img.shields.io/github/commit-activity/t/girls-whocode/pybundle?color=f59e0b)
+
+
+**pybundle** is a deterministic, automation-friendly CLI that captures Python project context into a single, reproducible bundle — ideal for debugging, CI artifacts, audits, and AI-assisted workflows.
 
 It produces **machine-readable outputs first**, with optional human-readable summaries layered on top.
 
@@ -62,7 +74,8 @@ For humans, automation, and AI alike.
 * 🧾 **Structured summaries** (`SUMMARY.json`)
 * 🧭 **Respects `.gitignore`** exactly when available
 * 🛑 **Safely ignores virtualenvs and caches** (even with non-standard names)
-* 🔍 Optional tooling checks (ruff, mypy, pytest, ripgrep scans)
+* 🔍 Optional tooling checks (ruff, mypy, pytest, pylance, bandit, pip-audit, coverage)
+* 🛡️ Security scanning (bandit for code issues, pip-audit for dependency CVEs)
 * 🧪 Deterministic output (stable paths, timestamps, schemas)
 * 🔒 Secret-safe (optional redaction)
 
@@ -76,7 +89,7 @@ At minimum, a bundle contains:
 MANIFEST.json        # stable, machine-readable metadata
 SUMMARY.json         # structured summary of collected data
 src/                 # filtered project source snapshot
-logs/                # tool outputs (ruff, mypy, etc.)
+logs/                # tool outputs (ruff, mypy, pytest, pylance, bandit, pip-audit, coverage, rg scans)
 meta/                # environment + tool detection
 ```
 
@@ -108,7 +121,10 @@ Create a dedicated requirements file in the root of your project:
 ruff
 mypy
 pytest
-gwc-pybundle==0.4.2
+pytest-cov
+bandit
+pip-audit
+gwc-pybundle==1.1.1
 ```
 
 Then install:
@@ -145,7 +161,7 @@ See **Usage** for more details.
 #### From GitHub
 
 ```bash
-pip install "gwc-pybundle @ git+https://github.com/girls-whocode/pybundle.git@v0.4.2"
+pip install "gwc-pybundle @ git+https://github.com/girls-whocode/pybundle.git@v1.1.1"
 ```
 
 Pinning to a tag ensures reproducible behavior.
@@ -176,7 +192,7 @@ Available profiles include:
 
 * `analysis` - **full diagnostics** (lint, type-check, tests, scans)
 * `debug` - **analysis + additional environment validation**
-* `backup` - **minimal environment snapshot**
+* `backup` - **minimal source + environment snapshot** (no analysis tools)
 * `ai` - **AI-optimized context bundle** (lean, source-first)
 
 To list all available profiles:
@@ -190,6 +206,132 @@ Profiles are always invoked via:
 ```bash
 pybundle run <profile>
 ```
+
+---
+
+### 💾 Backup profile
+
+The `backup` profile creates a minimal, lightweight snapshot ideal for version archival or disaster recovery.
+
+Run it with:
+
+```bash
+pybundle run backup
+```
+
+#### What `backup` includes
+
+* ✅ Full source code snapshot (respects `.gitignore`)
+* ✅ Git status and diff (`meta/00_git_status.txt`, `meta/01_git_diff.txt`)
+* ✅ Python version (`meta/20_python_version.txt`)
+* ✅ Installed packages (`meta/22_pip_freeze.txt`)
+* ✅ Copy manifest (`meta/50_copy_manifest.txt`)
+* ❌ No linting, type-checking, or tests
+* ❌ No security scanning
+* ❌ No ripgrep scans
+
+The result is a **fast, small, restorable archive** with just source code and environment context.
+
+#### Restoring a backup
+
+Backups are created as either `.zip` or `.tar.gz` archives (see Archive Format below).
+
+To extract and inspect:
+
+**For .zip archives:**
+```bash
+# Look for filename with *_backup_<TIMESTAMP>.zip
+unzip <FILENAME>.zip -d restored/
+cd restored/<FILENAME>/
+```
+
+**For .tar.gz archives:**
+```bash
+# Look for filename with *_backup_<TIMESTAMP>.tar.gz
+tar -xzf <FILENAME>.tar.gz -C restored/
+cd restored/<FILENAME>/
+```
+
+Inside the extracted directory:
+
+```text
+src/                      # Your project source code
+meta/
+  00_git_status.txt       # Git working tree status at backup time
+  01_git_diff.txt         # Uncommitted changes (if any)
+  20_python_version.txt   # Python version used
+  22_pip_freeze.txt       # Exact package versions
+  50_copy_manifest.txt    # List of files included
+MANIFEST.json             # Machine-readable metadata
+SUMMARY.json              # Structured summary
+RUN_LOG.txt               # Execution log
+```
+
+The `src/` directory contains your complete project structure.
+The `meta/22_pip_freeze.txt` file can be used to recreate the exact environment:
+
+```bash
+python -m venv venv
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+pip install -r meta/22_pip_freeze.txt
+```
+
+Then copy your source code back:
+
+```bash
+cp -r src/* /path/to/your/project/
+```
+
+#### Archive format fallback
+
+pybundle uses **zip** by default for maximum portability.
+
+If the `zip` command is not available on your system, pybundle **automatically falls back to tar.gz** format without requiring configuration.
+
+This ensures backups can be created on any system, regardless of installed compression tools.
+
+To explicitly control the format:
+
+```bash
+pybundle run backup --format zip      # Force zip (requires zip command)
+pybundle run backup --format tar.gz   # Force tar.gz (requires tar command)
+pybundle run backup --format auto     # Auto-detect (default behavior)
+```
+
+Both formats preserve the same internal structure and metadata.
+
+---
+
+### 🔍 Analysis Tools
+
+The `analysis` and `debug` profiles run comprehensive quality and security checks:
+
+#### Code Quality
+* **ruff** - Fast Python linter and formatter checks
+* **mypy** - Static type checking for type hints
+* **pylance** - Syntax error detection and import analysis
+
+#### Testing & Coverage
+* **pytest** - Test execution and results
+* **coverage** - Code coverage analysis (shows tested vs untested code)
+
+#### Security
+* **bandit** - Security vulnerability scanning for Python code
+* **pip-audit** - Dependency vulnerability checking against known CVEs
+
+#### Pattern Scanning
+* **ripgrep scans** - TODO detection, print statements, bare excepts
+
+All tools gracefully skip if not installed. Install recommended tools:
+
+```bash
+pip install ruff mypy pytest pytest-cov bandit pip-audit
+```
+
+For ripgrep (system dependency):
+* macOS: `brew install ripgrep`
+* Ubuntu/Debian: `sudo apt install ripgrep`
+
 ---
 
 ### 🤖 AI profile (NEW)
@@ -262,7 +404,11 @@ Tool execution can be selectively disabled:
 ```bash
 --no-ruff
 --no-mypy
+--no-pylance
 --no-pytest
+--no-bandit
+--no-pip-audit
+--no-coverage
 --no-rg
 --no-error-refs
 --no-context
@@ -324,7 +470,109 @@ pybundle falls back to safe structural rules:
 * detects virtual environments by structure (`pyvenv.cfg`, `bin/activate`), not by name
   → works with `.venv`, `.pybundle-venv`, `env-prod-2025`, etc.
 
-No filename guessing. No surprises.
+---
+
+## 🧾 Machine-Readable Output (`--json`)
+
+All `pybundle` commands support a **machine-readable JSON output mode** via the `--json` flag.
+
+When enabled, `pybundle` emits **exactly one JSON object to stdout**, with a **stable schema** intended for:
+
+* CI pipelines
+* automation scripts
+* external tooling
+* AI orchestration
+* reproducible analysis
+
+No human text, spinners, or formatting are mixed into the output.
+
+### Example
+
+```bash
+pybundle run analysis --json
+```
+
+Output:
+
+```json
+{
+  "status": "ok",
+  "command": "run",
+  "profile": "analysis",
+  "files_included": 39,
+  "files_excluded": 0,
+  "duration_ms": 394,
+  "bundle_path": "/home/jessica/repositories/python/pybundle/artifacts/pybundle_analysis_20260103T102440Z.zip"
+}
+```
+
+The same structure applies to **all profiles**:
+
+```bash
+pybundle run ai --json
+pybundle run debug --json
+pybundle run backup --json
+```
+
+---
+
+### JSON Field Definitions
+
+| Field            | Description                                        |
+| ---------------- | -------------------------------------------------- |
+| `status`         | `"ok"` or `"fail"` based on execution result       |
+| `command`        | The command executed (`run` or `doctor`)           |
+| `profile`        | The profile used (`analysis`, `ai`, `debug`, etc.) |
+| `files_included` | Number of files copied into the bundle             |
+| `files_excluded` | Number of *evaluated* files skipped by policy      |
+| `duration_ms`    | Total execution time in milliseconds               |
+| `bundle_path`    | Absolute path to the generated archive             |
+
+---
+
+### Important Semantics: `files_excluded`
+
+`files_excluded` **does not** mean “everything in the repository that was not bundled.”
+
+Instead, it means:
+
+> Files that were **eligible under the active profile’s policy** and were *explicitly skipped* after evaluation.
+
+Files and directories that are **intentionally out of scope** — such as:
+
+* `.git/`
+* `node_modules/`
+* virtual environments
+* build artifacts
+* caches
+
+are **never considered**, and therefore are **not counted as excluded**.
+
+This design keeps metrics honest and avoids inflating counts with known-irrelevant infrastructure.
+
+A value of `files_excluded = 0` simply means:
+
+> *Everything that was evaluated was worth keeping.*
+
+This is expected and normal for clean, well-structured projects — especially in `ai` mode.
+
+---
+
+### JSON Stability Guarantee
+
+The JSON schema emitted by `--json` is considered **part of the public API**.
+
+Starting with **v1.0**, field names and meanings will remain stable.
+New fields may be added, but existing fields will not be renamed or removed.
+
+This allows `pybundle` to be safely embedded into:
+
+* CI workflows
+* automation scripts
+* AI pipelines
+* external tooling
+
+without fear of breaking changes.
 
 ---
 
@@ -397,7 +645,7 @@ pybundle follows **Semantic Versioning**.
 Pinned Git tags are recommended when used as a dependency:
 
 ```txt
-gwc-pybundle @ git+https://github.com/girls-whocode/pybundle.git@v0.4.2
+gwc-pybundle @ git+https://github.com/girls-whocode/pybundle.git@v1.1.1
 ```
 
 ---
@@ -420,7 +668,7 @@ The project name, imports, and CLI remain **`pybundle`**.
 pip install gwc-pybundle
 pybundle run analysis
 ```
- Look in the autocreated `artifacts/` folder
+Look in the autocreated `artifacts/` folder.
 
 ## 📄 License