Principled-Evolution · kmadan · May 14, 2026 · May 14, 2026
diff --git a/README.md b/README.md
@@ -14,7 +14,10 @@
 </p>
 
 <p align="center">
-  <em>94 policies. 15+ regulatory frameworks. 5 industry verticals. Policy-as-code your auditor can read.</em>
+  <em>AI compliance rules you can read, run, diff, and prove.</em>
+</p>
+<p align="center">
+  <sub>94 policies · 15+ regulatory frameworks · 5 industry verticals</sub>
 </p>
 
 <p align="center">
@@ -31,7 +34,9 @@
 
 <br>
 
-**Governance Open Policy Agent Library** — a curated collection of [OPA](https://www.openpolicyagent.org/) policies, written in Rego, that encode real AI-governance requirements: the EU AI Act, NIST AI RMF, aviation safety standards, FERPA/COPPA in education, fair-lending rules in banking, and more.
+**GOPAL: Governance Open Policy Agent Library.** Think of it as an open policy pack for AI regulation.
+
+A curated collection of [OPA](https://www.openpolicyagent.org/) policies, written in Rego, that encode real AI-governance requirements: the EU AI Act, NIST AI RMF, aviation safety standards, FERPA/COPPA in education, fair-lending rules in banking, and more.
 
 Run them against your AI system's metadata, model cards, or evaluation results — and get back a structured, machine-readable compliance verdict you can drop into CI, an audit log, or a regulator submission.
 
@@ -44,6 +49,30 @@ Run them against your AI system's metadata, model cards, or evaluation results
 
 ---
 
+## AI compliance rules you can read, run, diff, and prove
+
+GOPAL turns regulatory and governance requirements — the EU AI Act, NIST AI RMF, aviation safety standards, FERPA/COPPA, fair lending, and healthcare safety — into executable OPA policies.
+
+Use GOPAL when you want AI governance checks that are:
+
+- **Readable** — every rule is Rego, not a black-box score
+- **Reviewable** — policy changes go through pull requests
+- **Testable** — every policy can have allow/deny test cases
+- **Versioned** — frameworks evolve without breaking pinned users
+- **Automatable** — run checks in CI/CD, audit workflows, or AICertify
+
+---
+
+## Why now
+
+The EU AI Act is in force. The NIST AI RMF is the de facto US baseline. The UK, India, Brazil, Singapore, and California are all moving. Aviation regulators are publishing AI/UAS guidance. Financial supervisors are issuing model-risk requirements.
+
+Engineering teams need AI governance checks that run in CI — not PDFs that sit on a shared drive, not screenshots pasted into review-board decks.
+
+GOPAL ships executable Rego policies for each of those regimes. They are versioned, testable, and reviewable in pull requests. The same tooling your platform team already uses for Kubernetes admission control can now enforce AI-system requirements.
+
+---
+
 ## Quick Start
 
 <p align="center">
@@ -53,6 +82,16 @@ Run them against your AI system's metadata, model cards, or evaluation results
   </picture>
 </p>
 
+### Try GOPAL in 30 seconds
+
+```bash
+git clone https://github.com/Principled-Evolution/gopal.git
+cd gopal/examples/eu-ai-act-transparency
+./run.sh
+```
+
+You'll see a structured EU AI Act transparency verdict against a sample AI system. See [`examples/`](examples/) for NIST AI RMF, customer-support LLM, and more.
+
 ### Standalone with the OPA CLI
 
 ```bash
@@ -99,6 +138,22 @@ GOPAL is different on three axes:
 
 ---
 
+## For OPA / Rego users
+
+If you already run OPA for Kubernetes admission, cloud authorization, CI/CD, or service mesh, GOPAL gives you a policy library targeted at AI systems instead of infrastructure.
+
+The packages, conventions, and test patterns are idiomatic Rego — no DSL on top, no Python required to evaluate. You can:
+
+- pull individual frameworks (`international/eu_ai_act/v1/`, `industry_specific/aviation/v1/`) into a bundle
+- evaluate with `opa eval`, [Conftest](https://www.conftest.dev/), or your existing OPA server
+- pin to a major version (`v1/`) and review upgrades as PRs
+- compose GOPAL rules with your private `custom/` rules in the same evaluation
+- lint with [Regal](https://github.com/StyraInc/regal) — the same linter GOPAL itself runs in CI
+
+If you want a Python framework that handles input capture and PDF/Markdown report generation on top, see [AICertify](https://github.com/Principled-Evolution/aicertify).
+
+---
+
 ## What's Inside
 
 <p align="center">
@@ -164,6 +219,19 @@ gopal/
 
 ---
 
+## GOPAL vs AICertify
+
+| Need | Use |
+|---|---|
+| I want raw Rego policies | GOPAL |
+| I want to evaluate an AI app and generate reports | AICertify |
+| I want to plug policies into existing OPA tooling | GOPAL |
+| I want PDF/Markdown/JSON audit reports | AICertify |
+
+AICertify uses GOPAL underneath. Pick GOPAL if you already have an OPA workflow you want to extend with AI-specific rules. Pick AICertify if you want a Python framework that captures AI-application interactions and produces audit-ready evidence end-to-end.
+
+---
+
 ## Authoring Policies
 
 <p align="center">
@@ -206,6 +274,23 @@ Then a sibling `*_test.rego` covers the rule. CI enforces:
 
 The [helper_functions/](helper_functions/) library gives you `compose_report()`, `validate_required_fields()`, and `field_exists()` so reports come out in a uniform shape no matter who wrote the rule.
 
+See [`docs/tutorials/add-your-first-policy.md`](docs/tutorials/add-your-first-policy.md) for a walkthrough, and [`docs/coverage/`](docs/coverage/) for per-framework coverage matrices.
+
+---
+
+## Policy correctness
+
+GOPAL is not legal advice. The policies here are executable interpretations of public regulatory and governance requirements, written by engineers who care about getting them right.
+
+If you believe a rule misreads a regulation or misses an obligation, please open an issue with:
+
+- the regulation, section, or article in question
+- your interpretation
+- the input/output behavior you'd expect
+- any official guidance, regulator text, or precedent
+
+Policy-correctness disagreements are not security vulnerabilities — see [SECURITY.md](SECURITY.md) for the latter. They are exactly the kind of issue we want public so the community can review and improve the rules together.
+
 ---
 
 ## Custom Policies

diff --git a/docs/INDEX.md b/docs/INDEX.md
@@ -7,6 +7,8 @@ Organized along [Diátaxis](https://diataxis.fr/) lines.
 ## 🎓 Tutorials — your first GOPAL evaluation
 
 - [Quick Start in the README](../README.md#quick-start) — standalone `opa eval`, or via AICertify.
+- [Add your first GOPAL policy](tutorials/add-your-first-policy.md) — write a working policy + test + CI check in 20 minutes.
+- [Runnable examples](../examples/README.md) — `examples/` with input/output pairs for EU AI Act, NIST AI RMF, and customer-support LLM.
 - [Add a brand-new regulatory framework](../skills/add-framework/SKILL.md) (Claude Code skill) — bootstraps the directory tree, framework README, and first policy.
 - [FAQ](FAQ.md) — comprehensive Q&A on what GOPAL is, when to use it, and how to extend it.
 
@@ -19,6 +21,7 @@ Organized along [Diátaxis](https://diataxis.fr/) lines.
 
 ## 📚 Reference — look up specific names
 
+- [Policy coverage matrices](coverage/) — per-framework view of what's Implemented / Scaffold / Planned.
 - [Coverage table](../README.md#whats-inside) — every framework with its policy count.
 - [helper_functions/reporting.rego](../helper_functions/reporting.rego) — `compose_report()`, validators.
 - [helper_functions/validation.rego](../helper_functions/validation.rego) — `field_exists()`, `validate_required_fields()`.

diff --git a/docs/coverage/README.md b/docs/coverage/README.md
@@ -0,0 +1,35 @@
+# Policy coverage matrices
+
+This directory documents, per framework, **which obligations are encoded in GOPAL** and **which are not yet**.
+
+The matrices are deliberately honest. A policy is only marked **Implemented** when the Rego rule actually validates input fields against the regulation's requirement. Many directories ship a **Scaffold** that establishes the package path and a `default allow := false` placeholder — useful as a starting point for contributors, not yet enforceable.
+
+## Available matrices
+
+- [EU AI Act](eu-ai-act.md) — Regulation (EU) 2024/1689
+- [NIST AI RMF](nist-ai-rmf.md) — NIST Special Publication 1270 + AI 600-1
+
+## Coming soon
+
+- UK AI principles (pro-innovation framework)
+- India / DPDP Act
+- Brazil AI Governance Bill
+- ICAO Doc 10019 (aviation)
+- FERPA / COPPA (education)
+- Healthcare AI safety
+- BFS — fair lending, model risk
+
+If you want to help expand coverage for a framework, open an issue or send a PR. The matrices are the best place to start — they show contributors exactly which articles, controls, or sections are still open.
+
+## Reading a matrix
+
+Each row is one obligation, control, or article in the source regulation. Columns:
+
+| Column | Meaning |
+|---|---|
+| **Obligation** | The regulator's name for the requirement (article number, control ID, etc.) |
+| **GOPAL policy** | Path to the Rego package that encodes it |
+| **Status** | `Implemented` / `Scaffold` / `Planned` |
+| **Notes** | What the rule checks, or what's missing |
+
+`Implemented` rules are safe to run in CI and produce structured verdicts. `Scaffold` rules return placeholder denials — they exist so the package path is stable while the logic is fleshed out. `Planned` means there's no file yet.
diff --git a/docs/coverage/eu-ai-act.md b/docs/coverage/eu-ai-act.md
@@ -0,0 +1,83 @@
+# EU AI Act — coverage matrix
+
+Source: **Regulation (EU) 2024/1689** (the Artificial Intelligence Act).
+
+Policies live under [`international/eu_ai_act/v1/`](../../international/eu_ai_act/v1).
+
+Legend: ✅ **Implemented** — checks real input fields against the obligation. ⚠️ **Scaffold** — package exists, returns placeholder denial. 📋 **Planned** — not in repo yet.
+
+## Title II — Prohibited AI practices (Article 5)
+
+| Obligation | GOPAL policy | Status | Notes |
+|---|---|---|---|
+| Article 5(1)(a) — Manipulative techniques | [`prohibited_practices/manipulation`](../../international/eu_ai_act/v1/prohibited_practices/manipulation.rego) | ✅ | Detects deployment of subliminal / manipulative techniques |
+| Article 5(1)(a) — Emotion recognition (workplace/edu) | [`prohibited_practices/emotion_recognition`](../../international/eu_ai_act/v1/prohibited_practices/emotion_recognition.rego) | ✅ | Detects emotion-recognition systems in workplace/educational contexts |
+| Article 5(1)(b) — Vulnerability exploitation | [`prohibited_practices/vulnerability_exploitation`](../../international/eu_ai_act/v1/prohibited_practices/vulnerability_exploitation.rego) | ✅ | Detects exploitation of age/disability/social vulnerabilities |
+| Article 5(1)(c) — Social scoring | [`prohibited_practices/social_scoring`](../../international/eu_ai_act/v1/prohibited_practices/social_scoring.rego) | ✅ | Detects social-scoring systems leading to detrimental treatment |
+| Article 5(1)(d) — Criminal-offense profiling | [`prohibited_practices/criminal_profiling`](../../international/eu_ai_act/v1/prohibited_practices/criminal_profiling.rego) | ⚠️ | Package exists; logic placeholder |
+| Article 5(1)(e) — Untargeted facial-recognition scraping | [`prohibited_practices/facial_recognition_scraping`](../../international/eu_ai_act/v1/prohibited_practices/facial_recognition_scraping.rego) | ⚠️ | Package exists; logic placeholder |
+| Article 5(1)(b)+(g) — Biometric categorization | [`prohibited_practices/biometric_categorization`](../../international/eu_ai_act/v1/prohibited_practices/biometric_categorization.rego) | ⚠️ | Package exists; logic placeholder |
+| Article 5(1)(h) — Real-time remote biometric identification | [`prohibited_practices/biometric_identification`](../../international/eu_ai_act/v1/prohibited_practices/biometric_identification.rego) | ⚠️ | Package exists; logic placeholder |
+
+## Title III — High-risk AI systems (Articles 6 – 27)
+
+### Chapter 2 — Requirements for high-risk AI systems
+
+| Obligation | GOPAL policy | Status | Notes |
+|---|---|---|---|
+| Article 9 — Risk management system | [`risk_management/risk_management`](../../international/eu_ai_act/v1/risk_management/risk_management.rego) | ✅ | Checks documented risk-management process & residual risk acceptance |
+| Article 10 — Data and data governance | [`data_governance/data_quality`](../../international/eu_ai_act/v1/data_governance/data_quality.rego) | ⚠️ | Scaffold |
+| Article 10 — Training data | [`data_governance/training_data`](../../international/eu_ai_act/v1/data_governance/training_data.rego) | ⚠️ | Scaffold |
+| Article 11 — Technical documentation | [`documentation/technical_documentation`](../../international/eu_ai_act/v1/documentation/technical_documentation.rego) | ✅ | Checks `documentation.technical_documentation.completeness` |
+| Article 12 — Record-keeping (logging) | [`documentation/record_keeping`](../../international/eu_ai_act/v1/documentation/record_keeping.rego) | ⚠️ | Scaffold |
+| Article 12 — Automated logs | [`documentation/automated_logs`](../../international/eu_ai_act/v1/documentation/automated_logs.rego) | ⚠️ | Scaffold |
+| Article 13 — Transparency to deployers | [`transparency/transparency`](../../international/eu_ai_act/v1/transparency/transparency.rego) | ✅ | Checks documentation completeness + toxicity threshold |
+| Article 14 — Human oversight | [`human_oversight/human_oversight`](../../international/eu_ai_act/v1/human_oversight/human_oversight.rego) | ⚠️ | Scaffold |
+| Article 15 — Accuracy, robustness, cybersecurity | [`technical_robustness/robustness`](../../international/eu_ai_act/v1/technical_robustness/robustness.rego) | ⚠️ | Scaffold |
+| Article 15 — Fairness obligations | [`eu_fairness/eu_fairness`](../../international/eu_ai_act/v1/eu_fairness/eu_fairness.rego) | ✅ | Checks bias-metric thresholds and protected-class coverage |
+
+### Chapter 3 — Obligations of providers, deployers, importers, distributors
+
+| Obligation | GOPAL policy | Status | Notes |
+|---|---|---|---|
+| Article 16 + 17 — Provider obligations | [`obligations/provider_obligations`](../../international/eu_ai_act/v1/obligations/provider_obligations.rego) | ⚠️ | Scaffold |
+| Article 23 — Importer obligations | [`obligations/importer_obligations`](../../international/eu_ai_act/v1/obligations/importer_obligations.rego) | ⚠️ | Scaffold |
+| Article 24 — Distributor obligations | [`obligations/distributor_obligations`](../../international/eu_ai_act/v1/obligations/distributor_obligations.rego) | ⚠️ | Scaffold |
+| Article 26 — Deployer obligations | [`obligations/deployer_obligations`](../../international/eu_ai_act/v1/obligations/deployer_obligations.rego) | ⚠️ | Scaffold |
+
+### Chapter 5 — Conformity assessment and CE marking
+
+| Obligation | GOPAL policy | Status | Notes |
+|---|---|---|---|
+| Article 43 — Conformity assessment | [`compliance/conformity_assessment`](../../international/eu_ai_act/v1/compliance/conformity_assessment.rego) | ⚠️ | Scaffold |
+| Article 47 — EU declaration of conformity | [`compliance/declaration_conformity`](../../international/eu_ai_act/v1/compliance/declaration_conformity.rego) | ⚠️ | Scaffold |
+| Article 48 — CE marking | [`compliance/ce_marking`](../../international/eu_ai_act/v1/compliance/ce_marking.rego) | ⚠️ | Scaffold |
+| Article 49 — Registration in EU database | [`compliance/registration`](../../international/eu_ai_act/v1/compliance/registration.rego) | ⚠️ | Scaffold |
+
+## Title V — General-purpose AI models (Articles 51 – 56)
+
+| Obligation | GOPAL policy | Status | Notes |
+|---|---|---|---|
+| Article 53 — GPAI technical documentation | [`gpai/technical_documentation`](../../international/eu_ai_act/v1/gpai/technical_documentation.rego) | ⚠️ | Scaffold |
+| Article 53 — Downstream transparency | [`gpai/downstream_transparency`](../../international/eu_ai_act/v1/gpai/downstream_transparency.rego) | ⚠️ | Scaffold |
+| Article 51 — Systemic-risk classification | [`gpai/systemic_risk_classification`](../../international/eu_ai_act/v1/gpai/systemic_risk_classification.rego) | ⚠️ | Scaffold |
+| Article 52 — Transparency obligations for certain systems | [`transparency/transparency`](../../international/eu_ai_act/v1/transparency/transparency.rego) | ✅ | Shared with Article 13 |
+
+## Not yet covered (📋 Planned)
+
+| Obligation | Why it's open | Help wanted |
+|---|---|---|
+| Article 6 — High-risk classification rules | Needs a structured input schema mapping Annex I/III to system attributes | Yes |
+| Article 27 — Fundamental-rights impact assessment | Needs FRIA template + checklist input | Yes |
+| Article 50 — Transparency to natural persons (deepfakes etc.) | Needs use-case taxonomy and disclosure-evidence input | Yes |
+| Article 55 — Obligations for GPAI with systemic risk | Needs systemic-risk evaluation results input | Yes |
+| Article 72 — Post-market monitoring | Needs post-deployment metrics input | Yes |
+| Annex IV — Technical documentation contents | Currently aggregated into `technical_documentation`; could be split per-line | Maybe |
+
+## How to help
+
+1. **Promote a scaffold to implementation.** Pick a row marked ⚠️ Scaffold, read the corresponding article, and replace the placeholder logic with concrete field checks. See [`docs/tutorials/add-your-first-policy.md`](../tutorials/add-your-first-policy.md).
+2. **Open a 📋 Planned row.** Comment on the relevant issue (or open one) with your interpretation of the obligation and a proposed input schema before sending a PR.
+3. **Disagree with our coverage call?** Open an issue. We'd rather have the dispute in public than ship rules that misread the regulation.
+
+> ⚠️ Reminder: GOPAL is not legal advice. The matrix above is GOPAL's *engineering* interpretation of where each obligation maps. Use it as a starting point for your own compliance review, not a substitute for one.