feat: SDK v0.5.2 — dashboard overhaul, lazy graph import, metrics reorganization

- Dashboard: 4-phase mission-driven UI (Identity → Policy → Verify → Report)
- Fix: lazy-load graph workflow in annex_generator to avoid crash without agentic extras
- Reorganize metrics under assurance/ (fairness, privacy, quality, performance, causal)
- Remove legacy venturalitica.graph, venturalitica.fairness, venturalitica.quality paths
- Add column-binding docs, compliance-mapping, dashboard guide
- E2E test updated for new dashboard title
- Probes refactored into individual modules

Author: morganrcu

.gitignore

@@ -57,3 +57,5 @@ results.json
 venturalitica_technical_doc.json
 system_description.yaml
 bom.json
+node_modules/
+starlight/.astro/

CHANGELOG.md

@@ -2,6 +2,99 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.0-starlight] - 2026-02-18
+
+### Astro Starlight Documentation Migration
+
+Migrated all documentation from MkDocs → Mintlify → **Astro Starlight** (open-source) with bilingual support (EN/ES) and automatic `llms.txt` generation via the `starlight-llms-txt` plugin.
+
+#### New Documentation Platform (`starlight/`)
+- **Astro Starlight**: Open-source documentation framework with first-class i18n, search, and static site generation
+- **`astro.config.mjs`**: Full configuration with i18n (root EN, `es` locale), 5-group sidebar, `starlight-llms-txt` plugin
+- **18 English `.mdx` pages**: Complete content in `src/content/docs/`
+- **18 Spanish `.mdx` pages**: Complete Spanish mirror in `src/content/docs/es/` with accent fixes and translated prose
+- **`src/content/i18n/es.json`**: Spanish UI string overrides for sidebar groups and labels
+- **`src/styles/custom.css`**: Custom theme styling
+- **`public/images/`**: Consolidated image assets (logo.svg, favicon.svg, 5 PNGs)
+- **Pagefind search**: Indexed 36 pages across 2 languages, 4781 words
+
+#### Syntax Conversions Applied (Mintlify → Starlight)
+- Admonitions: `<Note>` → `:::note`, `<Warning>` → `:::caution`, `<Tip>` → `:::tip`, `<Danger>` → `:::danger`
+- Tabbed content: `<Tabs><Tab>` → separate labeled code blocks (no imports needed)
+- Card groups: `<CardGroup><Card>` → plain markdown link lists
+- Frontmatter: `sidebarTitle` → `sidebar: { label: "..." }`
+- Internal links: removed `/es/` prefix (Starlight handles i18n routing), added trailing slashes
+- Spanish accent fixes applied throughout all prose text
+
+#### `llms.txt` Generation
+- **`starlight-llms-txt`** plugin auto-generates during build:
+  - `dist/llms.txt` (586B) — index with links to full/small versions
+  - `dist/llms-full.txt` (149KB) — complete documentation for LLM consumption
+  - `dist/llms-small.txt` (128KB) — abridged version with non-essential content removed
+
+#### Key Benefits
+- **Open-source**: No vendor lock-in or subscription costs (Mintlify requires paid plan)
+- **Native `llms.txt`**: Auto-generated by `starlight-llms-txt` plugin during build
+- **i18n**: Root locale (EN) + `es` locale with automatic language routing
+- **Search**: Pagefind-powered full-text search across both languages
+- **Zero-error build**: 37 pages built in ~10s with zero warnings
+
+#### Cleanup
+- Removed `mintlify/` directory (superseded by `starlight/`)
+- Removed `mkdocs.yml` configuration file
+- Removed MkDocs dependencies from `pyproject.toml` (`mkdocs`, `mkdocs-material`, `mkdocs-macros-plugin`, `mkdocs-static-i18n`, `pymdown-extensions`, `mkdocs-llmstxt`)
+- Updated Documentation URL in `pyproject.toml` to `https://venturalitica.github.io/venturalitica-sdk`
+- MkDocs `docs/` source directory preserved for reference
+
+---
+
+## [0.5.0-docs] - 2026-02-18
+
+### Documentation Overhaul
+
+Comprehensive documentation rewrite addressing all gaps identified in the strategic audit.
+
+#### New Documentation (8 pages)
+- **docs/metrics.md**: Complete metrics reference (35+ metrics, 7 categories, formulas, thresholds)
+- **docs/dashboard.md**: Glass Box Dashboard user guide (4 phases, 7 views, session management)
+- **docs/policy-authoring.md**: OSCAL policy authoring guide (assessment-plan format, props reference, two-policy pattern)
+- **docs/column-binding.md**: Column binding documentation (synonym table, resolution algorithm, multilingual support)
+- **docs/experimental.md**: Experimental features page (CLI login/pull/push, SaaS status, feature matrix)
+- **docs/probes.md**: Probes reference (7 probes, EU AI Act article mapping, evidence structure)
+- **docs/full-lifecycle.md**: Zero to Annex IV single-page walkthrough (copy-paste ready)
+- **docs/multiclass-fairness.md**: Multiclass fairness metrics deep dive (7 metrics, strategies, intersectional analysis)
+- **docs/compliance-mapping.md**: ISO 42001 / EU AI Act mapping (article-by-article SDK capability mapping)
+
+#### Fixed Documentation (4 pages)
+- **docs/api.md**: Fully rewritten with correct `enforce()` and `monitor()` signatures from source code
+- **docs/quickstart.md**: Fixed install command from `pip install git+...` to `pip install venturalitica`
+- **docs/index.md**: Rewritten with correct install, new doc links, removed stale references
+- **docs/es/quickstart.md**: Fixed install command in Spanish mirror
+
+#### Updated Documentation (4 pages)
+- **docs/academy/level1_policy.md**: Expanded with real data_policy.oscal.yaml (3 controls), expected output, prop reference table
+- **docs/academy/level2_integrator.md**: Fixed commands, added cross-references to new docs
+- **docs/academy/level3_auditor.md**: Fixed duplicate heading, updated code to use `load_sample()`, added references
+- **docs/academy/level4_annex_iv.md**: Fixed commands, updated code, replaced stale links with new doc references
+
+#### Spanish Mirror (`docs/es/`) — Full Update
+- Rewrote `es/api.md` and `es/index.md` to match new English sources
+- Rewrote all 4 academy levels (`es/academy/level1–level4`) with updated code, outputs, and cross-references
+- Created 8 new Spanish pages: `es/metrics.md`, `es/dashboard.md`, `es/policy-authoring.md`, `es/column-binding.md`, `es/experimental.md`, `es/probes.md`, `es/full-lifecycle.md`, `es/multiclass-fairness.md`, `es/compliance-mapping.md`
+- Updated `es/quickstart.md` "What's next" links to point to all new documentation pages
+- Verified `es/academy/index.md` and `es/tutorials/01_writing_policy.md` (no changes needed)
+
+#### Housekeeping
+- Deleted 15 empty `gov_*.md` placeholder files from project root
+- Updated `mkdocs.yml` navigation to include all new documentation pages
+- Removed references to nonexistent pages (training.md, integrations.md, compliance-dashboard.md, compliance-gap.md)
+- Unified OSCAL format references to `assessment-plan` as canonical throughout docs
+- Moved 8 stale English docs and 7 stale Spanish docs to `docs/.archive/` and `docs/es/.archive/` respectively
+- Removed `mkdocs-llmstxt` plugin: incompatible with `mkdocs-static-i18n` (i18n sub-build resets plugin state, producing empty `llms.txt`); build now runs with zero warnings
+
+#### Known Issues / Technical Debt
+- **Platform migration tracked:** `mkdocs-llmstxt` 0.5.0 is unmaintained and broken with the i18n plugin. Agent-friendly docs (`llms.txt`, content negotiation, per-page `.md` serving) require migrating to a platform with native support — **Mintlify** (recommended for AI compliance SDK) or **Docusaurus** (open-source, community `docusaurus-plugin-llms` plugin). Migration is a separate workstream.
+
 ## [0.5.0] - 2026-02-12
 
 ### "Marie Kondo" Release - Code Quality & Release Finalization
@@ -151,12 +244,12 @@ None at this time.
 
 Available on PyPI:
 ```bash
-pip install venturalitica-sdk==0.5.0
+pip install venturalitica==0.5.0
 ```
 
 Or with UV:
 ```bash
-uv add venturalitica-sdk==0.5.0
+uv add venturalitica==0.5.0
 ```
 
 ---

README.md

@@ -1,11 +1,17 @@
 # Venturalítica SDK
 
-![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)
+![coverage](https://img.shields.io/badge/coverage-73%25-yellow)
+[![PyPI](https://img.shields.io/pypi/v/venturalitica)](https://pypi.org/project/venturalitica/)
+[![Python](https://img.shields.io/pypi/pyversions/venturalitica)](https://pypi.org/project/venturalitica/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)
+[![Discord](https://img.shields.io/discord/P4RURqRm?label=Discord&logo=discord)](https://discord.gg/P4RURqRm)
 
 **Frictionless Governance for AI Systems.**
 
 The Venturalítica SDK enables Data Scientists and ML Engineers to integrate compliance and risk management directly into their training workflows. Built on the **OSCAL** (Open Security Controls Assessment Language) standard, it provides semantic policy enforcement with educational audit trails.
 
+**[Join our Discord community](https://discord.gg/P4RURqRm)** — Get help, share your use case, and discuss EU AI Act compliance with other engineers.
+
 ## ✨ Key Features
 
 - **Glass Box Governance**: Sequential regulatory mapping (Art 9-15) for total transparency.
@@ -21,7 +27,7 @@ The Venturalítica SDK enables Data Scientists and ML Engineers to integrate com
 ## 📦 Installation
 
 ```bash
-pip install git+https://github.com/Venturalitica/venturalitica-sdk.git
+pip install venturalitica
 ```
 
 ## ⚙️ Configuration
@@ -103,11 +109,11 @@ vl.enforce(
 
 ## 📚 Documentation
 
-- **[Tutorial: Zero-Setup Audit](docs/tutorials/local-audit.md)**: "Hello World" - Scan & Visualize in 2 minutes
-- **[Tutorial: Training Integration](docs/training.md)**: Add compliance checks to your Python code
-- **[Concept: Strict Mode](docs/strict_mode.md)**: Enforcing compliance in CI/CD chains
-- **[Concept: The Regulatory Map](docs/compliance-dashboard.md)**: Understanding the Dashboard (Art 9-15)
-- **[Concept: Evidence Collection](docs/evidence-collection.md)**: How to record your audits
+- **[Quickstart Guide](docs/quickstart.md)**: Get started in 60 seconds
+- **[Full Lifecycle Walkthrough](docs/full-lifecycle.md)**: Zero to Annex IV in one page
+- **[Policy Authoring](docs/policy-authoring.md)**: Write OSCAL policies for your AI systems
+- **[Compliance Dashboard](docs/dashboard.md)**: Understanding the Glass Box Dashboard (Art 9-15)
+- **[Evidence Probes](docs/probes.md)**: Automated evidence collection for audits
 - **[Samples Repository](https://github.com/venturalitica/venturalitica-sdk-samples)**: Real-world examples
 
 ## 🎯 Core Concepts
@@ -153,7 +159,7 @@ Launch the **Local Regulatory Map** to interpret your evidence:
 venturalitica ui
 ```
 
-**[Read the Guide: Understanding the Dashboard](docs/compliance-dashboard.md)**
+**[Read the Guide: Understanding the Dashboard](docs/dashboard.md)**
 
 **Features:**
 *   **Article 9-15 Walk**: A sequential check of Risk, Data, Transparency, and Oversight.
@@ -166,6 +172,21 @@ venturalitica ui
 *   OSCAL policies
 
 
+
+## 📡 Telemetry & Privacy
+
+Venturalítica collects **anonymous usage data** to help us improve the SDK.
+- **What we track**: Command usage (`login`, `pull`, `push`), SDK execution times, and errors.
+- **What we DO NOT track**: Your datasets, PII, IP addresses, or any code content.
+- **Privacy First**: We host our analytics in the **EU** and strictly disable IP tracking (`disable_geoip=True`).
+
+**Opt-Out:**
+To disable telemetry completely, set the environment variable:
+```bash
+export VENTURALITICA_NO_ANALYTICS=1
+```
+Or follow the standard [DO_NOT_TRACK](https://consoledonottrack.com/) specification.
+
 ## 🔒 Data Sovereignty & Privacy
 
 Venturalítica follows a strict **Local-First** architecture.

RELEASE_NOTES.md

@@ -182,12 +182,12 @@ This release was completed as part of Phase 4 "Marie Kondo" code quality refacto
 
 Available on PyPI:
 ```bash
-pip install venturalitica-sdk==0.5.0
+pip install venturalitica==0.5.0
 ```
 
 Or with UV:
 ```bash
-uv add venturalitica-sdk==0.5.0
+uv add venturalitica==0.5.0
 ```
 
 ---

docs/.archive/README.md

@@ -1,6 +1,6 @@
 # Venturalítica SDK Documentation
 
-**Frictionless Governance for AI Systems**
+**Frictionless Assurance for AI Systems**
 
 Welcome! This documentation is designed to get you from zero to compliant in minutes, not days.
 
@@ -78,7 +78,7 @@ Start here if you need **audit-ready documentation**:
 4. **Handshake Moment**: Realize you need organizational policies → Upgrade to SaaS
 
 ### Path 2: Compliance-First Onboarding
-**Goal**: Understand governance architecture before implementation
+**Goal**: Understand assurance architecture before implementation
 
 1. [Core Concepts](core-concepts.md) - Understand the "why"
 2. [OSCAL Authoring](oscal-authoring.md) - Write your policies

docs/.archive/advanced.md

@@ -30,11 +30,11 @@ By default, the SDK looks for policies in the local filesystem. You can customiz
 
 ```python
 from venturalitica.storage import LocalFileSystemStorage
-from venturalitica.core import GovernanceValidator
+from venturalitica.core import AssuranceValidator
 
 # Use custom policy storage location
 storage = LocalFileSystemStorage(base_path="/custom/policies")
-validator = GovernanceValidator("risks.oscal.yaml", storage=storage)
+validator = AssuranceValidator("risks.oscal.yaml", storage=storage)
 ```
 
 ## Robust Evaluation: Handling Missing Columns

docs/annex-iv.md docs/.archive/annex-iv.mddocs/annex-iv.md renamed to docs/.archive/annex-iv.md

@@ -30,7 +30,7 @@ venturalitica ui
 The system will analyze your local `.venturalitica/` folder and pull:
     *   **System Architecture** (from `bom.json`)
     *   **Risk Management Status** (from Article 9 Audit Results)
-    *   **Data Governance** (from Article 10 Audit Results)
+    *   **Data Assurance** (from Article 10 Audit Results)
     *   **Cybersecurity** (from CVE scans)
 
 ### Step 3: Download the Draft

docs/annex_iv_alignment.md docs/.archive/annex_iv_alignment.mddocs/annex_iv_alignment.md renamed to docs/.archive/annex_iv_alignment.md

@@ -9,4 +9,4 @@
 | **2(e) Human Oversight** | Measures for Article 14, output interpretation tools. | `HandshakeProbe` mandates `vl.enforce()`. Dashboard provides "Glass Box" interpretability. | ✅ High |
 | **2(f) Change Management** | Pre-determined changes, continuous compliance technical solutions. | `IntegrityProbe` detects drift. `CI` Strict Mode prevents unapproved changes from deploying. | ✅ High |
 | **2(g) Validation & Testing** | Testing data, metrics (accuracy/robustness/bias), test logs. | `vl.monitor()` captures execution metrics. `ComplianceResult` binds metrics to policy objectives. | ✅ High |
-| **2(h) Cybersecurity** | Cybersecurity measures put in place. | **HMAC-SHA256 Signing** of evidence + `IntegrityProbe` (Environment Fingerprinting). | ✅ High (Pilot) |
+| **2(h) Cybersecurity** | Cybersecurity measures put in place. | **HMAC-SHA256 Signing** of bundles + `IntegrityProbe` (Environment Fingerprinting). | ✅ High (Pilot) |

docs/.archive/cli-tools.md

@@ -1,6 +1,6 @@
 # CLI Tools
 
-The Venturalítica SDK provides powerful command-line tools for project analysis, compliance scanning, and interactive governance management.
+The Venturalítica SDK provides powerful command-line tools for project analysis, compliance scanning, and interactive assurance management.
 
 ## 1. BOM Scanner: `venturalitica scan`
 
@@ -58,9 +58,9 @@ Validate technical aspects independently of organizational policy.
 - **BOM Viewer**: Explore your system's inventory.
 - **Green AI Tracking**: View carbon emissions, energy consumption, and training duration.
 
-#### Tab 2: 🏛️ Governance & Risks
-Highlight governance gaps and map technical metrics to regulatory requirements.
-- **Risk Identification**: List compliance risks (Bias, Oversight, Data Governance).
+#### Tab 2: 🏛️ Assurance & Risks
+Highlight assurance gaps and map technical metrics to regulatory requirements.
+- **Risk Identification**: List compliance risks (Bias, Oversight, Data Assurance).
 - **Mitigation Gap Analysis**: Identify missing mitigation plans in your OSCAL policies.
 
 #### Tab 3: 📄 Documentation

docs/compliance-dashboard.md docs/.archive/compliance-dashboard.mddocs/compliance-dashboard.md renamed to docs/.archive/compliance-dashboard.md

@@ -1,6 +1,6 @@
 # The Compliance Dashboard: A Glass Box for AI
 
-The **Venturalítica Compliance Dashboard** is your local control center for AI Governance. Unlike "Black Box" compliance tools that operate behind closed doors, Venturalítica provides is a **Glass Box** experience: it exposes the exact technical evidence your system is producing and maps it directly to regulatory obligations.
+The **Venturalítica Compliance Dashboard** is your local control center for AI Assurance. Unlike "Black Box" compliance tools that operate behind closed doors, Venturalítica provides is a **Glass Box** experience: it exposes the exact technical evidence your system is producing and maps it directly to regulatory obligations.
 
 The dashboard makes the abstract concrete. It takes the invisible artifacts of your ML pipeline—metrics, logs, dependencies—and renders them into a **Regulatory Traceability Matrix**.
 
@@ -19,7 +19,7 @@ The core feature of the dashboard is the strict sequential mapping of the **EU A
     *   `Mitigation Verified`: Your fairness tests passed.
     *   `Risk Materialized`: A test failed (e.g., Disparate Impact detected).
 
-#### 2. [Article 10: Data Governance](https://artificialintelligenceact.eu/article/10/)
+#### 2. [Article 10: Data Assurance](https://artificialintelligenceact.eu/article/10/)
 *   **The Law**: Training, validation, and testing data must be relevant, representative, and error-free.
 *   **The Code**: Maps to your **Data Quality Checks** (e.g., class imbalance, missing values) and usage of data libraries (`pandas`, `numpy`).
 *   **Status**: Flags if data validation was skipped or failed.