chore: prepare CacheVis-RV public showcase release

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,60 @@
+name: Bug report
+description: Report a reproducible CacheVis-RV problem using sanitized information.
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping improve CacheVis-RV. Remove tokens, passwords, private paths, and personal information before submitting.
+  - type: input
+    id: environment
+    attributes:
+      label: Environment
+      description: Windows version, Python version, and PySide6 version.
+      placeholder: Windows 11, Python 3.12.x, PySide6 6.x
+    validations:
+      required: true
+  - type: dropdown
+    id: lab
+    attributes:
+      label: Affected area
+      options:
+        - Platform shell / navigation
+        - Address Explorer
+        - Miss Type Lab
+        - Locality Lab
+        - Policy Lab
+        - Performance Lab
+        - Write Policy Lab
+        - Single Experiment
+        - Compare Experiment
+        - CLI / reports
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Reproduction steps
+      description: Use synthetic inputs and remove local absolute paths.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: checkboxes
+    id: sanitized
+    attributes:
+      label: Data safety
+      options:
+        - label: I removed tokens, passwords, private paths, personal information, and confidential traces.
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security guidance
+    url: https://github.com/Yucheng-art/CacheVis-RV/blob/main/SECURITY.md
+    about: Read this before reporting a concern; never disclose secrets or personal data.

.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+    branches: [main, "release/**"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  unittest:
+    runs-on: windows-latest
+    timeout-minutes: 15
+    env:
+      QT_QPA_PLATFORM: offscreen
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install dependencies
+        run: python -m pip install -r requirements.txt
+      - name: Run 720-test regression suite
+        run: python -B -m unittest discover -s tests -v

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 3.0.0 — 2026-08-07
+
+- Present eight available learning and classic experiment labs.
+- Document the 720-test Windows verification baseline.
+- Add bilingual public-facing project documentation and real application captures.
+- Add repository-relative launch/test helpers and Windows CI.
+- Add copyright, third-party, security, and issue-reporting safeguards.

COPYRIGHT.md

@@ -0,0 +1,14 @@
+# Copyright and permitted viewing
+
+Copyright © 2026 Yucheng Xu. All rights reserved.
+
+This repository is made available for portfolio review, educational evaluation,
+and demonstration. It is source-available; it is not offered under an
+open-source license.
+
+Unless Yucheng Xu gives prior written permission, no permission is granted to
+copy, modify, redistribute, sublicense, use commercially, or distribute
+derivative works from this repository.
+
+Third-party software used by this project remains subject to its own license
+terms. See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

README.md

@@ -1,57 +1,175 @@
-# CacheVis-RV V3
+# CacheVis-RV
 
-CacheVis-RV V3 是面向计算机组成与 RISC-V Cache 教学的多实验室交互式可视化平台。当前应用身份为 `CacheVis-RV V3.0`，M0–M5 计划内功能里程碑已经完成。
+An interactive desktop platform for learning cache mapping, miss behavior,
+locality, replacement policies, AMAT, and write policies.
 
-## 版本定位
+Built with Python and PySide6 for computer architecture education and visual
+experimentation.
 
-- V1：软件著作权归档版，仅作只读参考。
-- V2：稳定 Address Visualizer 版，仅作只读参考。
-- V3：采用 Sidebar、Home、Lab Registry 与 `QStackedWidget` 的多 Lab 平台版。
+[![Tests](https://github.com/Yucheng-art/CacheVis-RV/actions/workflows/tests.yml/badge.svg)](https://github.com/Yucheng-art/CacheVis-RV/actions/workflows/tests.yml)
+![Labs](https://img.shields.io/badge/labs-8_available-2563eb)
+![Tests](https://img.shields.io/badge/tests-720_passing-15803d)
+![Platform](https://img.shields.io/badge/tested-Windows_10%2F11-0f172a)
+![Stack](https://img.shields.io/badge/Python-PySide6-7c3aed)
+![Usage](https://img.shields.io/badge/source--available-all_rights_reserved-9f1239)
 
-## 当前可用功能
+[中文说明](README.zh-CN.md)
 
-平台共有 8 个 Available Lab，Coming Soon 为 0。
+![CacheVis-RV Home showing eight available labs](docs/assets/home-overview.webp)
 
-Learn：
+## Why CacheVis-RV
 
-1. Address Explorer
-2. Miss Type Lab
-3. Locality Lab
-4. Policy Lab
-5. Performance Lab
-6. Write Policy Lab
+Cache behavior is easier to understand when addresses, cache lines, evidence,
+and performance consequences are visible together. CacheVis-RV turns abstract
+rules into guided, repeatable experiments while keeping the underlying models
+deterministic and testable.
 
-Classic Tools：
+## What you can learn
 
-7. Single Experiment
-8. Compare Experiment
+- How tag, index, and offset bits map an address into a cache.
+- Why misses are compulsory, conflict, or capacity misses under the strict 3C model.
+- How temporal and spatial locality change cache behavior.
+- Where LRU, FIFO, and deterministic Random replacement decisions diverge.
+- Why hit rate alone does not determine AMAT or total memory cost.
+- How write-through/write-back and allocation choices affect dirty state and traffic.
 
-Write Policy Lab 同步比较 Write-Through / Write-Back 与 Write-Allocate / No-Write-Allocate 四种组合，展示 dirty line、dirty eviction，以及 block fill、immediate store、bypass 和 dirty write-back 的教学流量。页面明确区分 runtime traffic 与 final dirty drain；查看历史 evidence 不会回滚当前 Cache、统计或运行位置。
+## Eight labs
 
-平台页面按需创建并缓存，切换页面不会丢失已创建 Lab 的状态。当前回归基线为 720 项 `unittest` 全部通过、无 skip；Qt offscreen smoke、真实 GUI 入口启动、七个 Write Policy preset GUI smoke 和用户人工视觉验收均已通过。
+| Group | Lab | Focus |
+| --- | --- | --- |
+| Learn | Address Explorer | Address splitting, mapping, cache contents, and timeline |
+| Learn | Miss Type Lab | Compulsory, conflict, and capacity evidence |
+| Learn | Locality Lab | Temporal/spatial locality and block reuse |
+| Learn | Policy Lab | LRU, FIFO, and deterministic Random comparison |
+| Learn | Performance Lab | AMAT, timing assumptions, sweeps, and trade-offs |
+| Learn | Write Policy Lab | Write propagation, allocation, dirty eviction, and traffic |
+| Classic Tools | Single Experiment | Configurable trace simulation and report export |
+| Classic Tools | Compare Experiment | Side-by-side cache parameter comparison |
 
-Write Policy Lab 不模拟 store buffer、write combining、coherence、memory consistency、实际 L2、pipeline CPI、energy model、动画或专用报告导出。当前 trace 的结果只适用于给定 Cache 配置和流量假设，不代表任一策略普遍最优。
+All eight labs are available. Pages are created lazily and cached so navigation
+preserves an experiment's state.
 
-## 文档
+## Visual tour
 
-- [产品与技术架构](docs/V3_PRODUCT_AND_TECH_ARCHITECTURE.md)
-- [M0 平台外壳总结](docs/V3_M0_PLATFORM_SHELL_SUMMARY.md)
-- [M0 Smoke Checklist](docs/V3_M0_SMOKE_CHECKLIST.md)
-- [M1 Miss Type Lab 总结](docs/V3_M1_MISS_TYPE_LAB_SUMMARY.md)
-- [M1 Miss Type Lab Smoke Checklist](docs/V3_M1_MISS_TYPE_LAB_SMOKE_CHECKLIST.md)
-- [M2 Locality Lab 总结](docs/V3_M2_LOCALITY_LAB_SUMMARY.md)
-- [M2 Locality Lab Smoke Checklist](docs/V3_M2_LOCALITY_LAB_SMOKE_CHECKLIST.md)
-- [M3 Policy Lab 总结](docs/V3_M3_POLICY_LAB_SUMMARY.md)
-- [M3 Policy Lab Smoke Checklist](docs/V3_M3_POLICY_LAB_SMOKE_CHECKLIST.md)
-- [M4 Performance Lab 总结](docs/V3_M4_PERFORMANCE_LAB_SUMMARY.md)
-- [M4 Performance Lab Smoke Checklist](docs/V3_M4_PERFORMANCE_LAB_SMOKE_CHECKLIST.md)
-- [M5 Write Policy Lab 总结](docs/V3_M5_WRITE_POLICY_LAB_SUMMARY.md)
-- [M5 Write Policy Lab Smoke Checklist](docs/V3_M5_WRITE_POLICY_LAB_SMOKE_CHECKLIST.md)
-- [项目交接上下文](docs/PROJECT_HANDOFF_CONTEXT.md)
-- [V2 继承计划](docs/V2_INHERITANCE_PLAN.md)
-- [路线图](docs/ROADMAP.md)
-- [决策记录](docs/DECISIONS.md)
+### Miss Type Lab — strict 3C evidence
 
-## 仓库约束
+![Miss Type Lab showing 3C evidence](docs/assets/miss-type-lab.webp)
 
-V1/V2 始终只读。不得上传 `Cache*.pdf`、环境目录、缓存或构建输出；未经明确许可不得提交、推送、创建 tag 或 PR。
+### Policy Lab — LRU, FIFO, and Random side by side
+
+![Policy Lab replacement comparison](docs/assets/policy-lab.webp)
+
+### Performance Lab — hit rate is not AMAT
+
+![Performance Lab AMAT sweep](docs/assets/performance-lab.webp)
+
+### Write Policy Lab — four synchronized policy lanes
+
+![Write Policy Lab showing dirty state and traffic](docs/assets/write-policy-lab.webp)
+
+## Quick start
+
+Officially verified on Windows 10 and Windows 11. Other platforms have not yet
+completed formal verification.
+
+```powershell
+git clone https://github.com/Yucheng-art/CacheVis-RV.git
+cd CacheVis-RV
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install --upgrade pip
+.\.venv\Scripts\python.exe -m pip install -r requirements.txt
+.\.venv\Scripts\python.exe -B .\src\main.py --gui
+```
+
+After setup, the repository-relative helpers are also available:
+
+```powershell
+.\scripts\run_gui.ps1
+.\scripts\run_tests.ps1
+```
+
+## Example experiments
+
+- Use Address Explorer to follow `0, 4, 8, 0` one step at a time.
+- Run the three Miss Type presets and inspect the actual-cache/reference-cache evidence.
+- Contrast row-major and column-major matrix access in Locality Lab.
+- Find the first divergence among LRU, FIFO, and Random in Policy Lab.
+- Run **Hit Rate Is Not AMAT** and compare timing assumptions in Performance Lab.
+- Compare all four write-policy lanes, then separate runtime traffic from final dirty drain.
+
+## Architecture
+
+The platform shell owns navigation and lazy page creation. Each teaching lab has
+its own controller, immutable page state/view models, and PySide6 widget tree.
+Shared cache behavior lives in a GUI-free core package. Compatibility facades
+keep the established flat imports working for existing callers.
+
+```text
+src/main.py
+└── cachevis_rv/
+    ├── core/          cache configuration, lines, simulator, policies, statistics
+    ├── experiments/   reusable runners, parsing, reporting, and services
+    ├── gui/           platform shell, registry, Home, sidebar, and theme
+    └── labs/          one independent package per lab
+```
+
+## Verification
+
+- 720 `unittest` tests pass with no skips.
+- Windows clean-environment installation and Quick Start are verified.
+- Qt offscreen creation/navigation smoke tests pass.
+- The real GUI entry reaches the Qt event loop without a traceback.
+- Core, controller, view-model, registry, parser, invariants, and platform boundaries are tested.
+
+Run the same suite locally:
+
+```powershell
+.\.venv\Scripts\python.exe -B -m unittest discover -s tests -v
+```
+
+## Project structure
+
+```text
+.github/             Windows CI and issue forms
+docs/                architecture, milestone notes, checklists, and screenshots
+scripts/             repository-relative PowerShell launchers
+src/                 application, core, experiments, GUI, and lab packages
+tests/               unittest regression and boundary tests
+```
+
+## Supported scope
+
+CacheVis-RV is an educational, deterministic cache-learning platform. It covers
+address mapping, 3C miss classification, locality evidence, replacement-policy
+comparison, analytical performance modeling, and write-policy traffic under the
+explicit assumptions displayed by each lab.
+
+## Current limitations
+
+- It is not a cycle-accurate or RTL simulator.
+- It is not a complete memory-hierarchy or industrial performance model.
+- The write-policy model does not simulate store buffers, write combining,
+  coherence, memory consistency, energy, or pipeline CPI.
+- EXE packaging and formal validation outside Windows 10/11 are not provided.
+- Results apply to the selected configuration, trace, and stated assumptions;
+  they do not establish a universally optimal policy.
+
+## Project status
+
+CacheVis-RV V3.0 is the current public release. The application exposes eight
+available labs, and the v3.0.0 release is verified by 720 automated tests. See
+[CHANGELOG.md](CHANGELOG.md) and the
+[showcase release notes](docs/V3_PUBLIC_SHOWCASE_RELEASE_NOTES.md).
+
+## Copyright and usage
+
+Copyright © 2026 Yucheng Xu. All rights reserved. The code is source-available
+for portfolio review, educational evaluation, and demonstration. No standard
+open-source license is granted. See [COPYRIGHT.md](COPYRIGHT.md) and
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+## Author / portfolio note
+
+Designed and implemented by Yucheng Xu as a computer architecture education and
+software-engineering portfolio project. Responsible security reports should
+follow [SECURITY.md](SECURITY.md) and must not include secrets or personal data.