Principled-Evolution · kmadan · Aug 30, 2026 · Aug 30, 2026
diff --git a/README.hi-IN.md b/README.hi-IN.md
@@ -21,10 +21,10 @@
   <a href="https://pypi.org/project/aicertify/"><img src="https://img.shields.io/pypi/v/aicertify?style=flat-square&color=blue" alt="PyPI"></a>
   <a href="https://github.com/Principled-Evolution/aicertify/actions/workflows/aicertify-ci.yaml"><img src="https://github.com/Principled-Evolution/aicertify/actions/workflows/aicertify-ci.yaml/badge.svg" alt="CI"></a>
   <a href="https://github.com/Principled-Evolution/aicertify/stargazers"><img src="https://img.shields.io/github/stars/Principled-Evolution/aicertify?style=flat-square" alt="Stars"></a>
-  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg?style=flat-square" alt="Python 3.12+"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12-blue.svg?style=flat-square" alt="Python 3.12"></a>
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square" alt="Apache 2.0"></a>
   <a href="https://www.openpolicyagent.org/ecosystem/entry/principled-evolution"><img src="https://img.shields.io/badge/built%20on-OPA-7D4698.svg?style=flat-square" alt="Built on OPA"></a>
-  <a href="https://github.com/Principled-Evolution/gopal"><img src="https://img.shields.io/badge/policies-85%20rego-2f9e44.svg?style=flat-square" alt="85 Rego Policies"></a>
+  <a href="https://github.com/Principled-Evolution/gopal"><img src="https://img.shields.io/badge/policies-92%20rego-2f9e44.svg?style=flat-square" alt="92 Rego Policies"></a>
   <a href="https://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome"></a>
 </p>
 

diff --git a/README.ja-JP.md b/README.ja-JP.md
@@ -21,10 +21,10 @@
   <a href="https://pypi.org/project/aicertify/"><img src="https://img.shields.io/pypi/v/aicertify?style=flat-square&color=blue" alt="PyPI"></a>
   <a href="https://github.com/Principled-Evolution/aicertify/actions/workflows/aicertify-ci.yaml"><img src="https://github.com/Principled-Evolution/aicertify/actions/workflows/aicertify-ci.yaml/badge.svg" alt="CI"></a>
   <a href="https://github.com/Principled-Evolution/aicertify/stargazers"><img src="https://img.shields.io/github/stars/Principled-Evolution/aicertify?style=flat-square" alt="Stars"></a>
-  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg?style=flat-square" alt="Python 3.12+"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12-blue.svg?style=flat-square" alt="Python 3.12"></a>
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square" alt="Apache 2.0"></a>
   <a href="https://www.openpolicyagent.org/ecosystem/entry/principled-evolution"><img src="https://img.shields.io/badge/built%20on-OPA-7D4698.svg?style=flat-square" alt="Built on OPA"></a>
-  <a href="https://github.com/Principled-Evolution/gopal"><img src="https://img.shields.io/badge/policies-85%20rego-2f9e44.svg?style=flat-square" alt="85 Rego Policies"></a>
+  <a href="https://github.com/Principled-Evolution/gopal"><img src="https://img.shields.io/badge/policies-92%20rego-2f9e44.svg?style=flat-square" alt="92 Rego Policies"></a>
   <a href="https://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome"></a>
 </p>
 

diff --git a/README.ko-KR.md b/README.ko-KR.md
@@ -21,10 +21,10 @@
   <a href="https://pypi.org/project/aicertify/"><img src="https://img.shields.io/pypi/v/aicertify?style=flat-square&color=blue" alt="PyPI"></a>
   <a href="https://github.com/Principled-Evolution/aicertify/actions/workflows/aicertify-ci.yaml"><img src="https://github.com/Principled-Evolution/aicertify/actions/workflows/aicertify-ci.yaml/badge.svg" alt="CI"></a>
   <a href="https://github.com/Principled-Evolution/aicertify/stargazers"><img src="https://img.shields.io/github/stars/Principled-Evolution/aicertify?style=flat-square" alt="Stars"></a>
-  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg?style=flat-square" alt="Python 3.12+"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12-blue.svg?style=flat-square" alt="Python 3.12"></a>
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square" alt="Apache 2.0"></a>
   <a href="https://www.openpolicyagent.org/ecosystem/entry/principled-evolution"><img src="https://img.shields.io/badge/built%20on-OPA-7D4698.svg?style=flat-square" alt="Built on OPA"></a>
-  <a href="https://github.com/Principled-Evolution/gopal"><img src="https://img.shields.io/badge/policies-85%20rego-2f9e44.svg?style=flat-square" alt="85 Rego Policies"></a>
+  <a href="https://github.com/Principled-Evolution/gopal"><img src="https://img.shields.io/badge/policies-92%20rego-2f9e44.svg?style=flat-square" alt="92 Rego Policies"></a>
   <a href="https://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="PRs Welcome"></a>
 </p>
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -21,10 +21,10 @@
   <a href="https://pypi.org/project/aicertify/"><img src="https://img.shields.io/pypi/v/aicertify?style=flat-square&color=blue" alt="PyPI"></a>
   <a href="https://github.com/Principled-Evolution/aicertify/actions/workflows/aicertify-ci.yaml"><img src="https://github.com/Principled-Evolution/aicertify/actions/workflows/aicertify-ci.yaml/badge.svg" alt="持续集成"></a>
   <a href="https://github.com/Principled-Evolution/aicertify/stargazers"><img src="https://img.shields.io/github/stars/Principled-Evolution/aicertify?style=flat-square" alt="Star 数"></a>
-  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-blue.svg?style=flat-square" alt="Python 3.12+"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12-blue.svg?style=flat-square" alt="Python 3.12"></a>
   <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square" alt="Apache 2.0 许可证"></a>
   <a href="https://www.openpolicyagent.org/ecosystem/entry/principled-evolution"><img src="https://img.shields.io/badge/built%20on-OPA-7D4698.svg?style=flat-square" alt="基于 OPA 构建"></a>
-  <a href="https://github.com/Principled-Evolution/gopal"><img src="https://img.shields.io/badge/policies-85%20rego-2f9e44.svg?style=flat-square" alt="85 条 Rego 策略"></a>
+  <a href="https://github.com/Principled-Evolution/gopal"><img src="https://img.shields.io/badge/policies-92%20rego-2f9e44.svg?style=flat-square" alt="92 条 Rego 策略"></a>
   <a href="https://makeapullrequest.com"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square" alt="欢迎提交 PR"></a>
 </p>
 

diff --git a/aicertify/opa_policies b/aicertify/opa_policies
diff --git a/diagrams/diagram1_hero_flow_dark.svg b/diagrams/diagram1_hero_flow_dark.svg
diff --git a/diagrams/diagram1_hero_flow_light.svg b/diagrams/diagram1_hero_flow_light.svg
diff --git a/diagrams/diagram2_architecture_dark.svg b/diagrams/diagram2_architecture_dark.svg
diff --git a/diagrams/diagram2_architecture_light.svg b/diagrams/diagram2_architecture_light.svg
diff --git a/diagrams/diagram3_regulatory_coverage_dark.svg b/diagrams/diagram3_regulatory_coverage_dark.svg
diff --git a/diagrams/diagram3_regulatory_coverage_light.svg b/diagrams/diagram3_regulatory_coverage_light.svg
diff --git a/diagrams/diagram5_report_anatomy_dark.svg b/diagrams/diagram5_report_anatomy_dark.svg
diff --git a/diagrams/diagram5_report_anatomy_light.svg b/diagrams/diagram5_report_anatomy_light.svg
diff --git a/docs/INDEX.md b/docs/INDEX.md
@@ -1,36 +1,38 @@
 # AICertify Documentation
 
-> **Looking for an overview?** Start with the [README](../README.md) — it covers value prop, quickstart, regulatory coverage, and a comparison vs alternatives.
+> **Looking for an overview?** Start with the [README](../README.md) — it covers the evaluation model, quickstart, regulatory coverage, evidence boundaries, and where AICertify fits.
 
 The documentation here is organized along [Diátaxis](https://diataxis.fr/) lines: tutorials get you running, how-tos solve specific problems, reference describes the API, explanation explores design.
 
-## 🎓 Tutorials — get from zero to a working compliance report
+## Tutorials
 
-- [Quickstart](../examples/quickstart.py) — clone, install, run, inspect the report. ~5 minutes.
+- [Quickstart](../examples/quickstart.py) — clone, install, run, and inspect the report.
 - [Sample contract](../examples/sample_contract.json) — the JSON shape a real contract takes.
-- [Examples README](../examples/README.md) — index of all shipped examples and their pre-generated outputs.
+- [Examples README](../examples/README.md) — index of the forkable application examples and their maintained expected reports.
 
-## 🛠️ How-To Guides — solve a specific problem
+## How-to guides
 
 - [Run a compliance check against a custom contract](../skills/evaluate-contract/SKILL.md) (Claude Code skill)
 - [Add coverage for a new regulation](../skills/draft-policy/SKILL.md) (Claude Code skill)
 - [Understand what a framework's policies enforce](../skills/explain-regulation/SKILL.md) (Claude Code skill)
 - [Generate a report in PDF / Markdown / JSON / HTML](../examples/quickstart.py) — see the `report_format` argument.
+- [Map existing tool outputs into GOPAL metrics](adapters.md) — adapters for Detoxify, model cards, Fairlearn, and Perspective.
+- [Write a custom evaluator](writing-an-evaluator.md) — metric declaration, registration, delivery, and tests.
 
-## 📚 Reference — look up specific names
+## Reference
 
 - [Python API](../aicertify/__init__.py) — the public surface re-exported from the package root.
 - [CLI](../aicertify/cli.py) — `python -m aicertify.cli` flags and behavior. See also [README#cli](../README.md#cli).
 - [Regulatory coverage table](../README.md#regulatory-coverage) — every framework with its policy count.
 - [pyproject.toml](../pyproject.toml) — metadata, dependencies, entry points.
 - [CHANGELOG](../CHANGELOG.md) — release history.
 
-## 💡 Explanation — understand the design
+## Explanation
 
-- [AGENTS.md](../AGENTS.md) — the architectural narrative and how AI coding agents (and humans) should work in the repo.
-- [Why policy-as-code?](../README.md#why-aicertify) — the differentiation argument.
+- [AGENTS.md](../AGENTS.md) — architecture, repository conventions, and guidance for AI coding agents and human contributors.
+- [Why AICertify](why-aicertify.md) — evidence model, reproducibility boundary, and the division of responsibility between AICertify, GOPAL, OPA, and evaluators.
 
-## 🤝 Contributing & community
+## Contributing and community
 
 - [CONTRIBUTING.md](../CONTRIBUTING.md)
 - [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)
+1 −1		README.md
+1 −1		docs/INDEX.md
+8 −8		docs/declarations.md
+1 −1		helper_functions/declarations.rego