cleanup and README

Author: joenaess

.github/workflows/self-test.yml

@@ -11,6 +11,7 @@ results.json
 recommendation.md
 LICENSE
 uv.lock
+legacy/
 
 # OS
 .DS_Store

.github/workflows/toolkit-ci.yml

@@ -1,2 +1,75 @@
-# compliance-toolkit
-testing open toolkit
+# 🛡️ Org Compliance Toolkit
+
+An automated license compliance and open-source readiness tool. Built with [uv](https://github.com/astral-sh/uv) and [ScanCode Toolkit](https://github.com/nexB/scancode-toolkit).
+
+## 🚀 Purpose
+
+This toolkit helps developers determine if their repository is ready for an Open Source release. It:
+
+1. **Scans** all dependencies for licenses.
+2. **Flags** licenses that hinder commercial or proprietary releases.
+3. **Recommends** the best Open Source license (MIT, Apache, GPL, or AGPL).
+4. **Generates** a valid `LICENSE` file automatically from official SPDX templates.
+
+---
+
+## 🛠️ Usage in GitHub Actions
+
+To use this in your project's repository, add a workflow file (e.g., `.github/workflows/compliance.yml`):
+
+```yaml
+name: OS Readiness Check
+on: [pull_request, workflow_dispatch]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run License Recommender
+        uses: your-org-name/compliance-toolkit/.github/actions/license-check@main
+        with:
+          apply_fix: 'false' # Set to 'true' to auto-generate a LICENSE file
+```
+
+## 💻 Local Development
+
+If you want to contribute to this toolkit, follow these steps:
+
+### 1. Prerequisites
+
+Install `uv` (the ultra-fast Python package manager):
+
+```bash
+curl -LsSf [https://astral-sh.net/uv/install.sh](https://astral-sh.net/uv/install.sh) | sh
+```
+
+### 2. Running the tool
+
+You can run the tool directly against any directory. uv will handle the dependencies and isolation automatically.
+
+```bash
+uv run compliance_tool.py [path/to/repo]
+```
+
+### 3. Formatting & Quality
+
+We use Ruff for linting and Pytest for logic verification. Ensure these pass before pushing code:
+
+```bash
+# Check code style and fix common issues
+uvx ruff check . --fix
+
+# Run logic tests to ensure recommendations are accurate
+uv run pytest
+```
+
+## ⚖️ License Logic
+The tool evaluates your project's "Inbound" dependencies (what you use) to determine the safest "Outbound" license (what you release under).
+
+| Dependency License | Recommended Release | Commercial Allowed? | Rationale |
+| :--- | :--- | :--- | :--- |
+| **MIT / Apache / BSD** | **Apache-2.0** or **MIT** | ✅ Yes | Permissive licenses allow for both open and proprietary re-distribution. |
+| **LGPL** | **Apache-2.0** | ⚠️ Restricted | Allowed commercially if the library is dynamically linked and not modified. |
+| **GPL (v2 or v3)** | **GPL-3.0-only** | ❌ No | Strong copyleft "viral" effect requires your project to be Open Source. |
+| **AGPL** | **AGPL-3.0-only** | ❌ No | Extends copyleft to network services (SaaS). Your source must be public. |