docs: restructure documentation

- Split kernel-details.md into focused docs (naive, tiled, bank-free, etc.)
- Add learning-path.md for progressive study guide
- Consolidate specs into specs.md
- Remove redundant RELEASE_NOTES.md (merged into CHANGELOG)
- Update README files with refined content
- Simplify CI workflows
- Update Jekyll config

Author: LessUp

.github/workflows/ci.yml

@@ -5,9 +5,21 @@ name: CI
 
 on:
   push:
-    branches: [main, master]
+    branches: [master]
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - 'index.md'
+      - '_config.yml'
+      - 'openspec/**'
   pull_request:
-    branches: [main, master]
+    branches: [master]
+    paths-ignore:
+      - '**/*.md'
+      - 'docs/**'
+      - 'index.md'
+      - '_config.yml'
+      - 'openspec/**'
   workflow_dispatch:
 
 permissions:

.github/workflows/pages.yml

@@ -1,21 +1,21 @@
 # GitHub Pages Deployment
 # Builds and deploys the project documentation site to GitHub Pages
+# Uses Jekyll with just-the-docs theme
 
 name: Deploy to GitHub Pages
 
 on:
   push:
-    branches: [master, main]
+    branches: [master]
     paths:
-      - 'index.md'
-      - 'README.md'
-      - 'README.zh-CN.md'
       - 'CHANGELOG.md'
       - 'CONTRIBUTING.md'
+      - 'index.md'
       - '_config.yml'
       - 'docs/**'
-      - 'specs/**'
+      - 'specs.md'
       - 'assets/**'
+      - '_sass/**'
       - '.github/workflows/pages.yml'
   workflow_dispatch:
 
@@ -38,6 +38,16 @@ jobs:
       - name: Setup Pages
         uses: actions/configure-pages@v5
 
+      - name: Cache Jekyll build
+        uses: actions/cache@v4
+        with:
+          path: |
+            .jekyll-cache
+            _site
+          key: ${{ runner.os }}-jekyll-${{ hashFiles('**/*.md', '**/*.yml') }}
+          restore-keys: |
+            ${{ runner.os }}-jekyll-
+
       - name: Build with Jekyll
         uses: actions/jekyll-build-pages@v1
         with:
@@ -46,6 +56,8 @@ jobs:
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./_site
 
   deploy:
     environment:

CHANGELOG.md

@@ -1,115 +1,59 @@
+---
+layout: default
+title: Changelog
+nav_order: 10
+permalink: /CHANGELOG
+---
+
 # Changelog
 
-All notable changes to this project will be documented in this file.
+All notable changes to this project are documented here.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project aims to follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
 ### Changed
-- **Documentation Reorganization**: Migrated to Spec-Driven Development (SDD) structure
-  - Removed `.kiro/specs/` directory
-  - Created `/specs/` directory with standardized structure:
-    - `specs/product/` - Product requirements
-    - `specs/rfc/` - Technical design documents (RFCs)
-    - `specs/testing/` - Test specifications
-  - Migrated and translated all spec documents to English
-  - Added `AGENTS.md` for AI agent workflow instructions
-  - Updated `README.md` and `CONTRIBUTING.md` to reference new spec structure
-
-### Fixed
-- **Config Bug**: Fixed duplicate `defaults` section in `_config.yml` causing Jekyll configuration conflict
-- **Config Bug**: Removed reference to non-existent `og-image.png` in `_config.yml`
-- **Code Comment**: Improved clarity in `getTheoreticalPeakGflops()` architecture detection comments
-
-### Improved
-- **GitHub Topics**: Optimized repository topics (removed `deep-learning`, `cuda-kernel`, `nvidia-gpu`; added `cuda-kernels`, `shared-memory`, `bank-conflict`)
-- **CI Workflow**: Added sm_89 and sm_90 architecture support in CUDA build matrix
-- **GitHub Pages**: Added `jekyll-default-layout` plugin, improved performance table formatting
-
----
+- Consolidated repository governance around `openspec/specs/`, updated agent instructions, and simplified documentation roles.
+- Reworked README, GitHub Pages content, and supporting docs into clearer repository-entry and learning surfaces.
+- Began pruning redundant release-history and engineering guidance artifacts in favor of fewer authoritative files.
 
 ## [2.1.0] - 2026-04-16
 
-### Changed
-- **Documentation Refactor**: Complete documentation restructure
-  - Consolidated changelog entries into single `CHANGELOG.md`
-  - Rewrote `.kiro/specs/` documentation (design.md, requirements.md, tasks.md)
-  - Enhanced `index.md` GitHub Pages landing page
-  - Updated `_config.yml` for better Jekyll configuration
-- **GitHub Workflows**: Simplified and optimized
-  - `ci.yml`: Cleaner structure, better step naming
-  - `pages.yml`: Fixed paths filter, improved concurrency group
-
-### Removed
-- **Dead Code Cleanup**: Removed 514 lines of unused code across 7 source files
-  - `src/utils/cuda_utils.cuh`: Removed unused utility functions
-  - `src/utils/verify.cuh`: Removed unused verification functions
-  - `src/kernels/naive_sgemm.cuh`: Removed scaled kernel variants
-  - `src/kernels/tiled_sgemm.cuh`: Removed scaled kernel variants
-  - `src/kernels/bank_conflict_free_sgemm.cuh`: Removed transposed variant
-  - `src/kernels/double_buffer_sgemm.cuh`: Removed register tiled variant
-  - `src/kernels/tensor_core_sgemm.cuh`: Removed unused optimized kernel
-- Deleted `changelog/` directory (consolidated into `CHANGELOG.md`)
-
-## [2.0.0] - 2026-03-13
-
-### Fixed
-- **Critical**: CI workflow adjusted for CPU-safe execution
-  - Removed GPU-dependent CUDA container build from GitHub Hosted Runner
-  - Restored `push`, `pull_request`, and `workflow_dispatch` triggers
-  - Unified format check using `jidicula/clang-format-action`
-
-### Changed
-- CI now only performs static format checking (CPU-safe)
-- GPU runtime tests remain local/dedicated-runner only
-
-## [2.0.0-rc.2] - 2026-03-10
-
 ### Added
-- GitHub Pages configuration with SEO metadata in `_config.yml`
-- Professional Chinese landing page in `index.md`
+- Tensor Core WMMA SGEMM kernel with guarded FP32 fallback for unsupported dimensions
+- Benchmark enhancements, including roofline data export and configurable warmup/benchmark iterations
+- Google Test coverage for standard kernels, Tensor Core fast path, fallback behavior, and edge cases
+- Bilingual documentation and a GitHub Pages documentation site
 
 ### Changed
-- README.md: Added CI/Pages badges, timing column, ASCII roadmap
-- pages.yml: Narrowed path triggers and sparse-checkout
-- .gitignore: Added Jekyll-related entries
+- Consolidated source code into `src/kernels/`, `src/utils/`, and `tests/`
+- Adopted CMake as the primary build system while retaining the Makefile for quick local runs
+- Expanded supported CUDA architecture targets to cover Volta through Hopper generation GPUs
 
 ### Fixed
-- Workflow deep standardization: unified `permissions`, `concurrency`, path filtering
+- Tensor Core path memory management issues
+- Double-buffer synchronization issues
+- Grid dimension handling for non-square matrices
 
-## [2.0.0-rc.1] - 2026-03-09
+## [2.0.0] - 2026-03-13
 
-### Fixed
-- **Critical Memory Leak**: Error checking macros now throw exceptions instead of `exit()`
-- **Memory Leak**: `launch_tensor_core_sgemm` now uses RAII wrappers
-- **Memory Leak**: `SGEMMBenchmark::run()` now uses RAII wrappers
+### Added
+- Bank-conflict-free and double-buffer SGEMM kernels
+- CUDA Events-based benchmark infrastructure
+- Nsight-oriented profiling support
 
 ### Changed
-- **Breaking**: Removed external dependency — project is now self-contained
+- Migrated from an earlier single-file layout to the current modular structure
+- Standardized on CUDA 11.0+ and C++17
 
-### Added
-- `CMakeLists.txt` for modern CMake build
-- Standardized CI workflow with `clang-format` check
-- CUDA container-based build validation
+### Removed
+- Legacy single-file benchmark script
+- SM 6.x support
 
 ## [1.0.0] - 2025-02-13
 
 ### Added
-- MIT LICENSE file
-- `.gitignore` with CUDA/Profiling/IDE rules
-- `.editorconfig` for unified code formatting
-- Standardized badges in README
-
----
-
-## Version History
-
-| Version | Date | Key Changes |
-|---------|------|-------------|
-| 2.1.0 | 2026-04-16 | Documentation refactor, dead code cleanup |
-| 2.0.0 | 2026-03-13 | CPU-safe CI, stable release |
-| 2.0.0-rc.2 | 2026-03-10 | GitHub Pages, documentation |
-| 2.0.0-rc.1 | 2026-03-09 | Memory leak fixes, CMake, self-contained |
-| 1.0.0 | 2025-02-13 | Initial project infrastructure |
+- Initial naive and tiled SGEMM kernels
+- Basic cuBLAS correctness verification
+- First benchmark CLI

CONTRIBUTING.md

@@ -1,67 +1,55 @@
-# Contributing
-
-Thank you for your interest in this project! Contributions via Issues and Pull Requests are welcome.
+---
+layout: default
+title: Contributing
+nav_order: 11
+permalink: /CONTRIBUTING
+---
 
-## Spec-Driven Development
+# Contributing
 
-This project follows **Spec-Driven Development (SDD)**. All technical specifications are maintained in `/specs`:
+Focused improvements are welcome. For this repository, the goal is clarity, correctness, and compactness rather than feature sprawl.
 
-- 📋 [Product Requirements](specs/product/sgemm-kernel-requirements.md)
-- 🏗️ [Core Architecture RFC](specs/rfc/0001-core-architecture.md)
-- 🗺️ [Implementation Roadmap RFC](specs/rfc/0002-implementation-roadmap.md)
-- 🧪 [Test Specifications](specs/testing/kernel-verification.md)
+## When to use OpenSpec
 
-**When contributing new features or changes:**
-1. **Review** the relevant spec documents in `/specs` first.
-2. **Update** specs if your changes affect interfaces, requirements, or behavior.
-3. **Implement** code that 100% adheres to the spec definitions.
-4. **Verify** against spec-defined test criteria.
+Use the OpenSpec workflow for any non-trivial change that affects:
 
-For detailed AI and human contributor workflow, see [`AGENTS.md`](AGENTS.md).
+- repository structure
+- documentation roles or public positioning
+- validation rules or workflows
+- kernel behavior or engineering requirements
 
-## Development Workflow
+Stable specs live under `openspec/specs/`. Active changes live under `openspec/changes/<change>/`.
 
-1. Fork this repository
-2. Create a feature branch: `git checkout -b feature/your-feature`
-3. Commit changes: `git commit -m "feat: add your feature"`
-4. Push branch: `git push origin feature/your-feature`
-5. Create a Pull Request
+## Recommended flow
 
-## Build & Test
+1. `/opsx:explore` for scope and trade-offs
+2. `/opsx:propose "description"` for the actual change
+3. `/opsx:apply` to execute the task list
+4. `/review` before major deletions, workflow changes, or archive
+5. `/opsx:archive` once tasks, docs, specs, and validation all agree
 
-Recommended: CMake (primary build system):
+## Validation
 
 ```bash
 cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
 cmake --build build -j$(nproc)
-./build/bin/sgemm_benchmark
-cmake --build build --target test_sgemm
 ctest --test-dir build
+openspec validate --all
 ```
 
-Quick local builds with Make:
-
-```bash
-make GPU_ARCH=sm_86
-make benchmark
-make test
-```
-
-Note: GitHub Actions currently runs format checks and containerized CUDA compile-only builds. CUDA runtime tests must be executed locally or on a GPU-enabled runner.
-
-## Code Style
+- Hosted CI covers formatting, CUDA compile validation, OpenSpec/repository checks, and Pages.
+- Runtime verification and benchmarking still require a local GPU-capable machine.
 
-- CUDA code follows project conventions (clang-format enforced)
-- Use indentation and formatting rules defined in `.editorconfig`
-- New kernel variants must include correctness verification against cuBLAS
-- Ensure all existing tests pass
+## Code and doc expectations
 
-## Commit Message Format
+- Keep the existing kernel launcher interface shape intact unless the specs require a change.
+- Preserve RAII-based CUDA resource management and exception-style error handling.
+- Avoid adding generic governance boilerplate or duplicate docs.
+- If two files serve the same purpose, prefer one authoritative file over two partially-overlapping ones.
 
-Use [Conventional Commits](https://www.conventionalcommits.org/):
+## Tooling notes
 
-- `feat:` New feature or kernel variant
-- `fix:` Bug fix
-- `perf:` Performance optimization
-- `docs:` Documentation update
-- `test:` Test-related changes
+- CMake is the primary build path.
+- `clangd` plus `compile_commands.json` is the shared LSP baseline.
+- Use `gh` for repository metadata, Actions, issues, and PR operations.
+- Install the lightweight local hooks with `scripts/install-hooks.sh` if you want repository-specific guardrails before commit.