Adds benchmark visuals, governance metadata, and model card

Improves documentation and project transparency by introducing
generated benchmark charts and an illustrative circadian dynamics GIF
for the README. Establishes ownership and governance metadata,
including a model card detailing evaluation metrics and limitations.
Supports reproducible results and clearer project governance for users
and contributors.

Author: OptimumAF

.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default owner for all files
+* @OptimumAF

CHANGELOG.md

@@ -25,13 +25,22 @@ for versioning even while in research-stage development.
 - Multi-seed benchmark runner:
   - `scripts/run_multiseed_resnet_benchmark.py`
   - JSON and CSV export support for reproducible cross-seed comparison.
+- README visual generation pipeline:
+  - `scripts/generate_readme_figures.py`
+  - generated PNG benchmark charts under `docs/figures/`
+  - illustrative circadian adaptation GIF (`docs/figures/circadian_sleep_dynamics.gif`)
+- Ownership and governance metadata:
+  - `.github/CODEOWNERS`
+  - `docs/model-card.md`
+  - `docs/figures/README.md`
 
 ### Changed
 
 - Repositioned repository messaging to Circadian Predictive Coding as the primary focus.
 - Updated `README.md` with:
   - circadian-first project framing
   - reproducible benchmark commands
+  - badges, mermaid circadian loop diagram, benchmark visuals, and results snapshot tables
   - governance and citation references
 - Updated `ARCHITECTURE.md` with clearer module boundaries and circadian-centric design intent.
 - Updated `CONTRIBUTING.md` with concrete contribution workflow and quality gates.

README.md

@@ -1,13 +1,39 @@
 # Circadian Predictive Coding
 
-Circadian Predictive Coding is a research-focused repository for biologically inspired neural learning with:
+[![CI](https://github.com/OptimumAF/Circadian-Predictive-Coding/actions/workflows/ci.yml/badge.svg)](https://github.com/OptimumAF/Circadian-Predictive-Coding/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![Latest Release](https://img.shields.io/github/v/release/OptimumAF/Circadian-Predictive-Coding)](https://github.com/OptimumAF/Circadian-Predictive-Coding/releases)
 
-- chemical-gated plasticity
-- sleep-phase structural adaptation (split/prune)
-- direct comparison against traditional backpropagation and traditional predictive coding
+Circadian Predictive Coding is a research-first repository focused on biologically inspired learning where models adapt their own structure over wake and sleep cycles.
+
+## Why This Repo
+
+This project is built around one central idea:
+
+- **Circadian Predictive Coding** should be compared rigorously against
+  - traditional backpropagation
+  - traditional predictive coding
+
+The baseline models stay in the repo as stable references, while circadian behavior is the primary innovation surface.
+
+## Circadian Loop
 
 The circadian model is the primary focus of this project. Backprop and predictive coding baselines are kept to ensure fair comparison and reproducible evaluation.
 
+```mermaid
+flowchart LR
+    A[Wake Training] --> B[Chemical Accumulation]
+    B --> C[Plasticity Gating]
+    C --> D{Sleep Trigger}
+    D -- No --> A
+    D -- Yes --> E[Sleep Consolidation]
+    E --> F[Split / Prune Adaptation]
+    F --> G[Replay + Homeostasis]
+    G --> H[Optional Rollback Guard]
+    H --> A
+```
+
 ## Core Idea
 
 The circadian algorithm models wake and sleep phases:
@@ -25,6 +51,36 @@ This lets model capacity adapt over time instead of staying fixed.
 - Function-preserving split behavior and guarded sleep rollback
 - Multi-seed benchmark runner with JSON/CSV output
 
+## Visual Results
+
+### Multi-seed CIFAR-100 Snapshot (3 seeds, subset benchmark)
+
+![Accuracy Chart](docs/figures/benchmark_accuracy.png)
+![Training Speed Chart](docs/figures/benchmark_train_speed.png)
+![Inference Latency Chart](docs/figures/benchmark_inference_latency_p95.png)
+
+### Circadian Dynamics (Illustrative)
+
+![Circadian Sleep Dynamics](docs/figures/circadian_sleep_dynamics.gif)
+
+## Results Snapshot
+
+### Multi-seed subset benchmark (`benchmark_multiseed_cifar100_summary.csv`)
+
+| Model | Accuracy Mean | Train SPS Mean | Inference P95 (ms) |
+|---|---:|---:|---:|
+| BackpropResNet50 | 0.6901 | 1775.3 | 17.34 |
+| PredictiveCodingResNet50 | 0.6810 | 1732.1 | 17.74 |
+| CircadianPredictiveCodingResNet50 | 0.6715 | 1643.6 | 18.71 |
+
+### Hard full CIFAR-100 run (single-seed, 48 epochs, 2026-02-27)
+
+| Model | Accuracy | Train SPS | Inference SPS | Notes |
+|---|---:|---:|---:|---|
+| BackpropResNet50 | 0.706 | 1350.7 | 4672.4 | fixed head |
+| PredictiveCodingResNet50 | 0.723 | 2093.4 | 4839.0 | fixed head |
+| CircadianPredictiveCodingResNet50 | 0.734 | 2059.9 | 4831.4 | hidden 384->394, splits=12, prunes=2, rollbacks=7 |
+
 ## Repository Layout
 
 ```text
@@ -39,13 +95,12 @@ tests/        # Unit/integration tests
 docs/
   adr/        # Architecture decision records
   modules/    # Module responsibility docs
+  figures/    # Generated and static figures for documentation
 scripts/      # Reproducible benchmark scripts
 ```
 
 ## Quickstart
 
-PowerShell:
-
 ```powershell
 python -m venv .venv
 .\.venv\Scripts\Activate.ps1
@@ -64,21 +119,15 @@ For NVIDIA GPUs (example CUDA wheels):
 python -m pip install --upgrade --force-reinstall torch torchvision --index-url https://download.pytorch.org/whl/cu128
 ```
 
-## Running Experiments
+## Main Commands
 
-Toy baseline comparison:
+Toy baseline:
 
 ```powershell
 python predictive_coding_experiment.py
 ```
 
-In-depth toy comparison (multi-seed, multi-noise):
-
-```powershell
-python predictive_coding_experiment.py --mode indepth --samples 400 --epochs 160 --noise-levels 0.6,0.8,1.0 --seed-list 3,7,11,19,23 --sleep-interval 40
-```
-
-ResNet-50 benchmark (all 3 models):
+ResNet benchmark (all 3 models):
 
 ```powershell
 python resnet50_benchmark.py --dataset-name cifar100 --classes 100 --dataset-train-subset-size 20000 --dataset-test-subset-size 5000 --epochs 12 --device cuda
@@ -90,19 +139,16 @@ Multi-seed benchmark export:
 python scripts/run_multiseed_resnet_benchmark.py --dataset-name cifar100 --seeds 7,13,29 --dataset-train-subset-size 20000 --dataset-test-subset-size 5000 --epochs 12 --device cuda --output-prefix benchmark_multiseed_cifar100
 ```
 
-## Reproducing The Current Strong Circadian Regime
-
-This command runs a harder full CIFAR-100 setup where circadian adaptation is active:
+Regenerate README charts:
 
 ```powershell
-python resnet50_benchmark.py --dataset-name cifar100 --classes 100 --dataset-train-subset-size 0 --dataset-test-subset-size 0 --epochs 48 --device cuda --target-accuracy -1 --backbone-weights imagenet --backprop-freeze-backbone --batch-size 64 --image-size 96 --eval-batches 2 --inference-batches 20 --warmup-batches 5 --circ-force-sleep --circ-sleep-interval 2 --circ-enable-sleep-rollback --circ-sleep-rollback-tolerance 0.001 --circ-sleep-rollback-metric cross_entropy --circ-sleep-rollback-eval-batches 2 --circ-min-hidden-dim 320 --circ-max-hidden-dim 768 --circ-prune-min-age-steps 1200 --circ-sleep-warmup-steps 10 --circ-adaptive-split-percentile 82 --circ-adaptive-prune-percentile 8 --circ-split-hysteresis-margin 0.01 --circ-prune-hysteresis-margin 0.02 --circ-max-split-per-sleep 1 --circ-max-prune-per-sleep 1 --circ-sleep-split-only-until-fraction 0.70 --circ-sleep-prune-only-after-fraction 0.97 --circ-sleep-max-change-fraction 0.01 --circ-split-noise-scale 0.002 --circ-homeostatic-downscale-factor 0.999 --circ-homeostasis-target-input-norm 1.2 --circ-homeostasis-target-output-norm 1.0 --circ-homeostasis-strength 0.25 --circ-lr 0.028 --circ-steps 14 --circ-inference-lr 0.12
+python scripts/generate_readme_figures.py --summary-csv benchmark_multiseed_cifar100_summary.csv --output-dir docs/figures
 ```
 
 ## Quality Commands
 
 ```powershell
 ruff check .
-ruff format .
 mypy src tests scripts
 pytest -q
 ```
@@ -117,6 +163,7 @@ pytest -q
 - Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
 - Governance: [GOVERNANCE.md](GOVERNANCE.md)
 - Support process: [SUPPORT.md](SUPPORT.md)
+- Model Card: [docs/model-card.md](docs/model-card.md)
 
 ## Citation
 

docs/figures/README.md

@@ -0,0 +1,20 @@
+# Figures
+
+This folder stores visual assets used by `README.md`.
+
+## Generated Artifacts
+
+- `benchmark_accuracy.png`
+- `benchmark_train_speed.png`
+- `benchmark_inference_latency_p95.png`
+- `circadian_sleep_dynamics.gif`
+
+## Regeneration
+
+Run:
+
+```powershell
+python scripts/generate_readme_figures.py --summary-csv benchmark_multiseed_cifar100_summary.csv --output-dir docs/figures
+```
+
+The GIF is illustrative and intended for communication in the README.

docs/figures/benchmark_accuracy.png

@@ -0,0 +1,57 @@
+# Model Card: Circadian Predictive Coding
+
+## Summary
+
+Circadian Predictive Coding is a predictive-coding-based learner with sleep-phase structural plasticity.
+It tracks per-neuron chemical usage, modulates plasticity during wake, and applies split/prune consolidation during sleep.
+
+## Intended Use
+
+- Research and educational experimentation with biologically inspired learning dynamics.
+- Controlled benchmarks against backpropagation and traditional predictive coding.
+
+## Not Intended For
+
+- Safety-critical production decisions.
+- Unreviewed deployment in medical, legal, or financial decision pipelines.
+
+## Model Family
+
+- Base: predictive coding with iterative hidden-state inference.
+- Extension: circadian dynamics:
+  - chemical accumulation and decay
+  - plasticity gating
+  - adaptive sleep triggers
+  - structural split/prune
+  - optional rollback and homeostatic controls
+
+## Training Data
+
+- Toy two-cluster synthetic dataset (NumPy experiments).
+- Synthetic and torchvision-backed vision datasets (ResNet benchmark workflow), including CIFAR-10/CIFAR-100.
+
+## Evaluation
+
+Primary comparison metrics:
+
+- Test accuracy
+- Cross-entropy / energy
+- Training throughput (`samples/s`)
+- Inference latency (`mean`, `p95`) and throughput
+- Circadian adaptation telemetry (splits, prunes, hidden dimension trajectory, rollbacks)
+
+## Known Limitations
+
+- Benchmark conclusions are sensitive to sleep hyperparameters.
+- Circadian adaptation can underperform if split/prune schedules are too aggressive.
+- Current implementation focuses on head-level circadian adaptation in ResNet benchmarks.
+
+## Ethical Considerations
+
+- No personal data is required by default benchmark workflows.
+- Public benchmark claims should include dataset, seeds, and configuration details for reproducibility.
+
+## Maintenance Status
+
+Active research repository; APIs and defaults may evolve.
+Use release tags for stable references in external projects.