gitgalaxy 2.2.0__tar.gz → 2.2.2__tar.gz

gitgalaxy-2.2.2/.flake8

@@ -0,0 +1,3 @@
+[flake8]
+max-line-length = 120
+extend-ignore = E203, W503, E501, E741, W291, W293, F401, F841

gitgalaxy-2.2.2/.github/workflows/gitgalaxy.yml

@@ -0,0 +1,72 @@
+name: GitGalaxy Zero-Trust Pipeline
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  vault-sentinel:
+    name: Vault Sentinel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: squid-protocol/gitgalaxy@main
+        with:
+          tool: 'vault-sentinel'
+          target: '.'
+
+  xray-inspector:
+    name: X-Ray Inspector
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: squid-protocol/gitgalaxy@main
+        with:
+          tool: 'xray-inspector'
+          target: '.'
+
+  supply-chain-firewall:
+    name: Supply Chain Firewall
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: squid-protocol/gitgalaxy@main
+        with:
+          tool: 'supply-chain-firewall'
+          target: '.'
+
+  architectural-report:
+    name: LLM Structural Brief
+    needs: [vault-sentinel, xray-inspector, supply-chain-firewall]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # Critical: Grants the Action permission to push to main
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate GalaxyScope LLM Brief
+        uses: squid-protocol/gitgalaxy@main
+        with:
+          tool: 'galaxyscope'
+          target: '.'
+          args: '--llm-only'
+          full_precision: 'true'
+
+      - name: Commit and Push LLM Brief to Main
+        run: |
+          # Move the report to the docs folder for clean organization
+          mkdir -p docs
+          mv *_galaxy_llm.md docs/gitgalaxy_architecture_brief.md || true
+          
+          # Configure the GitHub Actions bot identity
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          
+          # Stage the file
+          git add docs/gitgalaxy_architecture_brief.md
+          
+          # Only commit and push if there are actual changes to prevent pipeline failures
+          git diff --quiet && git diff --staged --quiet || (git commit -m "docs: auto-update LLM architectural brief" && git push)

gitgalaxy-2.2.2/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# 🤝 Contributing to GitGalaxy
+
+First off, thank you for considering contributing to GitGalaxy! The blAST engine is a highly calibrated, deterministic mathematical instrument. Calibrating it across the vast ecosystem of open-source software requires a dedicated community of systems engineers.
+
+Whether you are reporting a taxonomic discrepancy, refining the parsing engine, or expanding the documentation, your input helps map the architectural physics of software more accurately.
+
+---
+
+## ⚙️ The blAST Philosophy (Physics over ASTs)
+
+Before diving in, please remember that GitGalaxy treats code as a physical structure governed by thermodynamic laws. The blAST engine evaluates structural logic, algorithmic complexity, and calculated **risk exposures**—not just rigid syntax. 
+
+Sometimes, what appears to be a traditional parsing error might actually be the blAST engine intentionally flagging a structural anomaly or a dense risk exposure. Please keep this in mind when reporting issues or proposing changes to the extraction heuristics.
+
+---
+
+## 🌐 Expanding the blAST Engine (Adding Languages)
+
+GitGalaxy uses an AST-free, mathematical heuristics engine to build a comparative lexical taxonomical map across all programming languages. We do not write traditional parsers; we map thermodynamic language physics using bounded regular expressions. 
+
+If you want to add native support for a new language (e.g., Lua, Haskell, or a proprietary DSL), do not start writing regex from scratch. We use a strict LLM-driven calibration protocol to guarantee ReDoS immunity. 
+
+**Please read the strict engine calibration guide here:** **[Architecting a New Language (Extending the blAST Engine)](gitgalaxy/standards/how_to_add_a_language.md)**
+
+---
+
+## 🔬 The Differential Scan (Our PR Protocol)
+
+We do not merge structural backend changes based solely on subjective code review. GitGalaxy operates at planetary scale, and every change to the parsing logic has cascading effects.
+
+When you submit a Pull Request that alters the blAST engine, your candidate changes will be subjected to a **Full Differential Scan**. 
+
+* **The Control + Variable Test:** We run your branch against our calibrated baseline of ~80 massive open-source repositories, **plus** the specific repository your PR is designed to address.
+* **Before and After:** We perform a strict mathematical comparison of the engine's output before and after your rule update across this entire dataset. This ensures your addition resolves the target discrepancy without degrading the established baseline or triggering Catastrophic Backtracking (ReDoS).
+* **The Metrics:** The output is assessed strictly on four vectors: **Accuracy, Speed, Utility, and Ethos.**
+* Only changes that are mathematically and practically *measurably better* across the broader ecosystem will be incorporated into the `main` branch.
+
+---
+
+## 🛠️ Submitting Pull Requests
+
+To ensure your contribution integrates smoothly into the Zero-Trust ecosystem:
+
+1. **Fork and Branch:** Create a feature branch from `main` (`git checkout -b feature/your-feature-name`).
+2. **Maintain the Contract:** Ensure that any backend changes to the CLI do not break the universal JSON schema contract expected by the frontend Observatory. 
+3. **Test Visually:** Run your newly generated `_galaxy.json` through either **[GitGalaxy.io](https://gitgalaxy.io)** or your local **Airgap Observatory** to verify that 3D WebGPU rendering and visual physics constraints remain intact. 
+4. **Document:** If you are adding new language phenotypes or altering the parsing logic, please update the [Language Lens](docs/wiki/02-05-language-lens.md) documentation in the wiki.
+5. **Submit:** Open a PR with a clear title. Explain the *why* behind your structural changes, not just the *what*. Be sure to include the link to the target repository so we can include it in the Differential Scan.
+
+---
+
+## 🐛 Reporting Discrepancies
+
+If the GalaxyScope CLI misidentifies a repository's structure or fails to parse a specific file phenotype, please use our **[Parsing Discrepancy Form](https://github.com/squid-protocol/gitgalaxy/issues/new/choose)**. 
+
+To help us reproduce the issue with quantitative precision, you will be asked to provide:
+* A direct link to the public repository being scanned.
+* The Observatory viewer you were using ([GitGalaxy.io](https://gitgalaxy.io) or Airgap Observatory).
+* A clear description of the expected vs. actual output.
+* The contents of your custom `gitgalaxy_config.py` file (if applicable).
+* Contact information for follow-up questions.
+
+---
+
+## 🛡️ Security Vulnerabilities
+
+If you discover a vulnerability within GitGalaxy itself (e.g., a way to bypass the local sandbox, a ReDoS vector, or an issue in the Airgap Observatory), **do not open a public issue.** Please reach out directly via the contact portal at [GitGalaxy.io](https://gitgalaxy.io) so the vulnerability can be patched securely before public disclosure.
+
+---
+
+## 📜 Licensing Reminder
+
+GitGalaxy is released under the **PolyForm Noncommercial License 1.0.0**. By contributing to this repository, you agree that your contributions will be licensed under these same terms. 
+
+*Note: This tool is free for research, education, testing, and hobby projects. Any commercial use or integration into commercial SaaS products or corporate CI/CD pipelines requires a separate commercial license.*

{gitgalaxy-2.2.0 → gitgalaxy-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitgalaxy
-Version: 2.2.0
+Version: 2.2.2
 Summary: An AST-free, LLM-free zero-trust static analysis engine for mapping architectural risk, securing CI/CD pipelines, and modernizing legacy monoliths.
 Author: Joe Esquibel
 Project-URL: Homepage, https://gitgalaxy.io
@@ -24,7 +24,7 @@ Dynamic: license-file
 # GitGalaxy
 
 [![PyPI version](https://badge.fury.io/py/gitgalaxy.svg)](https://badge.fury.io/py/gitgalaxy)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
 
 [![Engine](https://img.shields.io/badge/Engine-blAST-8A2BE2.svg)](#)
@@ -33,35 +33,38 @@ Dynamic: license-file
 [![Threat Hunting](https://img.shields.io/badge/Threat_Hunting-Behavioral-FF4500.svg)](#)
 [![Architecture](https://img.shields.io/badge/Architecture-Zero__Trust-teal.svg)](#)
 [![Coverage](https://img.shields.io/badge/Coverage-50%2B_Languages-00C957.svg)](#)
-[![Scale](https://img.shields.io/badge/Scale-100k%2B_LOC%2Fsec-00BFFF.svg)](#)
 
 [![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen.svg)](https://pypi.org/project/gitgalaxy/)
 [![Airgap Ready](https://img.shields.io/badge/Security-Airgap_Ready-teal.svg)](#)
+[![Downloads](https://static.pepy.tech/badge/gitgalaxy)](https://pepy.tech/project/gitgalaxy)
 
-### **AST-Free Static Analysis & Knowledge Graph Engine**
+### **Whole-Repository Understanding & DevSecOps Physics**
 
-The blAST (Bypassing LLMs and ASTs) engine is a custom-made knowledge graph engine that resolves repositories at the function level. It scores each function based on 50 unique metrics, rolls that data up to score the file, and finally summarizes the entire repository.
+Most tools analyze code line-by-line. GitGalaxy maps the entire architectural ecosystem. By tracking the exact flow of information across network dependencies, identifying local folder constraints, and natively recognizing 50+ languages—even mid-file—GitGalaxy provides a deterministic, 10,000-foot view of your software's physical architecture.
 
 ### Scanning Apollo-11 with the blAST Engine
 
 ![GitGalaxy CLI Scan](./docs/wiki/assets/apollo11_scan.gif)
 
-By utilizing a custom engine, we retain full control over the search space. We built it to be exceptionally fast, capable of assessing your entire repository without requiring compilable code—a fundamental limitation of standard Abstract Syntax Trees (ASTs). ASTs are great for finding missing commas and memory overflows, but they miss the forest for the trees when generating knowledge graphs. LLMs, on the other hand, suffer from hallucination during large context windows and yield probabilistic, fluctuating answers.
+**Why we built a custom physics engine:**
+Standard Abstract Syntax Trees (ASTs) are great for finding syntax errors, but they require compilable code and miss the forest for the trees when mapping massive-scale information flow. LLMs, on the other hand, suffer from severe hallucination when analyzing large context windows and yield probabilistic, fluctuating answers.
 
-The blAST engine solves this. Because all programming languages utilize keywords and functions, our engine treats code files as text, scanning for these structural anchors to build a deterministic 3D knowledge graph. It seamlessly handles mid-file language switching, assesses the architectural ratio of test files to logic, and extracts invaluable project structure data that ASTs ignore.
+The **blAST (Bypassing LLMs and ASTs) engine** solves this. It reads code as raw structural text, scanning for semantic anchors to build a deterministic 3D knowledge graph of your entire repository. It instantly calculates the ratio of test boundaries to core logic, maps network blast radiuses, and extracts the vital project structure data that rigid linters ignore.
 
-Every assumption our system makes has been abstracted into over 300 tunable variables. Think of GitGalaxy as a highly calibrated telescope. You can query the number of active API network nodes, isolate unique external imports, or highlight functions exhibiting extreme cognitive load—all adjusted via custom whitelists and blacklists to eliminate false-positive fatigue. Field-tested on over 1,000 repositories spanning 50+ languages and 250+ extensions, the engine comes equipped with smart defaults ready for immediate deployment.
+Think of GitGalaxy as a highly calibrated telescope for codebase risk. Every assumption the system makes is abstracted into over 300 tunable variables. You can query active API nodes, isolate supply chain threats, or highlight functions exhibiting extreme cognitive load—all adjusted via custom shields to eliminate false-positive fatigue. Field-tested on over 1,000 repositories, the engine comes equipped with enterprise-grade defaults ready for immediate CI/CD deployment.
 
 **Core Codebase Mapping Technology**
 * Bypasses LLMs and rigid ASTs.
 * Doesn't require code to compile (AST-free).
-* Produces full function-to-function call chains.
+* Produces full network mapping via imports with generlized function calls per file.
 * Deterministically maps code by 60+ keyword regex profiles (Structural markers, I/O intents, state mutations).
 * Regex keyword profiles allow us to classify functions, files, classes, folders and repos.
 * Eliminates LLM architectural hallucinations and context window limits.
 * Scans 50+ languages, 250+ extensions, fully folder-aware. **([How to add a language in 1 minute and 1 prompt](gitgalaxy/standards/HOW_TO_ADD_LANGUAGE.md))**
 
 **Enterprise Scale & Performance Metrics**
+* **Active Pipeline Integration:** Over 11,000 PyPI downloads, driven heavily by automated CI/CD security sweeps and zero-trust DevSecOps workflows.
+* **Production Tested:** Backed by an active early-adopter community on GitHub driving real-world issue resolution, architectural forks, and continuous engine hardening.
 * 100,000 LOC/sec code analysis.
 * 0.07 GB/sec raw log ingestion.
 * Full-system scans in minutes without data sampling.
@@ -85,6 +88,7 @@ GitGalaxy is backed by an academic-grade thesis detailing the equations powering
 **Installation & Usage**
 * Python-based: `pip install gitgalaxy`
 * CLI execution
+* CI/CD Integration: Native **[GitHub Action](github-action-read-me.md)** available for zero-trust DevSecOps pipelines.
 * Outputs forensic JSONs (optimized for AI-agent summary reports) and a native SQLite3 database for robust querying and storage.
 
 > **📖 Official Documentation:** Read the full technical specifications, architecture blueprints, and the Taxonomical Equivalence Map at **[squid-protocol.github.io/gitgalaxy](https://squid-protocol.github.io/gitgalaxy/)**.
@@ -112,8 +116,11 @@ galaxyscope /path/to/your/local/repo
 
 GitGalaxy can be integrated directly into your GitHub Actions pipeline for automated DevSecOps auditing, Zero-Trust SBOM generation, or Pre-Commit firewalls. 
 
-Create a file in your repository at `.github/workflows/gitgalaxy-scan.yml`:
+**🚀 [View the Full GitHub Action Integration Guide](github-action-read-me.md)**
 
+Check out our comprehensive guide to set up the **"Golden Path" Pipeline** (Parallel Enforcement & Autonomous Reporting). It covers all available Sentinel tools, AI guardrails, and advanced configuration options like our hyper-sensitive `--paranoid` threat-hunting mode.
+
+*Minimal Example (Running a single Sentinel):*
 ```yaml
 name: GitGalaxy Security Audit
 
@@ -131,7 +138,7 @@ jobs:
       - name: Run GitGalaxy Supply Chain Firewall
         uses: squid-protocol/gitgalaxy@main
         with:
-          tool: 'supply-chain-firewall' # Options: galaxyscope, zero-trust-sbom, pii-leak-hunter, etc.
+          tool: 'supply-chain-firewall' # View the Integration Guide for the full tool directory
           target: '.'
 ```
 
@@ -158,7 +165,7 @@ A mathematical x-ray suite for sanitizing mainframe monoliths. It safely neutral
 * **Proven Metric:** The Graveyard Reaper engine extracted over 6,700 lines of dead execution blocks and orphaned variables from the standard IBM CICS benchmark app in seconds.
 
 ### [Software Supply Chain Security & Pre-Commit Firewalls](gitgalaxy/tools/supply_chain_security/)
-Extreme-velocity pre-commit firewalls. Instead of trusting manifest files, it scans physical internals to block steganography, sub-atomic XOR decryption loops, homoglyph typosquatting, and exposed cryptographic vaults before they ever enter your CI/CD pipeline.
+Extreme-velocity pre-commit firewalls. Instead of trusting manifest files, it scans physical internals to block steganography, sub-atomic XOR decryption loops, homoglyph typosquatting, and exposed cryptographic vaults before they ever enter your CI/CD pipeline. **[Deploy directly via our GitHub Action](github-action-read-me.md).**
 
 ### [Zero-Trust SBOM Generation & Dependency Auditing](gitgalaxy/tools/compliance/)
 A Zero-Trust Software Bill of Materials (SBOM) generator. It refuses to blindly trust `package.json` or `requirements.txt` files, instead locating the physical dependencies on disk, mathematically verifying their entropy and linguistic identity, and generating strict CycloneDX 1.4 JSON reports.
@@ -196,10 +203,22 @@ Your code never leaves your machine. GitGalaxy performs 100% of its scanning and
 * **Ephemeral Memory Processing:** Repositories are unpacked into a volatile memory buffer (RAM) and are automatically purged when the browser tab is closed.
 * **Privacy-by-Design:** Even when using the web-based viewer, the data remains behind the user's firewall at all times.
 
-## License & Copyright
+## ⚖️ Licensing & Usage
 
 Copyright (c) 2026 Joe Esquibel
 
-GitGalaxy is released under the PolyForm Noncommercial License 1.0.0. It is completely free for personal use, research, experiment, testing, and hobby projects. Use by educational or charitable organizations is also permitted.
+GitGalaxy is distributed under the **PolyForm Noncommercial License 1.0.0**. 
+
+### 🎓 Community Free Tier (Academic, Research, & Hobbyist)
+We are deeply committed to the open-source and academic communities. If you are using GitGalaxy for personal projects, academic research, or non-commercial development, the engine is 100% free to use.
+
+To suppress the commercial licensing delays in your terminal or personal CI/CD pipelines, simply set the following environment variable:
+
+```bash
+export GITGALAXY_LICENSE_KEY="COMMUNITY_FREE_TIER"
+```
+
+### 🏢 Commercial & Enterprise Use
+Running GitGalaxy in corporate environments, proprietary codebases, or commercial CI/CD pipelines requires an enterprise license. Unlicensed corporate pipelines will experience intentional execution friction, and attempting to use the Community Free Tier key in a corporate environment will trigger explicit non-compliance warnings in your audit logs.
 
-Any commercial use or integration into commercial SaaS products or corporate CI/CD pipelines requires a separate commercial license. Please reach out via gitgalaxy.io to discuss commercial integration.
+To acquire a zero-trust commercial key for your organization and ensure clean compliance logs, please contact: **joe@gitgalaxy.io**

{gitgalaxy-2.2.0 → gitgalaxy-2.2.2}/README.md

@@ -1,7 +1,7 @@
 # GitGalaxy
 
 [![PyPI version](https://badge.fury.io/py/gitgalaxy.svg)](https://badge.fury.io/py/gitgalaxy)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
 [![License: PolyForm Noncommercial](https://img.shields.io/badge/License-PolyForm%20Noncommercial-blue.svg)](https://polyformproject.org/licenses/noncommercial/1.0.0/)
 
 [![Engine](https://img.shields.io/badge/Engine-blAST-8A2BE2.svg)](#)
@@ -10,35 +10,38 @@
 [![Threat Hunting](https://img.shields.io/badge/Threat_Hunting-Behavioral-FF4500.svg)](#)
 [![Architecture](https://img.shields.io/badge/Architecture-Zero__Trust-teal.svg)](#)
 [![Coverage](https://img.shields.io/badge/Coverage-50%2B_Languages-00C957.svg)](#)
-[![Scale](https://img.shields.io/badge/Scale-100k%2B_LOC%2Fsec-00BFFF.svg)](#)
 
 [![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen.svg)](https://pypi.org/project/gitgalaxy/)
 [![Airgap Ready](https://img.shields.io/badge/Security-Airgap_Ready-teal.svg)](#)
+[![Downloads](https://static.pepy.tech/badge/gitgalaxy)](https://pepy.tech/project/gitgalaxy)
 
-### **AST-Free Static Analysis & Knowledge Graph Engine**
+### **Whole-Repository Understanding & DevSecOps Physics**
 
-The blAST (Bypassing LLMs and ASTs) engine is a custom-made knowledge graph engine that resolves repositories at the function level. It scores each function based on 50 unique metrics, rolls that data up to score the file, and finally summarizes the entire repository.
+Most tools analyze code line-by-line. GitGalaxy maps the entire architectural ecosystem. By tracking the exact flow of information across network dependencies, identifying local folder constraints, and natively recognizing 50+ languages—even mid-file—GitGalaxy provides a deterministic, 10,000-foot view of your software's physical architecture.
 
 ### Scanning Apollo-11 with the blAST Engine
 
 ![GitGalaxy CLI Scan](./docs/wiki/assets/apollo11_scan.gif)
 
-By utilizing a custom engine, we retain full control over the search space. We built it to be exceptionally fast, capable of assessing your entire repository without requiring compilable code—a fundamental limitation of standard Abstract Syntax Trees (ASTs). ASTs are great for finding missing commas and memory overflows, but they miss the forest for the trees when generating knowledge graphs. LLMs, on the other hand, suffer from hallucination during large context windows and yield probabilistic, fluctuating answers.
+**Why we built a custom physics engine:**
+Standard Abstract Syntax Trees (ASTs) are great for finding syntax errors, but they require compilable code and miss the forest for the trees when mapping massive-scale information flow. LLMs, on the other hand, suffer from severe hallucination when analyzing large context windows and yield probabilistic, fluctuating answers.
 
-The blAST engine solves this. Because all programming languages utilize keywords and functions, our engine treats code files as text, scanning for these structural anchors to build a deterministic 3D knowledge graph. It seamlessly handles mid-file language switching, assesses the architectural ratio of test files to logic, and extracts invaluable project structure data that ASTs ignore.
+The **blAST (Bypassing LLMs and ASTs) engine** solves this. It reads code as raw structural text, scanning for semantic anchors to build a deterministic 3D knowledge graph of your entire repository. It instantly calculates the ratio of test boundaries to core logic, maps network blast radiuses, and extracts the vital project structure data that rigid linters ignore.
 
-Every assumption our system makes has been abstracted into over 300 tunable variables. Think of GitGalaxy as a highly calibrated telescope. You can query the number of active API network nodes, isolate unique external imports, or highlight functions exhibiting extreme cognitive load—all adjusted via custom whitelists and blacklists to eliminate false-positive fatigue. Field-tested on over 1,000 repositories spanning 50+ languages and 250+ extensions, the engine comes equipped with smart defaults ready for immediate deployment.
+Think of GitGalaxy as a highly calibrated telescope for codebase risk. Every assumption the system makes is abstracted into over 300 tunable variables. You can query active API nodes, isolate supply chain threats, or highlight functions exhibiting extreme cognitive load—all adjusted via custom shields to eliminate false-positive fatigue. Field-tested on over 1,000 repositories, the engine comes equipped with enterprise-grade defaults ready for immediate CI/CD deployment.
 
 **Core Codebase Mapping Technology**
 * Bypasses LLMs and rigid ASTs.
 * Doesn't require code to compile (AST-free).
-* Produces full function-to-function call chains.
+* Produces full network mapping via imports with generlized function calls per file.
 * Deterministically maps code by 60+ keyword regex profiles (Structural markers, I/O intents, state mutations).
 * Regex keyword profiles allow us to classify functions, files, classes, folders and repos.
 * Eliminates LLM architectural hallucinations and context window limits.
 * Scans 50+ languages, 250+ extensions, fully folder-aware. **([How to add a language in 1 minute and 1 prompt](gitgalaxy/standards/HOW_TO_ADD_LANGUAGE.md))**
 
 **Enterprise Scale & Performance Metrics**
+* **Active Pipeline Integration:** Over 11,000 PyPI downloads, driven heavily by automated CI/CD security sweeps and zero-trust DevSecOps workflows.
+* **Production Tested:** Backed by an active early-adopter community on GitHub driving real-world issue resolution, architectural forks, and continuous engine hardening.
 * 100,000 LOC/sec code analysis.
 * 0.07 GB/sec raw log ingestion.
 * Full-system scans in minutes without data sampling.
@@ -62,6 +65,7 @@ GitGalaxy is backed by an academic-grade thesis detailing the equations powering
 **Installation & Usage**
 * Python-based: `pip install gitgalaxy`
 * CLI execution
+* CI/CD Integration: Native **[GitHub Action](github-action-read-me.md)** available for zero-trust DevSecOps pipelines.
 * Outputs forensic JSONs (optimized for AI-agent summary reports) and a native SQLite3 database for robust querying and storage.
 
 > **📖 Official Documentation:** Read the full technical specifications, architecture blueprints, and the Taxonomical Equivalence Map at **[squid-protocol.github.io/gitgalaxy](https://squid-protocol.github.io/gitgalaxy/)**.
@@ -89,8 +93,11 @@ galaxyscope /path/to/your/local/repo
 
 GitGalaxy can be integrated directly into your GitHub Actions pipeline for automated DevSecOps auditing, Zero-Trust SBOM generation, or Pre-Commit firewalls. 
 
-Create a file in your repository at `.github/workflows/gitgalaxy-scan.yml`:
+**🚀 [View the Full GitHub Action Integration Guide](github-action-read-me.md)**
 
+Check out our comprehensive guide to set up the **"Golden Path" Pipeline** (Parallel Enforcement & Autonomous Reporting). It covers all available Sentinel tools, AI guardrails, and advanced configuration options like our hyper-sensitive `--paranoid` threat-hunting mode.
+
+*Minimal Example (Running a single Sentinel):*
 ```yaml
 name: GitGalaxy Security Audit
 
@@ -108,7 +115,7 @@ jobs:
       - name: Run GitGalaxy Supply Chain Firewall
         uses: squid-protocol/gitgalaxy@main
         with:
-          tool: 'supply-chain-firewall' # Options: galaxyscope, zero-trust-sbom, pii-leak-hunter, etc.
+          tool: 'supply-chain-firewall' # View the Integration Guide for the full tool directory
           target: '.'
 ```
 
@@ -135,7 +142,7 @@ A mathematical x-ray suite for sanitizing mainframe monoliths. It safely neutral
 * **Proven Metric:** The Graveyard Reaper engine extracted over 6,700 lines of dead execution blocks and orphaned variables from the standard IBM CICS benchmark app in seconds.
 
 ### [Software Supply Chain Security & Pre-Commit Firewalls](gitgalaxy/tools/supply_chain_security/)
-Extreme-velocity pre-commit firewalls. Instead of trusting manifest files, it scans physical internals to block steganography, sub-atomic XOR decryption loops, homoglyph typosquatting, and exposed cryptographic vaults before they ever enter your CI/CD pipeline.
+Extreme-velocity pre-commit firewalls. Instead of trusting manifest files, it scans physical internals to block steganography, sub-atomic XOR decryption loops, homoglyph typosquatting, and exposed cryptographic vaults before they ever enter your CI/CD pipeline. **[Deploy directly via our GitHub Action](github-action-read-me.md).**
 
 ### [Zero-Trust SBOM Generation & Dependency Auditing](gitgalaxy/tools/compliance/)
 A Zero-Trust Software Bill of Materials (SBOM) generator. It refuses to blindly trust `package.json` or `requirements.txt` files, instead locating the physical dependencies on disk, mathematically verifying their entropy and linguistic identity, and generating strict CycloneDX 1.4 JSON reports.
@@ -173,10 +180,22 @@ Your code never leaves your machine. GitGalaxy performs 100% of its scanning and
 * **Ephemeral Memory Processing:** Repositories are unpacked into a volatile memory buffer (RAM) and are automatically purged when the browser tab is closed.
 * **Privacy-by-Design:** Even when using the web-based viewer, the data remains behind the user's firewall at all times.
 
-## License & Copyright
+## ⚖️ Licensing & Usage
 
 Copyright (c) 2026 Joe Esquibel
 
-GitGalaxy is released under the PolyForm Noncommercial License 1.0.0. It is completely free for personal use, research, experiment, testing, and hobby projects. Use by educational or charitable organizations is also permitted.
+GitGalaxy is distributed under the **PolyForm Noncommercial License 1.0.0**. 
+
+### 🎓 Community Free Tier (Academic, Research, & Hobbyist)
+We are deeply committed to the open-source and academic communities. If you are using GitGalaxy for personal projects, academic research, or non-commercial development, the engine is 100% free to use.
+
+To suppress the commercial licensing delays in your terminal or personal CI/CD pipelines, simply set the following environment variable:
+
+```bash
+export GITGALAXY_LICENSE_KEY="COMMUNITY_FREE_TIER"
+```
+
+### 🏢 Commercial & Enterprise Use
+Running GitGalaxy in corporate environments, proprietary codebases, or commercial CI/CD pipelines requires an enterprise license. Unlicensed corporate pipelines will experience intentional execution friction, and attempting to use the Community Free Tier key in a corporate environment will trigger explicit non-compliance warnings in your audit logs.
 
-Any commercial use or integration into commercial SaaS products or corporate CI/CD pipelines requires a separate commercial license. Please reach out via gitgalaxy.io to discuss commercial integration.
+To acquire a zero-trust commercial key for your organization and ensure clean compliance logs, please contact: **joe@gitgalaxy.io**

{gitgalaxy-2.2.0 → gitgalaxy-2.2.2}/gitgalaxy/README.md

@@ -16,7 +16,7 @@ When you trigger the `galaxyscope` command, the data flows through these five ph
 * **`/physics/` (The Math):** The heuristics engine. Contains the [Signal Processor](https://squid-protocol.github.io/gitgalaxy/02-09-signal-processing/) and [Neural Auditor](https://squid-protocol.github.io/gitgalaxy/02-19-neural-auditor/), which apply GitGalaxy mathematics to score O(N) complexity, topological blast radius, and state flux without using ASTs.
 * **`/recorders/` (The Exporters):** The translation layer. Converts the internal state maps into highly relational [SQLite Databases](https://squid-protocol.github.io/gitgalaxy/02-21-record-keeper/), AI-agent JSON tickets, and the final 3D WebGPU payload.
 * **`/security/` (The Sentinel):** The zero-trust validation layer. Contains the [Security Lens](https://squid-protocol.github.io/gitgalaxy/02-06-security-lens/) responsible for intercepting embedded malware, hardcoded secrets, and logic bombs on the fly.
-* **`/tools/` (The Spokes):** The enterprise automation layer. Contains specialized controllers for CI/CD pipelines—like the [Supply Chain Firewall](https://squid-protocol.github.io/gitgalaxy/04-03-supply-chain-firewall/) and [PII Leak Hunter](https://squid-protocol.github.io/gitgalaxy/04-06-pii-leak-hunter/)—that consume the core engine's telemetry.
+* **`/tools/` (The Spokes):** The enterprise automation layer. Contains specialized controllers for CI/CD pipelines—like the [Supply Chain Firewall](https://squid-protocol.github.io/gitgalaxy/04-03-supply-chain-firewall/) and [PII Leak Hunter](https://squid-protocol.github.io/gitgalaxy/04-06-pii-leak-hunter/)—that consume the core engine's telemetry. **These specialized tools power our official [Zero-Trust DevSecOps GitHub Action](../github-action-read-me.md).**
 
 ---
 
@@ -52,7 +52,12 @@ From the **root directory** of the repository, run:
 pip install -e .
 ```
 
-Once installed, you can trigger the main orchestrator globally from your terminal. This command runs the full [Data Pipeline](https://squid-protocol.github.io/gitgalaxy/02-01-pipeline-overview/) and outputs the final artifact.
+**Important:** GitGalaxy contains an embedded commercial licensing guardrail. To prevent a 5-second execution delay while testing your code locally, you must export the Community Free Tier key into your development environment before running the orchestrator:
+```bash
+export GITGALAXY_LICENSE_KEY="COMMUNITY_FREE_TIER"
+```
+
+Once installed and the key is set, you can trigger the main orchestrator globally from your terminal. This command runs the full [Data Pipeline](https://squid-protocol.github.io/gitgalaxy/02-01-pipeline-overview/) and outputs the final artifact.
 ```bash
 galaxyscope /path/to/test/repo --debug
 ```
@@ -69,4 +74,4 @@ To fully understand how GalaxyScope processes data, maps files, and applies risk
 * 📖 **[GalaxyScope CLI Reference](https://squid-protocol.github.io/gitgalaxy/01-02-galaxyscope-cli-reference/)** (Flags, outputs, and behaviors)
 * 📖 **[The Data Pipeline Overview](https://squid-protocol.github.io/gitgalaxy/02-01-pipeline-overview/)** (Step-by-step breakdown of the runtime)
 * 📖 **[Risk Exposures & Methodology](https://squid-protocol.github.io/gitgalaxy/08-01-methodology/)** (The math behind the heuristics)
-* 🪐 **[Return to the Main GitGalaxy Hub](https://github.com/squid-protocol/gitgalaxy)**
+* 🪐 **[Return to the Main GitGalaxy Hub](https://github.com/squid-protocol/gitgalaxy)**