diff --git a/README.md b/README.md
index fe7d8d9..0e5d629 100644
--- a/README.md
+++ b/README.md
@@ -59,10 +59,9 @@ Measured throughput, cold-start, bundle-size, validation, and explanation overhe
### Methodology and inspectability
-- Benchmark methodology and result contract: [`docs/benchmarks/methodology.md`](docs/benchmarks/methodology.md)
-- Explainability proof metadata and alt text: [`docs/benchmarks/assets/generated/explainability-trace-diagram.md`](docs/benchmarks/assets/generated/explainability-trace-diagram.md)
-- Visual proof system and publication guardrails: [`docs/benchmarks/visual-proof-system.md`](docs/benchmarks/visual-proof-system.md)
-- Playground README demo capture spec: [`docs/playground/readme-demo-capture.md`](docs/playground/readme-demo-capture.md)
+- Benchmark methodology (how each metric is measured): [`docs/benchmarks/methodology.md`](docs/benchmarks/methodology.md)
+- AI-rule safety (why AI-drafted rules need validation): [`docs/benchmarks/ai-rule-safety.md`](docs/benchmarks/ai-rule-safety.md)
+- Proof overview and explainability diagram: [`docs/benchmarks/`](docs/benchmarks/)
---
@@ -184,7 +183,7 @@ Available adoption assets:
- Runnable examples: [`examples/`](examples/) including n8n and LangGraph workflow automation recipes
- JSON Schemas, validation, and explain output: [`docs/schemas-validation-explainability.md`](docs/schemas-validation-explainability.md)
-- Benchmark methodology, visual proof, and playground capture specifications: [`docs/benchmarks/`](docs/benchmarks/) and [`docs/playground/readme-demo-capture.md`](docs/playground/readme-demo-capture.md)
+- Measured benchmarks, methodology, and AI-rule-safety proof: [`docs/benchmarks/`](docs/benchmarks/)
- Comparison and migration guides: [`docs/comparisons/`](docs/comparisons/) for choosing and migrating from json-rules-engine, JsonLogic, node-rules, and hand-written if/else
- AI-readable docs: [`docs/ai-coding-assistants.md`](docs/ai-coding-assistants.md), [`docs/public/llms.txt`](docs/public/llms.txt), [`docs/public/llms-full.txt`](docs/public/llms-full.txt), and [`docs/public/skills/neuron-js/SKILL.md`](docs/public/skills/neuron-js/SKILL.md)
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 689f787..f7494b0 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -44,16 +44,12 @@ export default defineConfig({
]
},
{
- text: 'Proof Assets',
+ text: 'Benchmarks & Proof',
items: [
- { text: 'Benchmarks & Visual Proof', link: '/benchmarks/' },
+ { text: 'Overview', link: '/benchmarks/' },
{ text: 'Benchmark Results', link: '/benchmarks/results' },
- { text: 'Benchmark Methodology', link: '/benchmarks/methodology' },
- { text: 'Visual Proof System', link: '/benchmarks/visual-proof-system' },
- { text: 'Benchmark Visual Pack', link: '/benchmarks/benchmark-visual-pack' },
- { text: 'Playground Capture Spec', link: '/playground/readme-demo-capture' },
- { text: 'Prompt Kit', link: '/benchmarks/prompt-kit' },
- { text: 'Asset Folder', link: '/benchmarks/assets/' }
+ { text: 'Methodology', link: '/benchmarks/methodology' },
+ { text: 'AI-Rule Safety', link: '/benchmarks/ai-rule-safety' }
]
},
{
diff --git a/docs/benchmarks/ai-rule-safety.md b/docs/benchmarks/ai-rule-safety.md
new file mode 100644
index 0000000..7c3e85d
--- /dev/null
+++ b/docs/benchmarks/ai-rule-safety.md
@@ -0,0 +1,49 @@
+# AI-rule safety
+
+LLMs are great at *drafting* JSON business rules — and that's exactly the risk. A
+plausible-looking rule can still encode the wrong field, the wrong threshold, or the wrong
+action. Neuron-JS exists so AI-drafted rules become **safe to run**: schema-validated,
+constrained to a developer-owned vocabulary, reviewable like code, and explainable after the
+fact.
+
+> AI drafts. Neuron-JS verifies.
+
+## 1. AI can draft rules
+
+A plausible JSON rule can still encode the wrong assumption, field, or action — it is not
+production-ready on its own.
+
+
+
+## 2. Validate before runtime
+
+Schema-first checks (`validateScript`) reject malformed scripts before they ever execute, and
+return the exact JSON path to fix.
+
+
+
+## 3. Constrain what can run
+
+A developer-owned registry defines the approved actions, conditions, parameters, and rules.
+Anything outside that vocabulary simply cannot execute — no arbitrary code.
+
+
+
+## 4. Review like code
+
+Generated rules are serializable data, so they go through the same governance as code: tests,
+owner approval, and rollback — never automatic AI approval.
+
+
+
+## 5. Then execute deterministically
+
+Synapse runs the approved rule path deterministically, and the explanation trace shows why the
+decision matched or failed — ready for audit, logs, or a support ticket.
+
+
+
+## In short
+
+`Validate → constrain → test → approve → execute → explain.` Deterministic workflow logic with
+auditability is the guardrail that makes AI-assisted business rules safe to ship.
diff --git a/docs/benchmarks/assets/README.md b/docs/benchmarks/assets/README.md
deleted file mode 100644
index 8f0f4c3..0000000
--- a/docs/benchmarks/assets/README.md
+++ /dev/null
@@ -1,68 +0,0 @@
-# NJS-GROWTH-07 benchmark asset folder
-
-Recommended folder for visual proof assets:
-
-```text
-docs/benchmarks/assets/
- README.md
- source-data/
- benchmark-results.example.json
- benchmark-results.schema.json
- prompts/
- benchmark-infographic.md
- explainability-trace-diagram.md
- playground-readme-gif-storyboard.md
- ai-rule-safety-carousel.md
- readme-proof-strip.md
- storyboard/
- playground-readme-gif.md
- ai-rule-safety-carousel.md
- generated/
- benchmark-chart-throughput.svg
- benchmark-chart-cold-start.svg
- benchmark-chart-bundle-size.svg
- benchmark-chart-validation-overhead.svg
- benchmark-chart-explanation-overhead.svg
- explainability-trace-diagram.svg
- readme-proof-strip.svg
-```
-
-## Folder rules
-
-- `source-data/` stores benchmark input data and schemas only. Generated assets must cite these files when they include measurements.
-- `prompts/` stores frozen prompts copied or split from `docs/benchmarks/prompt-kit.md` for repeatable generation. The benchmark chart prompt set lives at `prompts/benchmark-chart-prompts.md`; the methodology card prompt lives at `prompts/methodology-infographic.md`.
-- `storyboard/` stores GIF/clip scripts, frame lists, and capture notes.
-- `generated/` stores exported SVG/PNG/GIF/MP4 assets.
-
-## Data integrity rules
-
-- Do not place fabricated benchmark results in `source-data/`.
-- Example files must be named `.example.*` and must use obviously non-claiming values or schema-only structures.
-- Real benchmark files must include `node_version`, `package_version`, `commit_sha`, `warmup_iterations`, and `measured_iterations`.
-- Any generated benchmark chart must name its source data file in adjacent metadata or in the SVG metadata block.
-
-## Generated assets
-
-Current generated proof assets:
-
-- `generated/methodology-card.svg`: 16:9 methodology card explaining no-fabricated-benchmark rules without performance numbers.
-- `generated/explainability-trace-diagram.svg`: 16:9 SVG diagram showing business input -> schema validation -> registry -> rule evaluation -> match/fail trace -> deterministic decision.
-- `generated/explainability-trace-diagram.html`: browser preview wrapper with caption and alt text.
-- `generated/explainability-trace-diagram.md`: source grounding, caption, alt text, integrity notes, and export notes.
-
-## Accessibility rules
-
-Every final asset needs:
-
-- Alt text.
-- Source data link when metrics appear.
-- Color contrast check notes.
-- Export dimensions.
-- Creation date and generator/tool used.
-
-## README integration rule
-
-The README proof strip should not be merged into the README until either:
-
-1. it contains no benchmark numbers and is clearly a proof-structure asset; or
-2. it uses real benchmark output from the harness and cites the exact source data.
diff --git a/docs/benchmarks/assets/asset-manifest.md b/docs/benchmarks/assets/asset-manifest.md
deleted file mode 100644
index eec3fe1..0000000
--- a/docs/benchmarks/assets/asset-manifest.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Benchmark visual asset manifest
-
-Status: the five benchmark charts are generated from measured `actual_benchmark` output (`benchmarks/results/latest.actual.json`) by `benchmarks/charts/generate.ts`. See [benchmark results](../results.md). The prompts below remain as the design spec and regeneration reference.
-
-## Draft prompt assets
-
-| Asset | Path | Claim status | Source dependency |
-| --- | --- | --- | --- |
-| Throughput chart prompt | `prompts/benchmark-chart-prompts.md#throughput-comparison-chart` | No numeric claim | actual benchmark output required |
-| Cold-start chart prompt | `prompts/benchmark-chart-prompts.md#cold-start-comparison-chart` | No numeric claim | actual benchmark output required |
-| Bundle-size chart prompt | `prompts/benchmark-chart-prompts.md#bundle-size-comparison-chart` | No numeric claim | actual benchmark output required |
-| Validation-overhead chart prompt | `prompts/benchmark-chart-prompts.md#validation-overhead-chart` | No numeric claim | actual benchmark output required |
-| Explanation-overhead chart prompt | `prompts/benchmark-chart-prompts.md#explanation-overhead-chart` | No numeric claim | actual benchmark output required |
-| Methodology card prompt | `prompts/methodology-infographic.md` | Methodology only, no performance claim | `docs/benchmarks/methodology.md` |
-
-## Generated output paths
-
-Charts generated from measured benchmark output:
-
-- `generated/benchmark-chart-throughput.svg`
-- `generated/benchmark-chart-cold-start.svg`
-- `generated/benchmark-chart-bundle-size.svg`
-- `generated/benchmark-chart-validation-overhead.svg`
-- `generated/benchmark-chart-explanation-overhead.svg`
-
-Methodology-only (no performance numbers):
-
-- `generated/methodology-card.svg`
-
-AI-rule-safety carousel (qualitative, no performance numbers):
-
-- `generated/ai-rule-safety-carousel-1.svg` … `-5.svg`
-
-## Publication blocker
-
-Benchmark charts publish only from a source file that satisfies `result_kind: "actual_benchmark"`, `is_placeholder: false`, and `claims_allowed: true`. The committed charts were generated from such a file; regenerate with `yarn benchmark && yarn benchmark:charts` after any data change.
diff --git a/docs/benchmarks/assets/generated/ai-rule-safety-carousel.md b/docs/benchmarks/assets/generated/ai-rule-safety-carousel.md
deleted file mode 100644
index 22170f7..0000000
--- a/docs/benchmarks/assets/generated/ai-rule-safety-carousel.md
+++ /dev/null
@@ -1,46 +0,0 @@
-# AI-rule-safety carousel — asset metadata
-
-Generated proof asset for the NJS-GROWTH-07 AI-generated-rule safety carousel.
-
-- Asset files: `ai-rule-safety-carousel-1.svg` … `ai-rule-safety-carousel-5.svg`
-- Prompt/script source: [`../prompts/ai-rule-safety-carousel.md`](../prompts/ai-rule-safety-carousel.md)
-- Storyboard: [`../storyboard/ai-rule-safety-carousel.md`](../storyboard/ai-rule-safety-carousel.md)
-- Export dimensions: 1080 × 1350 (4:5 vertical), SVG vector source
-- Recommended surfaces: LinkedIn carousel, X image thread, GitHub discussion image set, docs proof-assets page
-- Created: 2026-06-23
-- Generator/tool: hand-authored SVG (same visual system as `explainability-trace-diagram.svg`)
-
-## Integrity
-
-Qualitative safety/governance content. No benchmark numbers, no performance or
-superiority claims, no fabricated metrics. Color system: cyan execution path,
-emerald validation/pass, violet trace/audit, amber LLM draft, rose blocked path,
-on a slate `#020617` background.
-
-## Slides and alt text
-
-### 1. AI can draft rules.
-
-
-
-### 2. Validate before runtime.
-
-
-
-### 3. Constrain what can run.
-
-
-
-### 4. Review like code.
-
-
-
-### 5. Then execute deterministically.
-
-
-
-## Accessibility
-
-- Every slide carries `` and `<desc>` for screen readers.
-- Text/background contrast uses light slate text (`#e5e7eb`/`#cbd5e1`) on dark `#020617`.
-- No information is conveyed by color alone; each colored marker has a text label.
diff --git a/docs/benchmarks/assets/generated/explainability-trace-diagram.html b/docs/benchmarks/assets/generated/explainability-trace-diagram.html
deleted file mode 100644
index 4d86745..0000000
--- a/docs/benchmarks/assets/generated/explainability-trace-diagram.html
+++ /dev/null
@@ -1,46 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <title>Neuron-JS explainability trace diagram
-
-
-
-
-
-
-
-
- Caption: Neuron-JS turns serializable business-rule JSON into deterministic decisions by validating inputs, constraining execution through a developer-owned registry, and exposing a match/fail explanation trace for review.
-
Source note: docs/schemas-validation-explainability.md and docs/benchmarks/visual-proof-system.md. No benchmark or performance claims are made.
-