Principled-Evolution · kmadan · May 14, 2026 · May 14, 2026 · May 14, 2026 · May 14, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -136,6 +136,15 @@ If Regal flags an issue, look it up in the [Regal rule catalog](https://docs.sty
 
 Each framework lives under `v1/`. When the upstream regulation changes materially, add `v2/` alongside — don't mutate `v1/` in place. See [COMPATIBILITY.md](COMPATIBILITY.md).
 
+## Diagrams and visual assets
+
+All README diagrams live in [`diagrams/`](diagrams/) as paired **light and dark SVGs**, embedded via `<picture>` for GitHub theme switching. The full design system (palette, type, shape language, naming, contribution flow) is documented in [`diagrams/STYLE.md`](diagrams/STYLE.md). Read it before adding or modifying any diagram.
+
+- **Edit existing diagrams in place** — they are hand-authored SVGs, not generated. Open the file, change it, validate with `python3 -c "import xml.etree.ElementTree as ET; ET.parse('<path>')"`.
+- **Do not reintroduce a matplotlib generator** — the previous `generate_diagrams.py` was deliberately removed. Hand-authored SVGs are the source of truth.
+- **New diagrams must ship both `_light.svg` and `_dark.svg` variants.** Use `<picture>` markup; verify GitHub theme switching by viewing the rendered README on both light and dark settings.
+- **Rego syntax-coloured text** in `diagram3_policy_anatomy` uses `<tspan>` with `xml:space="preserve"` on the parent — without that attribute Inkscape and some browsers normalise whitespace and keywords run into the next token.
+
 ## What NOT to do
 
 - Don't edit policies under `custom/` — that's a local-only space for downstream consumers.

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,15 +8,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- Centered HTML hero, ordered badge wall, three big-number value-prop cards, and 5 programmatically-generated marketing diagrams in the README (hero numbers, directory tree, policy anatomy, framework grid, evaluation flow).
-- `AGENTS.md` and `CLAUDE.md` — operational instructions for AI coding agents working in this repository. `GEMINI.md` refreshed to inherit from `AGENTS.md` while preserving the author's working principles.
-- `skills/` directory with 3 Claude Code skills: `draft-rego-policy`, `explain-framework`, `add-framework`. Each ships as a slash command once installed into `~/.claude/skills/`.
-- Comparison table vs generic OPA bundles and vendor governance SaaS in the README.
-- `diagrams/generate_diagrams.py` — reproducible matplotlib script that regenerates every marketing PNG.
+- **Hand-authored, theme-aware SVG diagrams** under [`diagrams/`](diagrams/) — paired `_light.svg` + `_dark.svg` for hero banner, hero numbers, directory tree, policy anatomy, and evaluation flow. Embedded via `<picture>` so GitHub light- and dark-theme readers each see the matching variant.
+- **Brand assets** — standalone `logo_{light,dark}.svg` (hexagon + `{}` curly braces, signalling policy-as-code), `og_card_{light,dark}.svg` + a 1200×630 `og_card.png` for GitHub Settings → Social preview.
+- **[`diagrams/STYLE.md`](diagrams/STYLE.md)** — design-system reference (palette, typography, shape language, light/dark pattern, contribution flow) shared with sister project AICertify.
+- **[`CONTRIBUTING.md`](CONTRIBUTING.md)** — policy-authoring conventions, local-checks recipe, PR review criteria, and a "adding a new framework" guide. Resolves the broken link the README had been carrying.
+- **[`SECURITY.md`](SECURITY.md)** — private vulnerability-disclosure flow at `security@principledevolution.ai`, 5-business-day acknowledgement, coordinated disclosure. Explicitly distinguishes security issues from policy-correctness disputes.
+- **`AGENTS.md`** — new "Diagrams and visual assets" section pointing future agents at the SVG system and explicitly retiring the matplotlib generator.
+- Previously (still in this Unreleased line): `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` operational instructions for AI coding agents; `skills/` directory with 3 Claude Code skills (`draft-rego-policy`, `explain-framework`, `add-framework`); comparison table vs generic OPA bundles and vendor governance SaaS in the README.
 
 ### Changed
+- **Top of README** — replaced the `<h1>GOPAL</h1>` + bold tagline with a hero banner SVG that bakes in the wordmark and value prop, tightening the top fold across all 5 language READMEs (en, zh-CN, ja-JP, ko-KR, hi-IN).
 - README rewritten for product-page clarity: hero numbers, then quick start, then differentiation, then directory map.
 
+### Removed
+- **`diagrams/generate_diagrams.py`** — matplotlib generator retired. Hand-authored SVGs are now the source of truth; see [`diagrams/STYLE.md`](diagrams/STYLE.md) for how to add new ones.
+- **`diagram4_framework_grid.png`** — the markdown comparison table directly below it does the same job; the embedded image was redundant.
+
 ## [1.0.0] — 2025-07
 
 ### Added

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,87 @@
+# Contributing to GOPAL
+
+Thanks for considering a contribution. GOPAL is an open, community-curated library of [OPA](https://www.openpolicyagent.org/) Rego policies encoding AI-governance requirements; the more eyes on each rule, the better the policies get.
+
+## What we welcome
+
+- **New policies** for an existing framework (e.g. an additional EU AI Act article)
+- **New frameworks** (e.g. UK AI Principles, California SB-1047 successor, MAS banking AI guidance)
+- **New industry verticals** (e.g. media, energy, defence)
+- **Fixes** for bugs in existing policy logic
+- **Tests** — every policy should have a sibling `*_test.rego`. Missing tests on existing policies are open invitations.
+- **Translations** — the README ships in 5 languages. Native-speaker review of any of them is gold.
+- **Documentation** improvements (CONTRIBUTING, README, AGENTS, STYLE)
+
+## Before you open a PR
+
+1. **Open or check an issue first.** For new frameworks or larger additions, a quick "I'm planning to add X" comment avoids duplicate work.
+2. **Run the same checks CI runs.** See [Development](#development) below.
+3. **Match the existing policy shape.** Every policy file follows the same structure (package, imports, METADATA, default deny, allow rule, report). See [diagrams/diagram3_policy_anatomy_light.svg](diagrams/diagram3_policy_anatomy_light.svg) and any existing `.rego` for the canonical pattern.
+4. **Add a test sibling.** A new `foo.rego` needs a `foo_test.rego` covering both allow and deny cases.
+5. **Update [CHANGELOG.md](CHANGELOG.md)** under `[Unreleased]` with a one-line entry describing your change.
+
+## Development
+
+```bash
+# One-time setup
+pip install pre-commit
+curl -L -o opa https://openpolicyagent.org/downloads/latest/opa_linux_amd64 \
+  && chmod +x opa && sudo mv opa /usr/local/bin/
+curl -L -o regal https://github.com/StyraInc/regal/releases/latest/download/regal_Linux_x86_64 \
+  && chmod +x regal && sudo mv regal /usr/local/bin/
+pre-commit install
+
+# Run the checks CI runs
+opa check --ignore custom/ .
+regal lint --ignore-files custom/ .
+
+# Run tests for a specific package
+opa test international/eu_ai_act/v1/
+```
+
+If `opa check` fails it usually means a typo in a package path or an undeclared rule. If `regal lint` fails, run with `--format pretty` for human-readable advice on the issue.
+
+## Policy authoring conventions
+
+- **Package path mirrors the directory.** `international/eu_ai_act/v1/transparency.rego` declares `package international.eu_ai_act.v1.transparency`.
+- **Default deny.** Every policy starts with `default allow := false` so a missing rule produces a safe (deny) result, never an accidental allow.
+- **Metadata comments.** Use `# METADATA` followed by `# title:` and `# description:` so the rule is human-readable in audit reports.
+- **Report composition.** Use `data.helper_functions.reporting.compose_report(...)` to produce the standardized output shape — don't roll your own report dict. The helper guarantees the field names auditors expect.
+- **Versioning.** New frameworks go under `<framework>/v1/`. When a regulation amends, the old `v1/` stays put and a new `v2/` ships alongside. See [COMPATIBILITY.md](COMPATIBILITY.md).
+- **Reference data needed?** Add it as a constant inside the policy or under a sibling `_data.rego`. Avoid runtime dependencies on external services.
+
+## Adding a new framework
+
+The fastest path:
+
+1. Decide where it goes: `international/`, `industry_specific/`, `global/`, or `operational/`.
+2. `mkdir <category>/<framework>/v1/`
+3. Drop in a first policy that follows the standard shape. The [`draft-rego-policy`](skills/draft-rego-policy/SKILL.md) skill scaffolds this for you under Claude Code.
+4. Add a test sibling.
+5. Update the README count + add a row under "What's Inside".
+6. Open a PR.
+
+## PR review
+
+PRs are reviewed for:
+
+1. **Correctness** — does the policy logic accurately encode the regulation?
+2. **Test coverage** — does the test cover both allow and deny? Edge cases?
+3. **Style** — `opa check` + `regal lint` clean? Matches existing patterns?
+4. **Scope** — single concern per PR, easier to revert.
+
+We aim to respond within 5 business days. Larger framework additions may take longer if the regulator's text needs verification.
+
+## Custom policies
+
+The `custom/` directory is `.gitignore`d and CI-skipped — that's where your organization's proprietary rules go. They evaluate alongside the public set without ever being pushed to this repo. See the [README's Custom Policies section](README.md#custom-policies).
+
+## Community
+
+- **Questions** — open a [Discussion](https://github.com/Principled-Evolution/gopal/discussions) or comment on the relevant issue.
+- **Security disclosures** — see [SECURITY.md](SECURITY.md). Do not file public issues for vulnerabilities.
+- **Code of conduct** — be kind, assume good faith, focus on the work.
+
+## License
+
+By contributing, you agree your contributions will be licensed under the [Apache License 2.0](LICENSE), the same license as GOPAL itself.
diff --git a/README.hi-IN.md b/README.hi-IN.md
@@ -1,4 +1,9 @@
-<h1 align="center">GOPAL</h1>
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/hero_banner_dark.svg">
+    <img src="diagrams/hero_banner_light.svg" alt="GOPAL — The Rego policy library for AI compliance" width="100%">
+  </picture>
+</div>
 
 <p align="center">
   <a href="README.md">English</a> |
@@ -8,10 +13,6 @@
   <strong>हिन्दी</strong>
 </p>
 
-<p align="center">
-  <strong>AI कंप्लायंस के लिए Rego पॉलिसी लाइब्रेरी।</strong>
-</p>
-
 <p align="center">
   <em>94 पॉलिसीज़। 15+ रेगुलेटरी फ्रेमवर्क्स। 5 इंडस्ट्री वर्टिकल्स। Policy-as-code जिसे आपका ऑडिटर पढ़ सकता है।</em>
 </p>
@@ -34,13 +35,23 @@
 
 इन्हें अपने AI सिस्टम के metadata, model cards, या मूल्यांकन परिणामों के विरुद्ध चलाइए — और एक संरचित, मशीन-रीडेबल कंप्लायंस वर्डिक्ट प्राप्त कीजिए जिसे आप CI, ऑडिट लॉग, या रेगुलेटर सबमिशन में डाल सकते हैं।
 
-<p align="center"><img src="diagrams/diagram1_hero_numbers.png" alt="GOPAL — 94 पॉलिसीज़, 15+ फ्रेमवर्क्स, 5 वर्टिकल्स" width="85%" /></p>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram1_hero_numbers_dark.svg">
+    <img src="diagrams/diagram1_hero_numbers_light.svg" alt="GOPAL कवरेज: 94 पॉलिसीज़, इंटरनेशनल स्टैंडर्ड्स, एविएशन, इंडस्ट्री वर्टिकल्स, और क्रॉस-कटिंग सिद्धांत" width="85%" />
+  </picture>
+</p>
 
 ---
 
 ## Quick Start
 
-<p align="center"><img src="diagrams/diagram5_evaluation_flow.png" alt="GOPAL मूल्यांकन कैसे काम करता है — इनपुट JSON, OPA इंजन, पॉलिसी, वर्डिक्ट" width="85%" /></p>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram5_evaluation_flow_dark.svg">
+    <img src="diagrams/diagram5_evaluation_flow_light.svg" alt="GOPAL मूल्यांकन कैसे काम करता है — इनपुट JSON, Rego पॉलिसी, OPA मूल्यांकन, वर्डिक्ट" width="85%" />
+  </picture>
+</p>
 
 ### OPA CLI के साथ स्टैंडअलोन
 
@@ -90,7 +101,12 @@ GOPAL तीन आयामों में अलग है:
 
 ## अंदर क्या है
 
-<p align="center"><img src="diagrams/diagram2_directory_tree.png" alt="GOPAL डायरेक्टरी लेआउट — 5 शीर्ष-स्तरीय शाखाएँ, क्षेत्राधिकार और वर्टिकल के अनुसार व्यवस्थित पॉलिसीज़" width="85%" /></p>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram2_directory_tree_dark.svg">
+    <img src="diagrams/diagram2_directory_tree_light.svg" alt="GOPAL डायरेक्टरी लेआउट — 4 शीर्ष-स्तरीय शाखाएँ, क्षेत्राधिकार और वर्टिकल के अनुसार व्यवस्थित पॉलिसीज़" width="85%" />
+  </picture>
+</p>
 
 ```
 gopal/
@@ -133,8 +149,6 @@ gopal/
 
 ## तुलना
 
-<p align="center"><img src="diagrams/diagram4_framework_grid.png" alt="GOPAL जिन फ्रेमवर्क्स को कवर करता है — EU AI Act, NIST, FAA, EASA, RTCA और अधिक" width="85%" /></p>
-
 | | GOPAL | जेनेरिक OPA बंडल | वेंडर गवर्नेंस SaaS |
 |---|---|---|---|
 | विशेष रूप से AI सिस्टम्स को लक्ष्य करता है | ✅ | ❌ | ✅ |
@@ -152,7 +166,12 @@ gopal/
 
 ## पॉलिसीज़ लिखना
 
-<p align="center"><img src="diagrams/diagram3_policy_anatomy.png" alt="एक GOPAL पॉलिसी की संरचना — package path, imports, metadata, default deny, allow rule, report" width="85%" /></p>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram3_policy_anatomy_dark.svg">
+    <img src="diagrams/diagram3_policy_anatomy_light.svg" alt="एक GOPAL पॉलिसी की संरचना — package path, imports, metadata, default deny, allow rule, report" width="85%" />
+  </picture>
+</p>
 
 हर पॉलिसी एक ही आकार का अनुसरण करती है:
 

diff --git a/README.ja-JP.md b/README.ja-JP.md
@@ -1,4 +1,9 @@
-<h1 align="center">GOPAL</h1>
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/hero_banner_dark.svg">
+    <img src="diagrams/hero_banner_light.svg" alt="GOPAL — The Rego policy library for AI compliance" width="100%">
+  </picture>
+</div>
 
 <p align="center">
   <a href="README.md">English</a> |
@@ -8,10 +13,6 @@
   <a href="README.hi-IN.md">हिन्दी</a>
 </p>
 
-<p align="center">
-  <strong>AI コンプライアンスのための Rego ポリシーライブラリ。</strong>
-</p>
-
 <p align="center">
   <em>94 ポリシー。15 以上の規制フレームワーク。5 つの業種別領域。監査人が読めるポリシー・アズ・コード。</em>
 </p>
@@ -34,13 +35,23 @@
 
 AI システムのメタデータ、モデルカード、評価結果に対してこれらのポリシーを実行すると、構造化された機械可読のコンプライアンス判定が得られます。CI、監査ログ、規制当局への提出資料にそのまま組み込めます。
 
-<p align="center"><img src="diagrams/diagram1_hero_numbers.png" alt="GOPAL — 94 ポリシー、15 以上のフレームワーク、5 つの業種" width="85%" /></p>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram1_hero_numbers_dark.svg">
+    <img src="diagrams/diagram1_hero_numbers_light.svg" alt="GOPAL のカバレッジ: 94 ポリシー、国際規格、航空、業種別、共通原則の 4 カテゴリ" width="85%" />
+  </picture>
+</p>
 
 ---
 
 ## クイックスタート
 
-<p align="center"><img src="diagrams/diagram5_evaluation_flow.png" alt="GOPAL の評価フロー — 入力 JSON、OPA エンジン、ポリシー、判定" width="85%" /></p>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram5_evaluation_flow_dark.svg">
+    <img src="diagrams/diagram5_evaluation_flow_light.svg" alt="GOPAL の評価フロー — 入力 JSON、Rego ポリシー、OPA 評価、判定" width="85%" />
+  </picture>
+</p>
 
 ### OPA CLI で単体利用する
 
@@ -90,7 +101,12 @@ GOPAL は次の 3 点で異なります。
 
 ## 同梱内容
 
-<p align="center"><img src="diagrams/diagram2_directory_tree.png" alt="GOPAL のディレクトリ構成 — 5 つのトップレベル分岐、管轄区域と業種ごとに整理されたポリシー" width="85%" /></p>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram2_directory_tree_dark.svg">
+    <img src="diagrams/diagram2_directory_tree_light.svg" alt="GOPAL のディレクトリ構成 — 4 つのトップレベル分岐、管轄区域と業種ごとに整理されたポリシー" width="85%" />
+  </picture>
+</p>
 
 ```
 gopal/
@@ -133,8 +149,6 @@ gopal/
 
 ## 比較
 
-<p align="center"><img src="diagrams/diagram4_framework_grid.png" alt="GOPAL がカバーするフレームワーク — EU AI Act、NIST、FAA、EASA、RTCA など" width="85%" /></p>
-
 | | GOPAL | 汎用 OPA バンドル | ベンダー製ガバナンス SaaS |
 |---|---|---|---|
 | AI システムを明確に対象 | ✅ | ❌ | ✅ |
@@ -152,7 +166,12 @@ gopal/
 
 ## ポリシーの記述
 
-<p align="center"><img src="diagrams/diagram3_policy_anatomy.png" alt="GOPAL ポリシーの構造 — パッケージパス、import、メタデータ、default deny、allow ルール、レポート" width="85%" /></p>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="diagrams/diagram3_policy_anatomy_dark.svg">
+    <img src="diagrams/diagram3_policy_anatomy_light.svg" alt="GOPAL ポリシーの構造 — パッケージパス、import、メタデータ、default deny、allow ルール、レポート" width="85%" />
+  </picture>
+</p>
 
 すべてのポリシーは同じ構造に従います。