From 4601e36c5232c1be3ace2ee86b239b85bd0fc9ec Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 02:51:35 +0800
Subject: [PATCH 1/6] chore(infra): streamline CI/CD workflows and add git
 hooks

- Simplify GitHub Actions workflows (ci, pages, release)
- Add pre-commit hook for code quality checks
- Update .gitignore with BMad V6 directories and local AI overrides
---
 .githooks/pre-commit          |  21 ++++
 .github/workflows/ci.yml      | 103 +++++-------------
 .github/workflows/pages.yml   |  70 +++----------
 .github/workflows/release.yml | 191 +++++++---------------------------
 .gitignore                    |  10 +-
 5 files changed, 108 insertions(+), 287 deletions(-)
 create mode 100755 .githooks/pre-commit

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100755
index 0000000..90fef09
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="$(git rev-parse --show-toplevel)"
+cd "$repo_root"
+
+mapfile -t source_files < <(
+    git diff --cached --name-only --diff-filter=ACMR | grep -E '\.(cpp|h|cu|cuh)$' || true
+)
+
+if [ "${#source_files[@]}" -eq 0 ]; then
+    exit 0
+fi
+
+if ! command -v clang-format-18 >/dev/null 2>&1; then
+    echo "pre-commit: clang-format-18 not found; skipping format check" >&2
+    exit 0
+fi
+
+clang-format-18 --dry-run --Werror "${source_files[@]}"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6366f28..10577ac 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,23 +1,21 @@
 name: CI
 
 on:
+  pull_request:
+    branches: [master, main]
   push:
-    branches: [main, master]
+    branches: [master, main]
     paths-ignore:
-      - '**.md'
-      - 'docs/**'
-      - 'changelog/**'
+      - '**/*.md'
       - 'website/**'
       - '.github/workflows/pages.yml'
-  pull_request:
-    branches: [main, master]
   workflow_dispatch:
 
 permissions:
   contents: read
 
 concurrency:
-  group: ci-${{ github.workflow }}-${{ github.ref }}
+  group: ci-${{ github.ref }}
   cancel-in-progress: true
 
 env:
@@ -25,22 +23,19 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
-  format-check:
-    name: Format Check
+  format:
+    name: Format
     runs-on: ubuntu-latest
-    if: github.event_name != 'workflow_dispatch'
     steps:
       - name: Checkout
         uses: actions/checkout@v4
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Install clang-format
         run: |
           sudo apt-get update
           sudo apt-get install -y clang-format-18
 
-      - name: Format C/C++/CUDA files
+      - name: Check formatting
         run: |
           find . -type f \( -name '*.cpp' -o -name '*.h' -o -name '*.cu' -o -name '*.cuh' \) \
             ! -path './build/*' \
@@ -49,34 +44,18 @@ jobs:
             ! -path './vendor/*' \
             ! -path './external/*' \
             ! -path './.kiro/*' \
-            | xargs clang-format-18 -i
-
-      - name: Commit formatting changes
-        if: github.event_name == 'push'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add -A
-          git diff --staged --quiet || git commit -m "style: auto-format C/C++/CUDA files [skip ci]"
-
-  build:
-    name: Build (${{ matrix.os }})
-    runs-on: ${{ matrix.os }}
-    needs: [format-check]
-    if: always() && (needs.format-check.result == 'success' || needs.format-check.result == 'skipped')
-    strategy:
-      fail-fast: false
-      matrix:
-        include:
-          - os: ubuntu-22.04
+            | xargs clang-format-18 --dry-run --Werror
 
+  build-test:
+    name: Build and Test
+    runs-on: ubuntu-22.04
+    needs: format
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup CUDA Environment
+      - name: Setup GCC and CUDA
         run: |
-          # Install GCC 10 for CUDA compatibility (GCC 11 has issues with nvcc)
           sudo apt-get update
           sudo apt-get install -y gcc-10 g++-10
           sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100
@@ -84,42 +63,26 @@ jobs:
           sudo update-alternatives --install /usr/bin/cc cc /usr/bin/gcc 30
           sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/g++ 30
 
-          # Check for pre-installed CUDA
-          if command -v nvcc &> /dev/null; then
-            echo "nvcc already in PATH"
+          if command -v nvcc >/dev/null 2>&1; then
             nvcc --version
           elif [ -d "/usr/local/cuda" ]; then
-            echo "CUDA_HOME=/usr/local/cuda" >> $GITHUB_ENV
-            echo "/usr/local/cuda/bin" >> $GITHUB_PATH
-            echo "CUDACXX=/usr/local/cuda/bin/nvcc" >> $GITHUB_ENV
+            echo "CUDA_HOME=/usr/local/cuda" >> "$GITHUB_ENV"
+            echo "/usr/local/cuda/bin" >> "$GITHUB_PATH"
+            echo "CUDACXX=/usr/local/cuda/bin/nvcc" >> "$GITHUB_ENV"
             nvcc --version
           elif [ -d "/usr/lib/nvidia-cuda-toolkit" ]; then
-            echo "CUDA_HOME=/usr/lib/nvidia-cuda-toolkit" >> $GITHUB_ENV
-            echo "/usr/lib/nvidia-cuda-toolkit/bin" >> $GITHUB_PATH
-            echo "CUDACXX=/usr/lib/nvidia-cuda-toolkit/bin/nvcc" >> $GITHUB_ENV
+            echo "CUDA_HOME=/usr/lib/nvidia-cuda-toolkit" >> "$GITHUB_ENV"
+            echo "/usr/lib/nvidia-cuda-toolkit/bin" >> "$GITHUB_PATH"
+            echo "CUDACXX=/usr/lib/nvidia-cuda-toolkit/bin/nvcc" >> "$GITHUB_ENV"
             nvcc --version
           else
-            echo "CUDA not found, installing..."
             sudo apt-get install -y nvidia-cuda-toolkit
-            echo "CUDA_HOME=/usr/lib/nvidia-cuda-toolkit" >> $GITHUB_ENV
-            echo "/usr/lib/nvidia-cuda-toolkit/bin" >> $GITHUB_PATH
-            echo "CUDACXX=/usr/lib/nvidia-cuda-toolkit/bin/nvcc" >> $GITHUB_ENV
+            echo "CUDA_HOME=/usr/lib/nvidia-cuda-toolkit" >> "$GITHUB_ENV"
+            echo "/usr/lib/nvidia-cuda-toolkit/bin" >> "$GITHUB_PATH"
+            echo "CUDACXX=/usr/lib/nvidia-cuda-toolkit/bin/nvcc" >> "$GITHUB_ENV"
             nvcc --version
           fi
 
-          # Set CUDA host compiler to GCC 10 (must be set before running cmake)
-          echo "CUDAHOSTCXX=/usr/bin/g++-10" >> $GITHUB_ENV
-
-          # Verify GCC version
-          echo "Using GCC version:"
-          gcc --version
-
-      - name: Setup ccache
-        uses: hendrikmuhs/ccache-action@v1.2
-        with:
-          key: ${{ runner.os }}-cuda-build
-          max-size: 500M
-
       - name: Configure CMake
         run: |
           cmake -S . -B build \
@@ -128,19 +91,7 @@ jobs:
             -DBUILD_TESTS=ON
 
       - name: Build
-        run: cmake --build build -j$(nproc)
-
-      - name: Run Tests
-        working-directory: build
-        run: ctest --output-on-failure --timeout 300
+        run: cmake --build build -j"$(nproc)"
 
-  ci-status:
-    name: CI Status
-    runs-on: ubuntu-latest
-    needs: [format-check, build]
-    if: always() && (needs.format-check.result == 'success' || needs.format-check.result == 'skipped') && needs.build.result == 'success'
-    steps:
-      - name: Check Status
-        run: |
-          echo "::notice::All tests passed"
-          echo "CI passed successfully"
+      - name: Run tests
+        run: ctest --test-dir build --output-on-failure --timeout 300
diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml
index 8910edc..94b0fc3 100644
--- a/.github/workflows/pages.yml
+++ b/.github/workflows/pages.yml
@@ -1,17 +1,12 @@
-# ═══════════════════════════════════════════════════════════════
-# Tiny-LLM GitHub Pages - Production Deployment
-# Features: PWA, Modern Theme, Search Optimization
-# ═══════════════════════════════════════════════════════════════
-
 name: GitHub Pages
 
 on:
-  push:
+  pull_request:
     branches: [master, main]
     paths:
       - 'website/**'
       - '.github/workflows/pages.yml'
-  pull_request:
+  push:
     branches: [master, main]
     paths:
       - 'website/**'
@@ -31,17 +26,12 @@ env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
-  # ═══════════════════════════════════════════════════════════════
-  # BUILD JOB
-  # ═══════════════════════════════════════════════════════════════
   build:
     name: Build Pages
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout repository
+      - name: Checkout
         uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
 
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
@@ -49,7 +39,7 @@ jobs:
           ruby-version: '3.3'
           bundler-cache: false
 
-      - name: Install dependencies
+      - name: Install site dependencies
         working-directory: website
         run: bundle install
 
@@ -57,62 +47,32 @@ jobs:
         id: pages
         uses: actions/configure-pages@v5
 
-      - name: Build site with Jekyll
+      - name: Build site
         working-directory: website
+        env:
+          JEKYLL_ENV: production
+          JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           bundle exec jekyll build \
             --baseurl "${{ steps.pages.outputs.base_path }}" \
             --destination ../_site \
             --trace
-        env:
-          JEKYLL_ENV: production
-          JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Verify build output
-        run: |
-          echo "Verifying build output..."
-          test -d ./_site || { echo "Error: _site directory not found"; exit 1; }
-          test -f ./_site/index.html || echo "Warning: index.html not found"
-          echo "Build successful!"
-          ls -la ./_site/ | head -20
+          test -f ../_site/index.html
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: ./_site
 
-  # ═══════════════════════════════════════════════════════════════
-  # DEPLOY JOB
-  # ═══════════════════════════════════════════════════════════════
   deploy:
-    name: Deploy to GitHub Pages
+    name: Deploy Pages
     if: github.event_name != 'pull_request'
-    environment:
-      name: github-pages
-      url: ${{ steps.deploy.outputs.page_url }}
     runs-on: ubuntu-latest
     needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     steps:
-      - name: Deploy to GitHub Pages
-        id: deploy
+      - name: Deploy
+        id: deployment
         uses: actions/deploy-pages@v4
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-  # ═══════════════════════════════════════════════════════════════
-  # VALIDATION JOB (PR only)
-  # ═══════════════════════════════════════════════════════════════
-  validate:
-    name: Validate Build
-    if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
-    needs: build
-    steps:
-      - name: Download built artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: github-pages
-          path: ./_site
-
-      - name: List built files
-        run: ls -laR ./_site/
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 503f90c..63c6844 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -4,96 +4,47 @@ on:
   push:
     tags:
       - 'v*.*.*'
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Release version (e.g., v2.0.2)'
-        required: true
-        type: string
 
 permissions:
   contents: write
-  packages: write
 
 env:
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
-  validate:
-    name: Validate Release
-    runs-on: ubuntu-latest
-    outputs:
-      version: ${{ steps.version.outputs.version }}
-      tag: ${{ steps.version.outputs.tag }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Determine Version
-        id: version
-        run: |
-          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
-            VERSION="${{ github.event.inputs.version }}"
-          else
-            VERSION="${GITHUB_REF#refs/tags/}"
-          fi
-          # Validate version format
-          if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-            echo "::error::Invalid version format: $VERSION (expected vX.Y.Z)"
-            exit 1
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "tag=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "Version: $VERSION"
-
-      - name: Check Tag Exists
-        if: github.event_name == 'workflow_dispatch'
-        run: |
-          git fetch --tags
-          if git tag | grep -q "^${{ steps.version.outputs.tag }}$"; then
-            echo "::error::Tag ${{ steps.version.outputs.tag }} already exists"
-            exit 1
-          fi
-
-      - name: Create Tag (if workflow_dispatch)
-        if: github.event_name == 'workflow_dispatch'
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git tag -a ${{ steps.version.outputs.tag }} -m "Release ${{ steps.version.outputs.version }}"
-          git push origin ${{ steps.version.outputs.tag }}
-
   build:
     name: Build Release Artifacts
-    needs: validate
     runs-on: ubuntu-22.04
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
-      - name: Setup CUDA Environment
+      - name: Setup GCC and CUDA
         run: |
-          # Check for pre-installed CUDA
-          if command -v nvcc &> /dev/null; then
-            echo "nvcc already in PATH"
+          sudo apt-get update
+          sudo apt-get install -y gcc-10 g++-10
+          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-10 100
+          sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-10 100
+          sudo update-alternatives --install /usr/bin/cc cc /usr/bin/gcc 30
+          sudo update-alternatives --install /usr/bin/c++ c++ /usr/bin/g++ 30
+
+          if command -v nvcc >/dev/null 2>&1; then
             nvcc --version
           elif [ -d "/usr/local/cuda" ]; then
-            echo "CUDA_HOME=/usr/local/cuda" >> $GITHUB_ENV
-            echo "/usr/local/cuda/bin" >> $GITHUB_PATH
-            echo "CUDACXX=/usr/local/cuda/bin/nvcc" >> $GITHUB_ENV
+            echo "CUDA_HOME=/usr/local/cuda" >> "$GITHUB_ENV"
+            echo "/usr/local/cuda/bin" >> "$GITHUB_PATH"
+            echo "CUDACXX=/usr/local/cuda/bin/nvcc" >> "$GITHUB_ENV"
             nvcc --version
           elif [ -d "/usr/lib/nvidia-cuda-toolkit" ]; then
-            echo "CUDA_HOME=/usr/lib/nvidia-cuda-toolkit" >> $GITHUB_ENV
-            echo "/usr/lib/nvidia-cuda-toolkit/bin" >> $GITHUB_PATH
-            echo "CUDACXX=/usr/lib/nvidia-cuda-toolkit/bin/nvcc" >> $GITHUB_ENV
+            echo "CUDA_HOME=/usr/lib/nvidia-cuda-toolkit" >> "$GITHUB_ENV"
+            echo "/usr/lib/nvidia-cuda-toolkit/bin" >> "$GITHUB_PATH"
+            echo "CUDACXX=/usr/lib/nvidia-cuda-toolkit/bin/nvcc" >> "$GITHUB_ENV"
             nvcc --version
           else
-            echo "CUDA not found, installing..."
-            sudo apt-get update
             sudo apt-get install -y nvidia-cuda-toolkit
-            echo "CUDA_HOME=/usr/lib/nvidia-cuda-toolkit" >> $GITHUB_ENV
-            echo "/usr/lib/nvidia-cuda-toolkit/bin" >> $GITHUB_PATH
-            echo "CUDACXX=/usr/lib/nvidia-cuda-toolkit/bin/nvcc" >> $GITHUB_ENV
+            echo "CUDA_HOME=/usr/lib/nvidia-cuda-toolkit" >> "$GITHUB_ENV"
+            echo "/usr/lib/nvidia-cuda-toolkit/bin" >> "$GITHUB_PATH"
+            echo "CUDACXX=/usr/lib/nvidia-cuda-toolkit/bin/nvcc" >> "$GITHUB_ENV"
             nvcc --version
           fi
 
@@ -101,116 +52,46 @@ jobs:
         run: |
           cmake -S . -B build \
             -DCMAKE_BUILD_TYPE=Release \
+            -DCMAKE_CUDA_HOST_COMPILER=/usr/bin/g++-10 \
             -DBUILD_TESTS=ON
 
       - name: Build
-        run: cmake --build build -j$(nproc)
+        run: cmake --build build -j"$(nproc)"
 
-      - name: Run Tests
-        working-directory: build
-        run: ctest --output-on-failure --timeout 300
+      - name: Run tests
+        run: ctest --test-dir build --output-on-failure --timeout 300
 
-      - name: Prepare Release Artifacts
+      - name: Package release
         run: |
+          version="${GITHUB_REF#refs/tags/}"
           mkdir -p release
           cp build/tiny_llm_demo release/ 2>/dev/null || true
-          cp -r include release/ 2>/dev/null || true
-          cp CMakeLists.txt release/ 2>/dev/null || true
-          tar -czvf tiny-llm-${{ needs.validate.outputs.version }}-linux-x64.tar.gz -C release . 2>/dev/null || echo "No binaries to package"
+          cp -r include release/
+          cp CMakeLists.txt release/
+          tar -czf "tiny-llm-${version}-linux-x64.tar.gz" -C release .
 
-      - name: Upload Artifacts
+      - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:
           name: release-artifacts
-          path: |
-            *.tar.gz
+          path: tiny-llm-*.tar.gz
           retention-days: 7
 
-  release:
-    name: Create Release
-    needs: [validate, build]
+  publish:
+    name: Publish Release
     runs-on: ubuntu-latest
+    needs: build
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Download Artifacts
+      - name: Download artifacts
         uses: actions/download-artifact@v4
         with:
           name: release-artifacts
           path: ./artifacts
 
-      - name: Generate Release Notes
-        id: notes
-        run: |
-          VERSION="${{ needs.validate.outputs.version }}"
-          VER_NUM="${VERSION#v}"
-          
-          CHANGELOG_EN="website/changelog/en/${VER_NUM}.md"
-          CHANGELOG_ZH="website/changelog/zh/${VER_NUM}.md"
-          
-          {
-            echo "release_notes<<EOF"
-            echo "## Tiny-LLM $VERSION"
-            echo ""
-            if [[ -f "$CHANGELOG_EN" ]]; then
-              echo "### English"
-              echo ""
-              echo "High-performance CUDA C++ inference engine release."
-              echo ""
-              echo "**Highlights**:"
-              echo "- W8A16 quantization for ~50% memory reduction"
-              echo "- Efficient KV Cache management"
-              echo "- Optimized CUDA kernels with Tensor Core support"
-              echo ""
-              echo "See [Changelog](https://lessup.github.io/tiny-llm/changelog/en/${VER_NUM}.html) for details."
-              echo ""
-              echo "---"
-              echo ""
-              echo "### 简体中文"
-              echo ""
-              echo "高性能 CUDA C++ 推理引擎发布。"
-              echo ""
-              echo "**亮点**："
-              echo "- W8A16 量化，显存减少约 50%"
-              echo "- 高效 KV 缓存管理"
-              echo "- 优化的 CUDA 内核，支持 Tensor Core"
-              echo ""
-              echo "详见 [更新日志](https://lessup.github.io/tiny-llm/changelog/zh/${VER_NUM}.html)。"
-            else
-              echo "### English"
-              echo "Release $VERSION"
-              echo ""
-              echo "---"
-              echo ""
-              echo "### 简体中文"
-              echo "发布 $VERSION"
-            fi
-            echo ""
-            echo "### Installation | 安装"
-            echo ""
-            echo '```bash'
-            echo "git clone https://github.com/LessUp/tiny-llm.git"
-            echo "cd tiny-llm"
-            echo "git checkout $VERSION"
-            echo "mkdir build && cd build"
-            echo "cmake .. -DCMAKE_BUILD_TYPE=Release"
-            echo "make -j\$(nproc)"
-            echo '```'
-            echo ""
-            echo "[Documentation | 文档](https://lessup.github.io/tiny-llm/) | [API Reference | API 参考](https://lessup.github.io/tiny-llm/docs/en/API.html)"
-            echo "EOF"
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Create GitHub Release
+      - name: Create GitHub release
         uses: softprops/action-gh-release@v2
         with:
-          tag_name: ${{ needs.validate.outputs.tag }}
-          name: Tiny-LLM ${{ needs.validate.outputs.version }}
-          body: ${{ steps.notes.outputs.release_notes }}
-          draft: false
-          prerelease: ${{ contains(needs.validate.outputs.version, '-rc') || contains(needs.validate.outputs.version, '-beta') || contains(needs.validate.outputs.version, '-alpha') }}
-          files: |
-            artifacts/*.tar.gz
+          files: artifacts/*.tar.gz
+          generate_release_notes: true
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/.gitignore b/.gitignore
index ab5839c..4350473 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,10 +43,14 @@ Makefile
 .vscode/launch.json
 .vscode/tasks.json
 .vscode/.ropeproject
+compile_commands.json
 *.swp
 *.swo
 *~
 
+# Local AI overrides
+CLAUDE.local.md
+
 # OS generated files
 .DS_Store
 .DS_Store?
@@ -83,4 +87,8 @@ coverage/
 
 # Profiling data
 *.prof
-*.nvprof
\ No newline at end of file
+*.nvprof
+
+# BMad Method V6
+_bmad/
+_bmad-output/

From 200c46a7272ffb6398e5db47ab9f6e5fbe59f948 Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 02:51:42 +0800
Subject: [PATCH 2/6] feat(ai-tools): add BMad V6, OpenSpec workflow and Claude
 Code integration

- Install BMad Method V6 with 41 Claude Code skills
- Add OpenSpec change management workflow and specs
- Configure Claude Code with project-specific instructions
- Add VSCode extension recommendations
- Add GitHub Copilot instructions
- Configure clangd for C++ language server
---
 .clangd                                       |    8 +
 .claude/commands/opsx/apply.md                |  152 ++
 .claude/commands/opsx/archive.md              |  157 ++
 .claude/commands/opsx/explore.md              |  173 ++
 .claude/commands/opsx/propose.md              |  106 ++
 .../skills/bmad-advanced-elicitation/SKILL.md |  136 ++
 .../bmad-advanced-elicitation/methods.csv     |   51 +
 .claude/skills/bmad-agent-analyst/SKILL.md    |   59 +
 .../bmad-skill-manifest.yaml                  |   11 +
 .claude/skills/bmad-agent-architect/SKILL.md  |   54 +
 .../bmad-skill-manifest.yaml                  |   11 +
 .claude/skills/bmad-agent-dev/SKILL.md        |   69 +
 .../bmad-agent-dev/bmad-skill-manifest.yaml   |   11 +
 .claude/skills/bmad-agent-pm/SKILL.md         |   59 +
 .../bmad-agent-pm/bmad-skill-manifest.yaml    |   11 +
 .../skills/bmad-agent-tech-writer/SKILL.md    |   57 +
 .../bmad-skill-manifest.yaml                  |   11 +
 .../bmad-agent-tech-writer/explain-concept.md |   20 +
 .../bmad-agent-tech-writer/mermaid-gen.md     |   20 +
 .../bmad-agent-tech-writer/validate-doc.md    |   19 +
 .../bmad-agent-tech-writer/write-document.md  |   20 +
 .../skills/bmad-agent-ux-designer/SKILL.md    |   55 +
 .../bmad-skill-manifest.yaml                  |   11 +
 .claude/skills/bmad-brainstorming/SKILL.md    |    6 +
 .../bmad-brainstorming/brain-methods.csv      |   62 +
 .../steps/step-01-session-setup.md            |  214 +++
 .../steps/step-01b-continue.md                |  124 ++
 .../steps/step-02a-user-selected.md           |  229 +++
 .../steps/step-02b-ai-recommended.md          |  239 +++
 .../steps/step-02c-random-selection.md        |  211 +++
 .../steps/step-02d-progressive-flow.md        |  266 +++
 .../steps/step-03-technique-execution.md      |  401 +++++
 .../steps/step-04-idea-organization.md        |  305 ++++
 .claude/skills/bmad-brainstorming/template.md |   15 +
 .claude/skills/bmad-brainstorming/workflow.md |   53 +
 .../SKILL.md                                  |    6 +
 .../steps/step-01-document-discovery.md       |  179 ++
 .../steps/step-02-prd-analysis.md             |  168 ++
 .../steps/step-03-epic-coverage-validation.md |  169 ++
 .../steps/step-04-ux-alignment.md             |  129 ++
 .../steps/step-05-epic-quality-review.md      |  241 +++
 .../steps/step-06-final-assessment.md         |  126 ++
 .../templates/readiness-report-template.md    |    4 +
 .../workflow.md                               |   47 +
 .../skills/bmad-checkpoint-preview/SKILL.md   |   29 +
 .../bmad-checkpoint-preview/generate-trail.md |   38 +
 .../step-01-orientation.md                    |  105 ++
 .../step-02-walkthrough.md                    |   89 +
 .../step-03-detail-pass.md                    |  106 ++
 .../step-04-testing.md                        |   74 +
 .../bmad-checkpoint-preview/step-05-wrapup.md |   24 +
 .claude/skills/bmad-code-review/SKILL.md      |    6 +
 .../steps/step-01-gather-context.md           |   85 +
 .../bmad-code-review/steps/step-02-review.md  |   34 +
 .../bmad-code-review/steps/step-03-triage.md  |   49 +
 .../bmad-code-review/steps/step-04-present.md |  129 ++
 .claude/skills/bmad-code-review/workflow.md   |   55 +
 .claude/skills/bmad-correct-course/SKILL.md   |    6 +
 .../skills/bmad-correct-course/checklist.md   |  288 ++++
 .../skills/bmad-correct-course/workflow.md    |  267 +++
 .../skills/bmad-create-architecture/SKILL.md  |    6 +
 .../architecture-decision-template.md         |   12 +
 .../data/domain-complexity.csv                |   13 +
 .../data/project-types.csv                    |    7 +
 .../steps/step-01-init.md                     |  153 ++
 .../steps/step-01b-continue.md                |  173 ++
 .../steps/step-02-context.md                  |  224 +++
 .../steps/step-03-starter.md                  |  329 ++++
 .../steps/step-04-decisions.md                |  318 ++++
 .../steps/step-05-patterns.md                 |  359 ++++
 .../steps/step-06-structure.md                |  379 +++++
 .../steps/step-07-validation.md               |  359 ++++
 .../steps/step-08-complete.md                 |   76 +
 .../bmad-create-architecture/workflow.md      |   32 +
 .../bmad-create-epics-and-stories/SKILL.md    |    6 +
 .../steps/step-01-validate-prerequisites.md   |  255 +++
 .../steps/step-02-design-epics.md             |  212 +++
 .../steps/step-03-create-stories.md           |  255 +++
 .../steps/step-04-final-validation.md         |  131 ++
 .../templates/epics-template.md               |   61 +
 .../bmad-create-epics-and-stories/workflow.md |   51 +
 .claude/skills/bmad-create-prd/SKILL.md       |    6 +
 .../data/domain-complexity.csv                |   15 +
 .../bmad-create-prd/data/prd-purpose.md       |  197 +++
 .../bmad-create-prd/data/project-types.csv    |   11 +
 .../bmad-create-prd/steps-c/step-01-init.md   |  178 ++
 .../steps-c/step-01b-continue.md              |  161 ++
 .../steps-c/step-02-discovery.md              |  208 +++
 .../steps-c/step-02b-vision.md                |  142 ++
 .../steps-c/step-02c-executive-summary.md     |  158 ++
 .../steps-c/step-03-success.md                |  214 +++
 .../steps-c/step-04-journeys.md               |  201 +++
 .../bmad-create-prd/steps-c/step-05-domain.md |  194 +++
 .../steps-c/step-06-innovation.md             |  211 +++
 .../steps-c/step-07-project-type.md           |  222 +++
 .../steps-c/step-08-scoping.md                |  216 +++
 .../steps-c/step-09-functional.md             |  219 +++
 .../steps-c/step-10-nonfunctional.md          |  230 +++
 .../bmad-create-prd/steps-c/step-11-polish.md |  221 +++
 .../steps-c/step-12-complete.md               |  115 ++
 .../bmad-create-prd/templates/prd-template.md |   10 +
 .claude/skills/bmad-create-prd/workflow.md    |   61 +
 .claude/skills/bmad-create-story/SKILL.md     |    6 +
 .claude/skills/bmad-create-story/checklist.md |  357 ++++
 .../bmad-create-story/discover-inputs.md      |   88 +
 .claude/skills/bmad-create-story/template.md  |   49 +
 .claude/skills/bmad-create-story/workflow.md  |  380 +++++
 .claude/skills/bmad-create-ux-design/SKILL.md |    6 +
 .../steps/step-01-init.md                     |  135 ++
 .../steps/step-01b-continue.md                |  127 ++
 .../steps/step-02-discovery.md                |  190 +++
 .../steps/step-03-core-experience.md          |  217 +++
 .../steps/step-04-emotional-response.md       |  220 +++
 .../steps/step-05-inspiration.md              |  235 +++
 .../steps/step-06-design-system.md            |  253 +++
 .../steps/step-07-defining-experience.md      |  255 +++
 .../steps/step-08-visual-foundation.md        |  225 +++
 .../steps/step-09-design-directions.md        |  225 +++
 .../steps/step-10-user-journeys.md            |  242 +++
 .../steps/step-11-component-strategy.md       |  249 +++
 .../steps/step-12-ux-patterns.md              |  238 +++
 .../steps/step-13-responsive-accessibility.md |  265 +++
 .../steps/step-14-complete.md                 |  171 ++
 .../ux-design-template.md                     |   13 +
 .../skills/bmad-create-ux-design/workflow.md  |   35 +
 .claude/skills/bmad-dev-story/SKILL.md        |    6 +
 .claude/skills/bmad-dev-story/checklist.md    |   80 +
 .claude/skills/bmad-dev-story/workflow.md     |  450 +++++
 .claude/skills/bmad-distillator/SKILL.md      |  177 ++
 .../agents/distillate-compressor.md           |  116 ++
 .../agents/round-trip-reconstructor.md        |   68 +
 .../resources/compression-rules.md            |   51 +
 .../resources/distillate-format-reference.md  |  227 +++
 .../resources/splitting-strategy.md           |   78 +
 .../scripts/analyze_sources.py                |  300 ++++
 .../scripts/tests/test_analyze_sources.py     |  204 +++
 .claude/skills/bmad-document-project/SKILL.md |    6 +
 .../skills/bmad-document-project/checklist.md |  245 +++
 .../documentation-requirements.csv            |   12 +
 .../bmad-document-project/instructions.md     |  128 ++
 .../templates/deep-dive-template.md           |  345 ++++
 .../templates/index-template.md               |  169 ++
 .../templates/project-overview-template.md    |  103 ++
 .../templates/project-scan-report-schema.json |  160 ++
 .../templates/source-tree-template.md         |  135 ++
 .../skills/bmad-document-project/workflow.md  |   25 +
 .../workflows/deep-dive-instructions.md       |  299 ++++
 .../workflows/deep-dive-workflow.md           |   34 +
 .../workflows/full-scan-instructions.md       | 1107 ++++++++++++
 .../workflows/full-scan-workflow.md           |   34 +
 .claude/skills/bmad-domain-research/SKILL.md  |    6 +
 .../domain-steps/step-01-init.md              |  137 ++
 .../domain-steps/step-02-domain-analysis.md   |  229 +++
 .../step-03-competitive-landscape.md          |  238 +++
 .../domain-steps/step-04-regulatory-focus.md  |  206 +++
 .../domain-steps/step-05-technical-trends.md  |  234 +++
 .../step-06-research-synthesis.md             |  444 +++++
 .../bmad-domain-research/research.template.md |   29 +
 .../skills/bmad-domain-research/workflow.md   |   51 +
 .claude/skills/bmad-edit-prd/SKILL.md         |    6 +
 .../skills/bmad-edit-prd/data/prd-purpose.md  |  197 +++
 .../steps-e/step-e-01-discovery.md            |  242 +++
 .../steps-e/step-e-01b-legacy-conversion.md   |  204 +++
 .../bmad-edit-prd/steps-e/step-e-02-review.md |  245 +++
 .../bmad-edit-prd/steps-e/step-e-03-edit.md   |  250 +++
 .../steps-e/step-e-04-complete.md             |  163 ++
 .claude/skills/bmad-edit-prd/workflow.md      |   62 +
 .../bmad-editorial-review-prose/SKILL.md      |   86 +
 .../bmad-editorial-review-structure/SKILL.md  |  179 ++
 .../bmad-generate-project-context/SKILL.md    |    6 +
 .../project-context-template.md               |   21 +
 .../steps/step-01-discover.md                 |  186 +++
 .../steps/step-02-generate.md                 |  321 ++++
 .../steps/step-03-complete.md                 |  278 ++++
 .../bmad-generate-project-context/workflow.md |   39 +
 .claude/skills/bmad-help/SKILL.md             |   75 +
 .claude/skills/bmad-index-docs/SKILL.md       |   66 +
 .claude/skills/bmad-market-research/SKILL.md  |    6 +
 .../bmad-market-research/research.template.md |   29 +
 .../steps/step-01-init.md                     |  184 ++
 .../steps/step-02-customer-behavior.md        |  239 +++
 .../steps/step-03-customer-pain-points.md     |  251 +++
 .../steps/step-04-customer-decisions.md       |  261 +++
 .../steps/step-05-competitive-analysis.md     |  173 ++
 .../steps/step-06-research-completion.md      |  478 ++++++
 .../skills/bmad-market-research/workflow.md   |   51 +
 .claude/skills/bmad-party-mode/SKILL.md       |  125 ++
 .claude/skills/bmad-prfaq/SKILL.md            |   96 ++
 .../bmad-prfaq/agents/artifact-analyzer.md    |   60 +
 .../bmad-prfaq/agents/web-researcher.md       |   49 +
 .../bmad-prfaq/assets/prfaq-template.md       |   62 +
 .claude/skills/bmad-prfaq/bmad-manifest.json  |   16 +
 .../bmad-prfaq/references/customer-faq.md     |   55 +
 .../bmad-prfaq/references/internal-faq.md     |   51 +
 .../bmad-prfaq/references/press-release.md    |   60 +
 .../skills/bmad-prfaq/references/verdict.md   |   79 +
 .claude/skills/bmad-product-brief/SKILL.md    |   82 +
 .../agents/artifact-analyzer.md               |   60 +
 .../agents/opportunity-reviewer.md            |   44 +
 .../agents/skeptic-reviewer.md                |   44 +
 .../agents/web-researcher.md                  |   49 +
 .../bmad-product-brief/bmad-manifest.json     |   17 +
 .../prompts/contextual-discovery.md           |   57 +
 .../prompts/draft-and-review.md               |   86 +
 .../bmad-product-brief/prompts/finalize.md    |   75 +
 .../prompts/guided-elicitation.md             |   70 +
 .../resources/brief-template.md               |   60 +
 .../bmad-qa-generate-e2e-tests/SKILL.md       |    6 +
 .../bmad-qa-generate-e2e-tests/checklist.md   |   33 +
 .../bmad-qa-generate-e2e-tests/workflow.md    |  136 ++
 .claude/skills/bmad-quick-dev/SKILL.md        |    6 +
 .../bmad-quick-dev/compile-epic-context.md    |   62 +
 .../skills/bmad-quick-dev/spec-template.md    |   88 +
 .../step-01-clarify-and-route.md              |   91 +
 .claude/skills/bmad-quick-dev/step-02-plan.md |   47 +
 .../bmad-quick-dev/step-03-implement.md       |   39 +
 .../skills/bmad-quick-dev/step-04-review.md   |   49 +
 .../skills/bmad-quick-dev/step-05-present.md  |   63 +
 .claude/skills/bmad-quick-dev/step-oneshot.md |   61 +
 .claude/skills/bmad-quick-dev/workflow.md     |   75 +
 .claude/skills/bmad-retrospective/SKILL.md    |    6 +
 .claude/skills/bmad-retrospective/workflow.md | 1479 +++++++++++++++++
 .../bmad-review-adversarial-general/SKILL.md  |   37 +
 .../bmad-review-edge-case-hunter/SKILL.md     |   67 +
 .claude/skills/bmad-shard-doc/SKILL.md        |  105 ++
 .claude/skills/bmad-sprint-planning/SKILL.md  |    6 +
 .../skills/bmad-sprint-planning/checklist.md  |   33 +
 .../sprint-status-template.yaml               |   56 +
 .../skills/bmad-sprint-planning/workflow.md   |  263 +++
 .claude/skills/bmad-sprint-status/SKILL.md    |    6 +
 .claude/skills/bmad-sprint-status/workflow.md |  261 +++
 .../skills/bmad-technical-research/SKILL.md   |    6 +
 .../research.template.md                      |   29 +
 .../technical-steps/step-01-init.md           |  137 ++
 .../step-02-technical-overview.md             |  239 +++
 .../step-03-integration-patterns.md           |  248 +++
 .../step-04-architectural-patterns.md         |  202 +++
 .../step-05-implementation-research.md        |  233 +++
 .../step-06-research-synthesis.md             |  487 ++++++
 .../bmad-technical-research/workflow.md       |   52 +
 .claude/skills/bmad-validate-prd/SKILL.md     |    6 +
 .../data/domain-complexity.csv                |   15 +
 .../bmad-validate-prd/data/prd-purpose.md     |  197 +++
 .../bmad-validate-prd/data/project-types.csv  |   11 +
 .../steps-v/step-v-01-discovery.md            |  221 +++
 .../steps-v/step-v-02-format-detection.md     |  188 +++
 .../steps-v/step-v-02b-parity-check.md        |  206 +++
 .../steps-v/step-v-03-density-validation.md   |  171 ++
 .../step-v-04-brief-coverage-validation.md    |  211 +++
 .../step-v-05-measurability-validation.md     |  225 +++
 .../step-v-06-traceability-validation.md      |  214 +++
 ...-v-07-implementation-leakage-validation.md |  202 +++
 .../step-v-08-domain-compliance-validation.md |  240 +++
 .../step-v-09-project-type-validation.md      |  260 +++
 .../steps-v/step-v-10-smart-validation.md     |  206 +++
 .../step-v-11-holistic-quality-validation.md  |  261 +++
 .../step-v-12-completeness-validation.md      |  239 +++
 .../steps-v/step-v-13-report-complete.md      |  229 +++
 .claude/skills/bmad-validate-prd/workflow.md  |   61 +
 .claude/skills/openspec-apply-change/SKILL.md |  156 ++
 .../skills/openspec-archive-change/SKILL.md   |  114 ++
 .claude/skills/openspec-explore/SKILL.md      |  288 ++++
 .claude/skills/openspec-propose/SKILL.md      |  110 ++
 .claude/skills/verify/SKILL.md                |   32 +
 .github/copilot-instructions.md               |   38 +
 .vscode/extensions.json                       |    6 +
 CLAUDE.md                                     |   56 +
 openspec/MIGRATION.md                         |  113 ++
 .../archive/core-architecture/design.md       |  148 ++
 .../archive/core-architecture/proposal.md     |   22 +
 .../initial-implementation/proposal.md        |   22 +
 .../archive/initial-implementation/tasks.md   |  106 ++
 .../.openspec.yaml                            |    2 +
 .../normalize-archive-readiness/design.md     |  127 ++
 .../normalize-archive-readiness/proposal.md   |   30 +
 .../specs/ai-assisted-development/spec.md     |   34 +
 .../specs/project-presentation/spec.md        |   34 +
 .../specs/repository-governance/spec.md       |   45 +
 .../normalize-archive-readiness/tasks.md      |   36 +
 openspec/config.yaml                          |   25 +
 openspec/schemas/api/inference-engine.yaml    |   77 +
 openspec/schemas/db/schema-v1.dbml            |  178 ++
 openspec/specs/inference-engine/spec.md       |  245 +++
 283 files changed, 38484 insertions(+)
 create mode 100644 .clangd
 create mode 100644 .claude/commands/opsx/apply.md
 create mode 100644 .claude/commands/opsx/archive.md
 create mode 100644 .claude/commands/opsx/explore.md
 create mode 100644 .claude/commands/opsx/propose.md
 create mode 100644 .claude/skills/bmad-advanced-elicitation/SKILL.md
 create mode 100644 .claude/skills/bmad-advanced-elicitation/methods.csv
 create mode 100644 .claude/skills/bmad-agent-analyst/SKILL.md
 create mode 100644 .claude/skills/bmad-agent-analyst/bmad-skill-manifest.yaml
 create mode 100644 .claude/skills/bmad-agent-architect/SKILL.md
 create mode 100644 .claude/skills/bmad-agent-architect/bmad-skill-manifest.yaml
 create mode 100644 .claude/skills/bmad-agent-dev/SKILL.md
 create mode 100644 .claude/skills/bmad-agent-dev/bmad-skill-manifest.yaml
 create mode 100644 .claude/skills/bmad-agent-pm/SKILL.md
 create mode 100644 .claude/skills/bmad-agent-pm/bmad-skill-manifest.yaml
 create mode 100644 .claude/skills/bmad-agent-tech-writer/SKILL.md
 create mode 100644 .claude/skills/bmad-agent-tech-writer/bmad-skill-manifest.yaml
 create mode 100644 .claude/skills/bmad-agent-tech-writer/explain-concept.md
 create mode 100644 .claude/skills/bmad-agent-tech-writer/mermaid-gen.md
 create mode 100644 .claude/skills/bmad-agent-tech-writer/validate-doc.md
 create mode 100644 .claude/skills/bmad-agent-tech-writer/write-document.md
 create mode 100644 .claude/skills/bmad-agent-ux-designer/SKILL.md
 create mode 100644 .claude/skills/bmad-agent-ux-designer/bmad-skill-manifest.yaml
 create mode 100644 .claude/skills/bmad-brainstorming/SKILL.md
 create mode 100644 .claude/skills/bmad-brainstorming/brain-methods.csv
 create mode 100644 .claude/skills/bmad-brainstorming/steps/step-01-session-setup.md
 create mode 100644 .claude/skills/bmad-brainstorming/steps/step-01b-continue.md
 create mode 100644 .claude/skills/bmad-brainstorming/steps/step-02a-user-selected.md
 create mode 100644 .claude/skills/bmad-brainstorming/steps/step-02b-ai-recommended.md
 create mode 100644 .claude/skills/bmad-brainstorming/steps/step-02c-random-selection.md
 create mode 100644 .claude/skills/bmad-brainstorming/steps/step-02d-progressive-flow.md
 create mode 100644 .claude/skills/bmad-brainstorming/steps/step-03-technique-execution.md
 create mode 100644 .claude/skills/bmad-brainstorming/steps/step-04-idea-organization.md
 create mode 100644 .claude/skills/bmad-brainstorming/template.md
 create mode 100644 .claude/skills/bmad-brainstorming/workflow.md
 create mode 100644 .claude/skills/bmad-check-implementation-readiness/SKILL.md
 create mode 100644 .claude/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md
 create mode 100644 .claude/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md
 create mode 100644 .claude/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md
 create mode 100644 .claude/skills/bmad-check-implementation-readiness/steps/step-04-ux-alignment.md
 create mode 100644 .claude/skills/bmad-check-implementation-readiness/steps/step-05-epic-quality-review.md
 create mode 100644 .claude/skills/bmad-check-implementation-readiness/steps/step-06-final-assessment.md
 create mode 100644 .claude/skills/bmad-check-implementation-readiness/templates/readiness-report-template.md
 create mode 100644 .claude/skills/bmad-check-implementation-readiness/workflow.md
 create mode 100644 .claude/skills/bmad-checkpoint-preview/SKILL.md
 create mode 100644 .claude/skills/bmad-checkpoint-preview/generate-trail.md
 create mode 100644 .claude/skills/bmad-checkpoint-preview/step-01-orientation.md
 create mode 100644 .claude/skills/bmad-checkpoint-preview/step-02-walkthrough.md
 create mode 100644 .claude/skills/bmad-checkpoint-preview/step-03-detail-pass.md
 create mode 100644 .claude/skills/bmad-checkpoint-preview/step-04-testing.md
 create mode 100644 .claude/skills/bmad-checkpoint-preview/step-05-wrapup.md
 create mode 100644 .claude/skills/bmad-code-review/SKILL.md
 create mode 100644 .claude/skills/bmad-code-review/steps/step-01-gather-context.md
 create mode 100644 .claude/skills/bmad-code-review/steps/step-02-review.md
 create mode 100644 .claude/skills/bmad-code-review/steps/step-03-triage.md
 create mode 100644 .claude/skills/bmad-code-review/steps/step-04-present.md
 create mode 100644 .claude/skills/bmad-code-review/workflow.md
 create mode 100644 .claude/skills/bmad-correct-course/SKILL.md
 create mode 100644 .claude/skills/bmad-correct-course/checklist.md
 create mode 100644 .claude/skills/bmad-correct-course/workflow.md
 create mode 100644 .claude/skills/bmad-create-architecture/SKILL.md
 create mode 100644 .claude/skills/bmad-create-architecture/architecture-decision-template.md
 create mode 100644 .claude/skills/bmad-create-architecture/data/domain-complexity.csv
 create mode 100644 .claude/skills/bmad-create-architecture/data/project-types.csv
 create mode 100644 .claude/skills/bmad-create-architecture/steps/step-01-init.md
 create mode 100644 .claude/skills/bmad-create-architecture/steps/step-01b-continue.md
 create mode 100644 .claude/skills/bmad-create-architecture/steps/step-02-context.md
 create mode 100644 .claude/skills/bmad-create-architecture/steps/step-03-starter.md
 create mode 100644 .claude/skills/bmad-create-architecture/steps/step-04-decisions.md
 create mode 100644 .claude/skills/bmad-create-architecture/steps/step-05-patterns.md
 create mode 100644 .claude/skills/bmad-create-architecture/steps/step-06-structure.md
 create mode 100644 .claude/skills/bmad-create-architecture/steps/step-07-validation.md
 create mode 100644 .claude/skills/bmad-create-architecture/steps/step-08-complete.md
 create mode 100644 .claude/skills/bmad-create-architecture/workflow.md
 create mode 100644 .claude/skills/bmad-create-epics-and-stories/SKILL.md
 create mode 100644 .claude/skills/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.md
 create mode 100644 .claude/skills/bmad-create-epics-and-stories/steps/step-02-design-epics.md
 create mode 100644 .claude/skills/bmad-create-epics-and-stories/steps/step-03-create-stories.md
 create mode 100644 .claude/skills/bmad-create-epics-and-stories/steps/step-04-final-validation.md
 create mode 100644 .claude/skills/bmad-create-epics-and-stories/templates/epics-template.md
 create mode 100644 .claude/skills/bmad-create-epics-and-stories/workflow.md
 create mode 100644 .claude/skills/bmad-create-prd/SKILL.md
 create mode 100644 .claude/skills/bmad-create-prd/data/domain-complexity.csv
 create mode 100644 .claude/skills/bmad-create-prd/data/prd-purpose.md
 create mode 100644 .claude/skills/bmad-create-prd/data/project-types.csv
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-01-init.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-01b-continue.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-02-discovery.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-02b-vision.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-02c-executive-summary.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-03-success.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-04-journeys.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-05-domain.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-06-innovation.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-07-project-type.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-08-scoping.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-09-functional.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-10-nonfunctional.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-11-polish.md
 create mode 100644 .claude/skills/bmad-create-prd/steps-c/step-12-complete.md
 create mode 100644 .claude/skills/bmad-create-prd/templates/prd-template.md
 create mode 100644 .claude/skills/bmad-create-prd/workflow.md
 create mode 100644 .claude/skills/bmad-create-story/SKILL.md
 create mode 100644 .claude/skills/bmad-create-story/checklist.md
 create mode 100644 .claude/skills/bmad-create-story/discover-inputs.md
 create mode 100644 .claude/skills/bmad-create-story/template.md
 create mode 100644 .claude/skills/bmad-create-story/workflow.md
 create mode 100644 .claude/skills/bmad-create-ux-design/SKILL.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-01-init.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-01b-continue.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-02-discovery.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-03-core-experience.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-04-emotional-response.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-05-inspiration.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-06-design-system.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-07-defining-experience.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-08-visual-foundation.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-09-design-directions.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-10-user-journeys.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-11-component-strategy.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-12-ux-patterns.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md
 create mode 100644 .claude/skills/bmad-create-ux-design/steps/step-14-complete.md
 create mode 100644 .claude/skills/bmad-create-ux-design/ux-design-template.md
 create mode 100644 .claude/skills/bmad-create-ux-design/workflow.md
 create mode 100644 .claude/skills/bmad-dev-story/SKILL.md
 create mode 100644 .claude/skills/bmad-dev-story/checklist.md
 create mode 100644 .claude/skills/bmad-dev-story/workflow.md
 create mode 100644 .claude/skills/bmad-distillator/SKILL.md
 create mode 100644 .claude/skills/bmad-distillator/agents/distillate-compressor.md
 create mode 100644 .claude/skills/bmad-distillator/agents/round-trip-reconstructor.md
 create mode 100644 .claude/skills/bmad-distillator/resources/compression-rules.md
 create mode 100644 .claude/skills/bmad-distillator/resources/distillate-format-reference.md
 create mode 100644 .claude/skills/bmad-distillator/resources/splitting-strategy.md
 create mode 100644 .claude/skills/bmad-distillator/scripts/analyze_sources.py
 create mode 100644 .claude/skills/bmad-distillator/scripts/tests/test_analyze_sources.py
 create mode 100644 .claude/skills/bmad-document-project/SKILL.md
 create mode 100644 .claude/skills/bmad-document-project/checklist.md
 create mode 100644 .claude/skills/bmad-document-project/documentation-requirements.csv
 create mode 100644 .claude/skills/bmad-document-project/instructions.md
 create mode 100644 .claude/skills/bmad-document-project/templates/deep-dive-template.md
 create mode 100644 .claude/skills/bmad-document-project/templates/index-template.md
 create mode 100644 .claude/skills/bmad-document-project/templates/project-overview-template.md
 create mode 100644 .claude/skills/bmad-document-project/templates/project-scan-report-schema.json
 create mode 100644 .claude/skills/bmad-document-project/templates/source-tree-template.md
 create mode 100644 .claude/skills/bmad-document-project/workflow.md
 create mode 100644 .claude/skills/bmad-document-project/workflows/deep-dive-instructions.md
 create mode 100644 .claude/skills/bmad-document-project/workflows/deep-dive-workflow.md
 create mode 100644 .claude/skills/bmad-document-project/workflows/full-scan-instructions.md
 create mode 100644 .claude/skills/bmad-document-project/workflows/full-scan-workflow.md
 create mode 100644 .claude/skills/bmad-domain-research/SKILL.md
 create mode 100644 .claude/skills/bmad-domain-research/domain-steps/step-01-init.md
 create mode 100644 .claude/skills/bmad-domain-research/domain-steps/step-02-domain-analysis.md
 create mode 100644 .claude/skills/bmad-domain-research/domain-steps/step-03-competitive-landscape.md
 create mode 100644 .claude/skills/bmad-domain-research/domain-steps/step-04-regulatory-focus.md
 create mode 100644 .claude/skills/bmad-domain-research/domain-steps/step-05-technical-trends.md
 create mode 100644 .claude/skills/bmad-domain-research/domain-steps/step-06-research-synthesis.md
 create mode 100644 .claude/skills/bmad-domain-research/research.template.md
 create mode 100644 .claude/skills/bmad-domain-research/workflow.md
 create mode 100644 .claude/skills/bmad-edit-prd/SKILL.md
 create mode 100644 .claude/skills/bmad-edit-prd/data/prd-purpose.md
 create mode 100644 .claude/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md
 create mode 100644 .claude/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md
 create mode 100644 .claude/skills/bmad-edit-prd/steps-e/step-e-02-review.md
 create mode 100644 .claude/skills/bmad-edit-prd/steps-e/step-e-03-edit.md
 create mode 100644 .claude/skills/bmad-edit-prd/steps-e/step-e-04-complete.md
 create mode 100644 .claude/skills/bmad-edit-prd/workflow.md
 create mode 100644 .claude/skills/bmad-editorial-review-prose/SKILL.md
 create mode 100644 .claude/skills/bmad-editorial-review-structure/SKILL.md
 create mode 100644 .claude/skills/bmad-generate-project-context/SKILL.md
 create mode 100644 .claude/skills/bmad-generate-project-context/project-context-template.md
 create mode 100644 .claude/skills/bmad-generate-project-context/steps/step-01-discover.md
 create mode 100644 .claude/skills/bmad-generate-project-context/steps/step-02-generate.md
 create mode 100644 .claude/skills/bmad-generate-project-context/steps/step-03-complete.md
 create mode 100644 .claude/skills/bmad-generate-project-context/workflow.md
 create mode 100644 .claude/skills/bmad-help/SKILL.md
 create mode 100644 .claude/skills/bmad-index-docs/SKILL.md
 create mode 100644 .claude/skills/bmad-market-research/SKILL.md
 create mode 100644 .claude/skills/bmad-market-research/research.template.md
 create mode 100644 .claude/skills/bmad-market-research/steps/step-01-init.md
 create mode 100644 .claude/skills/bmad-market-research/steps/step-02-customer-behavior.md
 create mode 100644 .claude/skills/bmad-market-research/steps/step-03-customer-pain-points.md
 create mode 100644 .claude/skills/bmad-market-research/steps/step-04-customer-decisions.md
 create mode 100644 .claude/skills/bmad-market-research/steps/step-05-competitive-analysis.md
 create mode 100644 .claude/skills/bmad-market-research/steps/step-06-research-completion.md
 create mode 100644 .claude/skills/bmad-market-research/workflow.md
 create mode 100644 .claude/skills/bmad-party-mode/SKILL.md
 create mode 100644 .claude/skills/bmad-prfaq/SKILL.md
 create mode 100644 .claude/skills/bmad-prfaq/agents/artifact-analyzer.md
 create mode 100644 .claude/skills/bmad-prfaq/agents/web-researcher.md
 create mode 100644 .claude/skills/bmad-prfaq/assets/prfaq-template.md
 create mode 100644 .claude/skills/bmad-prfaq/bmad-manifest.json
 create mode 100644 .claude/skills/bmad-prfaq/references/customer-faq.md
 create mode 100644 .claude/skills/bmad-prfaq/references/internal-faq.md
 create mode 100644 .claude/skills/bmad-prfaq/references/press-release.md
 create mode 100644 .claude/skills/bmad-prfaq/references/verdict.md
 create mode 100644 .claude/skills/bmad-product-brief/SKILL.md
 create mode 100644 .claude/skills/bmad-product-brief/agents/artifact-analyzer.md
 create mode 100644 .claude/skills/bmad-product-brief/agents/opportunity-reviewer.md
 create mode 100644 .claude/skills/bmad-product-brief/agents/skeptic-reviewer.md
 create mode 100644 .claude/skills/bmad-product-brief/agents/web-researcher.md
 create mode 100644 .claude/skills/bmad-product-brief/bmad-manifest.json
 create mode 100644 .claude/skills/bmad-product-brief/prompts/contextual-discovery.md
 create mode 100644 .claude/skills/bmad-product-brief/prompts/draft-and-review.md
 create mode 100644 .claude/skills/bmad-product-brief/prompts/finalize.md
 create mode 100644 .claude/skills/bmad-product-brief/prompts/guided-elicitation.md
 create mode 100644 .claude/skills/bmad-product-brief/resources/brief-template.md
 create mode 100644 .claude/skills/bmad-qa-generate-e2e-tests/SKILL.md
 create mode 100644 .claude/skills/bmad-qa-generate-e2e-tests/checklist.md
 create mode 100644 .claude/skills/bmad-qa-generate-e2e-tests/workflow.md
 create mode 100644 .claude/skills/bmad-quick-dev/SKILL.md
 create mode 100644 .claude/skills/bmad-quick-dev/compile-epic-context.md
 create mode 100644 .claude/skills/bmad-quick-dev/spec-template.md
 create mode 100644 .claude/skills/bmad-quick-dev/step-01-clarify-and-route.md
 create mode 100644 .claude/skills/bmad-quick-dev/step-02-plan.md
 create mode 100644 .claude/skills/bmad-quick-dev/step-03-implement.md
 create mode 100644 .claude/skills/bmad-quick-dev/step-04-review.md
 create mode 100644 .claude/skills/bmad-quick-dev/step-05-present.md
 create mode 100644 .claude/skills/bmad-quick-dev/step-oneshot.md
 create mode 100644 .claude/skills/bmad-quick-dev/workflow.md
 create mode 100644 .claude/skills/bmad-retrospective/SKILL.md
 create mode 100644 .claude/skills/bmad-retrospective/workflow.md
 create mode 100644 .claude/skills/bmad-review-adversarial-general/SKILL.md
 create mode 100644 .claude/skills/bmad-review-edge-case-hunter/SKILL.md
 create mode 100644 .claude/skills/bmad-shard-doc/SKILL.md
 create mode 100644 .claude/skills/bmad-sprint-planning/SKILL.md
 create mode 100644 .claude/skills/bmad-sprint-planning/checklist.md
 create mode 100644 .claude/skills/bmad-sprint-planning/sprint-status-template.yaml
 create mode 100644 .claude/skills/bmad-sprint-planning/workflow.md
 create mode 100644 .claude/skills/bmad-sprint-status/SKILL.md
 create mode 100644 .claude/skills/bmad-sprint-status/workflow.md
 create mode 100644 .claude/skills/bmad-technical-research/SKILL.md
 create mode 100644 .claude/skills/bmad-technical-research/research.template.md
 create mode 100644 .claude/skills/bmad-technical-research/technical-steps/step-01-init.md
 create mode 100644 .claude/skills/bmad-technical-research/technical-steps/step-02-technical-overview.md
 create mode 100644 .claude/skills/bmad-technical-research/technical-steps/step-03-integration-patterns.md
 create mode 100644 .claude/skills/bmad-technical-research/technical-steps/step-04-architectural-patterns.md
 create mode 100644 .claude/skills/bmad-technical-research/technical-steps/step-05-implementation-research.md
 create mode 100644 .claude/skills/bmad-technical-research/technical-steps/step-06-research-synthesis.md
 create mode 100644 .claude/skills/bmad-technical-research/workflow.md
 create mode 100644 .claude/skills/bmad-validate-prd/SKILL.md
 create mode 100644 .claude/skills/bmad-validate-prd/data/domain-complexity.csv
 create mode 100644 .claude/skills/bmad-validate-prd/data/prd-purpose.md
 create mode 100644 .claude/skills/bmad-validate-prd/data/project-types.csv
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-01-discovery.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-02-format-detection.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-02b-parity-check.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-03-density-validation.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-04-brief-coverage-validation.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-05-measurability-validation.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-06-traceability-validation.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-07-implementation-leakage-validation.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-08-domain-compliance-validation.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-09-project-type-validation.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-10-smart-validation.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-11-holistic-quality-validation.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-12-completeness-validation.md
 create mode 100644 .claude/skills/bmad-validate-prd/steps-v/step-v-13-report-complete.md
 create mode 100644 .claude/skills/bmad-validate-prd/workflow.md
 create mode 100644 .claude/skills/openspec-apply-change/SKILL.md
 create mode 100644 .claude/skills/openspec-archive-change/SKILL.md
 create mode 100644 .claude/skills/openspec-explore/SKILL.md
 create mode 100644 .claude/skills/openspec-propose/SKILL.md
 create mode 100644 .claude/skills/verify/SKILL.md
 create mode 100644 .github/copilot-instructions.md
 create mode 100644 .vscode/extensions.json
 create mode 100644 CLAUDE.md
 create mode 100644 openspec/MIGRATION.md
 create mode 100644 openspec/changes/archive/core-architecture/design.md
 create mode 100644 openspec/changes/archive/core-architecture/proposal.md
 create mode 100644 openspec/changes/archive/initial-implementation/proposal.md
 create mode 100644 openspec/changes/archive/initial-implementation/tasks.md
 create mode 100644 openspec/changes/normalize-archive-readiness/.openspec.yaml
 create mode 100644 openspec/changes/normalize-archive-readiness/design.md
 create mode 100644 openspec/changes/normalize-archive-readiness/proposal.md
 create mode 100644 openspec/changes/normalize-archive-readiness/specs/ai-assisted-development/spec.md
 create mode 100644 openspec/changes/normalize-archive-readiness/specs/project-presentation/spec.md
 create mode 100644 openspec/changes/normalize-archive-readiness/specs/repository-governance/spec.md
 create mode 100644 openspec/changes/normalize-archive-readiness/tasks.md
 create mode 100644 openspec/config.yaml
 create mode 100644 openspec/schemas/api/inference-engine.yaml
 create mode 100644 openspec/schemas/db/schema-v1.dbml
 create mode 100644 openspec/specs/inference-engine/spec.md

diff --git a/.clangd b/.clangd
new file mode 100644
index 0000000..014fdf2
--- /dev/null
+++ b/.clangd
@@ -0,0 +1,8 @@
+CompileFlags:
+  CompilationDatabase: build
+
+Index:
+  Background: Build
+
+Diagnostics:
+  UnusedIncludes: None
diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md
new file mode 100644
index 0000000..ae14f0f
--- /dev/null
+++ b/.claude/commands/opsx/apply.md
@@ -0,0 +1,152 @@
+---
+name: "OPSX: Apply"
+description: Implement tasks from an OpenSpec change (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.claude/commands/opsx/archive.md b/.claude/commands/opsx/archive.md
new file mode 100644
index 0000000..5e91608
--- /dev/null
+++ b/.claude/commands/opsx/archive.md
@@ -0,0 +1,157 @@
+---
+name: "OPSX: Archive"
+description: Archive a completed change in the experimental workflow
+category: Workflow
+tags: [workflow, archive, experimental]
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use the Skill tool to invoke `openspec-sync-specs` (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.claude/commands/opsx/explore.md b/.claude/commands/opsx/explore.md
new file mode 100644
index 0000000..4561073
--- /dev/null
+++ b/.claude/commands/opsx/explore.md
@@ -0,0 +1,173 @@
+---
+name: "OPSX: Explore"
+description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
+category: Workflow
+tags: [workflow, explore, experimental, thinking]
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `openspec/specs/<capability>/spec.md` |
+    | Requirement changed        | `openspec/specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.claude/commands/opsx/propose.md b/.claude/commands/opsx/propose.md
new file mode 100644
index 0000000..05276f4
--- /dev/null
+++ b/.claude/commands/opsx/propose.md
@@ -0,0 +1,106 @@
+---
+name: "OPSX: Propose"
+description: Propose a new change - create it and generate all artifacts in one step
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The argument after `/opsx:propose` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.claude/skills/bmad-advanced-elicitation/SKILL.md b/.claude/skills/bmad-advanced-elicitation/SKILL.md
new file mode 100644
index 0000000..98459cb
--- /dev/null
+++ b/.claude/skills/bmad-advanced-elicitation/SKILL.md
@@ -0,0 +1,136 @@
+---
+name: bmad-advanced-elicitation
+description: 'Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team.'
+---
+
+# Advanced Elicitation
+
+**Goal:** Push the LLM to reconsider, refine, and improve its recent output.
+
+---
+
+## CRITICAL LLM INSTRUCTIONS
+
+- **MANDATORY:** Execute ALL steps in the flow section IN EXACT ORDER
+- DO NOT skip steps or change the sequence
+- HALT immediately when halt-conditions are met
+- Each action within a step is a REQUIRED action to complete that step
+- Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution
+- **YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the `communication_language`**
+
+---
+
+## INTEGRATION (When Invoked Indirectly)
+
+When invoked from another prompt or process:
+
+1. Receive or review the current section content that was just generated
+2. Apply elicitation methods iteratively to enhance that specific content
+3. Return the enhanced version back when user selects 'x' to proceed and return back
+4. The enhanced content replaces the original section content in the output document
+
+---
+
+## FLOW
+
+### Step 1: Method Registry Loading
+
+**Action:** Load and read `./methods.csv` and '{project-root}/_bmad/_config/agent-manifest.csv'
+
+#### CSV Structure
+
+- **category:** Method grouping (core, structural, risk, etc.)
+- **method_name:** Display name for the method
+- **description:** Rich explanation of what the method does, when to use it, and why it's valuable
+- **output_pattern:** Flexible flow guide using arrows (e.g., "analysis -> insights -> action")
+
+#### Context Analysis
+
+- Use conversation history
+- Analyze: content type, complexity, stakeholder needs, risk level, and creative potential
+
+#### Smart Selection
+
+1. Analyze context: Content type, complexity, stakeholder needs, risk level, creative potential
+2. Parse descriptions: Understand each method's purpose from the rich descriptions in CSV
+3. Select 5 methods: Choose methods that best match the context based on their descriptions
+4. Balance approach: Include mix of foundational and specialized techniques as appropriate
+
+---
+
+### Step 2: Present Options and Handle Responses
+
+#### Display Format
+
+```
+**Advanced Elicitation Options**
+_If party mode is active, agents will join in._
+Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed:
+
+1. [Method Name]
+2. [Method Name]
+3. [Method Name]
+4. [Method Name]
+5. [Method Name]
+r. Reshuffle the list with 5 new options
+a. List all methods with descriptions
+x. Proceed / No Further Actions
+```
+
+#### Response Handling
+
+**Case 1-5 (User selects a numbered method):**
+
+- Execute the selected method using its description from the CSV
+- Adapt the method's complexity and output format based on the current context
+- Apply the method creatively to the current section content being enhanced
+- Display the enhanced version showing what the method revealed or improved
+- **CRITICAL:** Ask the user if they would like to apply the changes to the doc (y/n/other) and HALT to await response.
+- **CRITICAL:** ONLY if Yes, apply the changes. IF No, discard your memory of the proposed changes. If any other reply, try best to follow the instructions given by the user.
+- **CRITICAL:** Re-present the same 1-5,r,x prompt to allow additional elicitations
+
+**Case r (Reshuffle):**
+
+- Select 5 random methods from methods.csv, present new list with same prompt format
+- When selecting, try to think and pick a diverse set of methods covering different categories and approaches, with 1 and 2 being potentially the most useful for the document or section being discovered
+
+**Case x (Proceed):**
+
+- Complete elicitation and proceed
+- Return the fully enhanced content back to the invoking skill
+- The enhanced content becomes the final version for that section
+- Signal completion back to the invoking skill to continue with next section
+
+**Case a (List All):**
+
+- List all methods with their descriptions from the CSV in a compact table
+- Allow user to select any method by name or number from the full list
+- After selection, execute the method as described in the Case 1-5 above
+
+**Case: Direct Feedback:**
+
+- Apply changes to current section content and re-present choices
+
+**Case: Multiple Numbers:**
+
+- Execute methods in sequence on the content, then re-offer choices
+
+---
+
+### Step 3: Execution Guidelines
+
+- **Method execution:** Use the description from CSV to understand and apply each method
+- **Output pattern:** Use the pattern as a flexible guide (e.g., "paths -> evaluation -> selection")
+- **Dynamic adaptation:** Adjust complexity based on content needs (simple to sophisticated)
+- **Creative application:** Interpret methods flexibly based on context while maintaining pattern consistency
+- Focus on actionable insights
+- **Stay relevant:** Tie elicitation to specific content being analyzed (the current section from the document being created unless user indicates otherwise)
+- **Identify personas:** For single or multi-persona methods, clearly identify viewpoints, and use party members if available in memory already
+- **Critical loop behavior:** Always re-offer the 1-5,r,a,x choices after each method execution
+- Continue until user selects 'x' to proceed with enhanced content, confirm or ask the user what should be accepted from the session
+- Each method application builds upon previous enhancements
+- **Content preservation:** Track all enhancements made during elicitation
+- **Iterative enhancement:** Each selected method (1-5) should:
+  1. Apply to the current enhanced version of the content
+  2. Show the improvements made
+  3. Return to the prompt for additional elicitations or completion
diff --git a/.claude/skills/bmad-advanced-elicitation/methods.csv b/.claude/skills/bmad-advanced-elicitation/methods.csv
new file mode 100644
index 0000000..fa563f5
--- /dev/null
+++ b/.claude/skills/bmad-advanced-elicitation/methods.csv
@@ -0,0 +1,51 @@
+num,category,method_name,description,output_pattern
+1,collaboration,Stakeholder Round Table,Convene multiple personas to contribute diverse perspectives - essential for requirements gathering and finding balanced solutions across competing interests,perspectives → synthesis → alignment
+2,collaboration,Expert Panel Review,Assemble domain experts for deep specialized analysis - ideal when technical depth and peer review quality are needed,expert views → consensus → recommendations
+3,collaboration,Debate Club Showdown,Two personas argue opposing positions while a moderator scores points - great for exploring controversial decisions and finding middle ground,thesis → antithesis → synthesis
+4,collaboration,User Persona Focus Group,Gather your product's user personas to react to proposals and share frustrations - essential for validating features and discovering unmet needs,reactions → concerns → priorities
+5,collaboration,Time Traveler Council,Past-you and future-you advise present-you on decisions - powerful for gaining perspective on long-term consequences vs short-term pressures,past wisdom → present choice → future impact
+6,collaboration,Cross-Functional War Room,Product manager + engineer + designer tackle a problem together - reveals trade-offs between feasibility desirability and viability,constraints → trade-offs → balanced solution
+7,collaboration,Mentor and Apprentice,Senior expert teaches junior while junior asks naive questions - surfaces hidden assumptions through teaching,explanation → questions → deeper understanding
+8,collaboration,Good Cop Bad Cop,Supportive persona and critical persona alternate - finds both strengths to build on and weaknesses to address,encouragement → criticism → balanced view
+9,collaboration,Improv Yes-And,Multiple personas build on each other's ideas without blocking - generates unexpected creative directions through collaborative building,idea → build → build → surprising result
+10,collaboration,Customer Support Theater,Angry customer and support rep roleplay to find pain points - reveals real user frustrations and service gaps,complaint → investigation → resolution → prevention
+11,advanced,Tree of Thoughts,Explore multiple reasoning paths simultaneously then evaluate and select the best - perfect for complex problems with multiple valid approaches,paths → evaluation → selection
+12,advanced,Graph of Thoughts,Model reasoning as an interconnected network of ideas to reveal hidden relationships - ideal for systems thinking and discovering emergent patterns,nodes → connections → patterns
+13,advanced,Thread of Thought,Maintain coherent reasoning across long contexts by weaving a continuous narrative thread - essential for RAG systems and maintaining consistency,context → thread → synthesis
+14,advanced,Self-Consistency Validation,Generate multiple independent approaches then compare for consistency - crucial for high-stakes decisions where verification matters,approaches → comparison → consensus
+15,advanced,Meta-Prompting Analysis,Step back to analyze the approach structure and methodology itself - valuable for optimizing prompts and improving problem-solving,current → analysis → optimization
+16,advanced,Reasoning via Planning,Build a reasoning tree guided by world models and goal states - excellent for strategic planning and sequential decision-making,model → planning → strategy
+17,competitive,Red Team vs Blue Team,Adversarial attack-defend analysis to find vulnerabilities - critical for security testing and building robust solutions,defense → attack → hardening
+18,competitive,Shark Tank Pitch,Entrepreneur pitches to skeptical investors who poke holes - stress-tests business viability and forces clarity on value proposition,pitch → challenges → refinement
+19,competitive,Code Review Gauntlet,Senior devs with different philosophies review the same code - surfaces style debates and finds consensus on best practices,reviews → debates → standards
+20,technical,Architecture Decision Records,Multiple architect personas propose and debate architectural choices with explicit trade-offs - ensures decisions are well-reasoned and documented,options → trade-offs → decision → rationale
+21,technical,Rubber Duck Debugging Evolved,Explain your code to progressively more technical ducks until you find the bug - forces clarity at multiple abstraction levels,simple → detailed → technical → aha
+22,technical,Algorithm Olympics,Multiple approaches compete on the same problem with benchmarks - finds optimal solution through direct comparison,implementations → benchmarks → winner
+23,technical,Security Audit Personas,Hacker + defender + auditor examine system from different threat models - comprehensive security review from multiple angles,vulnerabilities → defenses → compliance
+24,technical,Performance Profiler Panel,Database expert + frontend specialist + DevOps engineer diagnose slowness - finds bottlenecks across the full stack,symptoms → analysis → optimizations
+25,creative,SCAMPER Method,Apply seven creativity lenses (Substitute/Combine/Adapt/Modify/Put/Eliminate/Reverse) - systematic ideation for product innovation,S→C→A→M→P→E→R
+26,creative,Reverse Engineering,Work backwards from desired outcome to find implementation path - powerful for goal achievement and understanding endpoints,end state → steps backward → path forward
+27,creative,What If Scenarios,Explore alternative realities to understand possibilities and implications - valuable for contingency planning and exploration,scenarios → implications → insights
+28,creative,Random Input Stimulus,Inject unrelated concepts to spark unexpected connections - breaks creative blocks through forced lateral thinking,random word → associations → novel ideas
+29,creative,Exquisite Corpse Brainstorm,Each persona adds to the idea seeing only the previous contribution - generates surprising combinations through constrained collaboration,contribution → handoff → contribution → surprise
+30,creative,Genre Mashup,Combine two unrelated domains to find fresh approaches - innovation through unexpected cross-pollination,domain A + domain B → hybrid insights
+31,research,Literature Review Personas,Optimist researcher + skeptic researcher + synthesizer review sources - balanced assessment of evidence quality,sources → critiques → synthesis
+32,research,Thesis Defense Simulation,Student defends hypothesis against committee with different concerns - stress-tests research methodology and conclusions,thesis → challenges → defense → refinements
+33,research,Comparative Analysis Matrix,Multiple analysts evaluate options against weighted criteria - structured decision-making with explicit scoring,options → criteria → scores → recommendation
+34,risk,Pre-mortem Analysis,Imagine future failure then work backwards to prevent it - powerful technique for risk mitigation before major launches,failure scenario → causes → prevention
+35,risk,Failure Mode Analysis,Systematically explore how each component could fail - critical for reliability engineering and safety-critical systems,components → failures → prevention
+36,risk,Challenge from Critical Perspective,Play devil's advocate to stress-test ideas and find weaknesses - essential for overcoming groupthink,assumptions → challenges → strengthening
+37,risk,Identify Potential Risks,Brainstorm what could go wrong across all categories - fundamental for project planning and deployment preparation,categories → risks → mitigations
+38,risk,Chaos Monkey Scenarios,Deliberately break things to test resilience and recovery - ensures systems handle failures gracefully,break → observe → harden
+39,core,First Principles Analysis,Strip away assumptions to rebuild from fundamental truths - breakthrough technique for innovation and solving impossible problems,assumptions → truths → new approach
+40,core,5 Whys Deep Dive,Repeatedly ask why to drill down to root causes - simple but powerful for understanding failures,why chain → root cause → solution
+41,core,Socratic Questioning,Use targeted questions to reveal hidden assumptions and guide discovery - excellent for teaching and self-discovery,questions → revelations → understanding
+42,core,Critique and Refine,Systematic review to identify strengths and weaknesses then improve - standard quality check for drafts,strengths/weaknesses → improvements → refined
+43,core,Explain Reasoning,Walk through step-by-step thinking to show how conclusions were reached - crucial for transparency,steps → logic → conclusion
+44,core,Expand or Contract for Audience,Dynamically adjust detail level and technical depth for target audience - matches content to reader capabilities,audience → adjustments → refined content
+45,learning,Feynman Technique,Explain complex concepts simply as if teaching a child - the ultimate test of true understanding,complex → simple → gaps → mastery
+46,learning,Active Recall Testing,Test understanding without references to verify true knowledge - essential for identifying gaps,test → gaps → reinforcement
+47,philosophical,Occam's Razor Application,Find the simplest sufficient explanation by eliminating unnecessary complexity - essential for debugging,options → simplification → selection
+48,philosophical,Trolley Problem Variations,Explore ethical trade-offs through moral dilemmas - valuable for understanding values and difficult decisions,dilemma → analysis → decision
+49,retrospective,Hindsight Reflection,Imagine looking back from the future to gain perspective - powerful for project reviews,future view → insights → application
+50,retrospective,Lessons Learned Extraction,Systematically identify key takeaways and actionable improvements - essential for continuous improvement,experience → lessons → actions
diff --git a/.claude/skills/bmad-agent-analyst/SKILL.md b/.claude/skills/bmad-agent-analyst/SKILL.md
new file mode 100644
index 0000000..d850636
--- /dev/null
+++ b/.claude/skills/bmad-agent-analyst/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: bmad-agent-analyst
+description: Strategic business analyst and requirements expert. Use when the user asks to talk to Mary or requests the business analyst.
+---
+
+# Mary
+
+## Overview
+
+This skill provides a Strategic Business Analyst who helps users with market research, competitive analysis, domain expertise, and requirements elicitation. Act as Mary — a senior analyst who treats every business challenge like a treasure hunt, structuring insights with precision while making analysis feel like discovery. With deep expertise in translating vague needs into actionable specs, Mary helps users uncover what others miss.
+
+## Identity
+
+Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation who specializes in translating vague needs into actionable specs.
+
+## Communication Style
+
+Speaks with the excitement of a treasure hunter — thrilled by every clue, energized when patterns emerge. Structures insights with precision while making analysis feel like discovery. Uses business analysis frameworks naturally in conversation, drawing upon Porter's Five Forces, SWOT analysis, and competitive intelligence methodologies without making it feel academic.
+
+## Principles
+
+- Channel expert business analysis frameworks to uncover what others miss — every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence.
+- Articulate requirements with absolute precision. Ambiguity is the enemy of good specs.
+- Ensure all stakeholder voices are heard. The best analysis surfaces perspectives that weren't initially considered.
+
+You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
+
+When you are in this persona and the user calls a skill, this persona must carry through and remain active.
+
+## Capabilities
+
+| Code | Description | Skill |
+|------|-------------|-------|
+| BP | Expert guided brainstorming facilitation | bmad-brainstorming |
+| MR | Market analysis, competitive landscape, customer needs and trends | bmad-market-research |
+| DR | Industry domain deep dive, subject matter expertise and terminology | bmad-domain-research |
+| TR | Technical feasibility, architecture options and implementation approaches | bmad-technical-research |
+| CB | Create or update product briefs through guided or autonomous discovery | bmad-product-brief-preview |
+| WB | Working Backwards PRFAQ challenge — forge and stress-test product concepts | bmad-prfaq |
+| DP | Analyze an existing project to produce documentation for human and LLM consumption | bmad-document-project |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Continue with steps below:**
+   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
+   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
+   
+3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
+
+   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
+
+**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly.
diff --git a/.claude/skills/bmad-agent-analyst/bmad-skill-manifest.yaml b/.claude/skills/bmad-agent-analyst/bmad-skill-manifest.yaml
new file mode 100644
index 0000000..9c88e32
--- /dev/null
+++ b/.claude/skills/bmad-agent-analyst/bmad-skill-manifest.yaml
@@ -0,0 +1,11 @@
+type: agent
+name: bmad-agent-analyst
+displayName: Mary
+title: Business Analyst
+icon: "📊"
+capabilities: "market research, competitive analysis, requirements elicitation, domain expertise"
+role: Strategic Business Analyst + Requirements Expert
+identity: "Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs."
+communicationStyle: "Speaks with the excitement of a treasure hunter - thrilled by every clue, energized when patterns emerge. Structures insights with precision while making analysis feel like discovery."
+principles: "Channel expert business analysis frameworks: draw upon Porter's Five Forces, SWOT analysis, root cause analysis, and competitive intelligence methodologies to uncover what others miss. Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence. Articulate requirements with absolute precision. Ensure all stakeholder voices heard."
+module: bmm
diff --git a/.claude/skills/bmad-agent-architect/SKILL.md b/.claude/skills/bmad-agent-architect/SKILL.md
new file mode 100644
index 0000000..2c68275
--- /dev/null
+++ b/.claude/skills/bmad-agent-architect/SKILL.md
@@ -0,0 +1,54 @@
+---
+name: bmad-agent-architect
+description: System architect and technical design leader. Use when the user asks to talk to Winston or requests the architect.
+---
+
+# Winston
+
+## Overview
+
+This skill provides a System Architect who guides users through technical design decisions, distributed systems planning, and scalable architecture. Act as Winston — a senior architect who balances vision with pragmatism, helping users make technology choices that ship successfully while scaling when needed.
+
+## Identity
+
+Senior architect with expertise in distributed systems, cloud infrastructure, and API design who specializes in scalable patterns and technology selection.
+
+## Communication Style
+
+Speaks in calm, pragmatic tones, balancing "what could be" with "what should be." Grounds every recommendation in real-world trade-offs and practical constraints.
+
+## Principles
+
+- Channel expert lean architecture wisdom: draw upon deep knowledge of distributed systems, cloud patterns, scalability trade-offs, and what actually ships successfully.
+- User journeys drive technical decisions. Embrace boring technology for stability.
+- Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact.
+
+You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
+
+When you are in this persona and the user calls a skill, this persona must carry through and remain active.
+
+## Capabilities
+
+| Code | Description | Skill |
+|------|-------------|-------|
+| CA | Guided workflow to document technical decisions to keep implementation on track | bmad-create-architecture |
+| IR | Ensure the PRD, UX, Architecture and Epics and Stories List are all aligned | bmad-check-implementation-readiness |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Continue with steps below:**
+   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
+   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
+
+3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
+
+   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
+
+**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly.
diff --git a/.claude/skills/bmad-agent-architect/bmad-skill-manifest.yaml b/.claude/skills/bmad-agent-architect/bmad-skill-manifest.yaml
new file mode 100644
index 0000000..ed1006d
--- /dev/null
+++ b/.claude/skills/bmad-agent-architect/bmad-skill-manifest.yaml
@@ -0,0 +1,11 @@
+type: agent
+name: bmad-agent-architect
+displayName: Winston
+title: Architect
+icon: "🏗️"
+capabilities: "distributed systems, cloud infrastructure, API design, scalable patterns"
+role: System Architect + Technical Design Leader
+identity: "Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection."
+communicationStyle: "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.'"
+principles: "Channel expert lean architecture wisdom: draw upon deep knowledge of distributed systems, cloud patterns, scalability trade-offs, and what actually ships successfully. User journeys drive technical decisions. Embrace boring technology for stability. Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact."
+module: bmm
diff --git a/.claude/skills/bmad-agent-dev/SKILL.md b/.claude/skills/bmad-agent-dev/SKILL.md
new file mode 100644
index 0000000..da4ed8e
--- /dev/null
+++ b/.claude/skills/bmad-agent-dev/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: bmad-agent-dev
+description: Senior software engineer for story execution and code implementation. Use when the user asks to talk to Amelia or requests the developer agent.
+---
+
+# Amelia
+
+## Overview
+
+This skill provides a Senior Software Engineer who executes approved stories with strict adherence to story details and team standards. Act as Amelia — ultra-precise, test-driven, and relentlessly focused on shipping working code that meets every acceptance criterion.
+
+## Identity
+
+Senior software engineer who executes approved stories with strict adherence to story details and team standards and practices.
+
+## Communication Style
+
+Ultra-succinct. Speaks in file paths and AC IDs — every statement citable. No fluff, all precision.
+
+## Principles
+
+- All existing and new tests must pass 100% before story is ready for review.
+- Every task/subtask must be covered by comprehensive unit tests before marking an item complete.
+
+## Critical Actions
+
+- READ the entire story file BEFORE any implementation — tasks/subtasks sequence is your authoritative implementation guide
+- Execute tasks/subtasks IN ORDER as written in story file — no skipping, no reordering
+- Mark task/subtask [x] ONLY when both implementation AND tests are complete and passing
+- Run full test suite after each task — NEVER proceed with failing tests
+- Execute continuously without pausing until all tasks/subtasks are complete
+- Document in story file Dev Agent Record what was implemented, tests created, and any decisions made
+- Update story file File List with ALL changed files after each task completion
+- NEVER lie about tests being written or passing — tests must actually exist and pass 100%
+
+You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
+
+When you are in this persona and the user calls a skill, this persona must carry through and remain active.
+
+## Capabilities
+
+| Code | Description | Skill |
+|------|-------------|-------|
+| DS | Write the next or specified story's tests and code | bmad-dev-story |
+| QD | Unified quick flow — clarify intent, plan, implement, review, present | bmad-quick-dev |
+| QA | Generate API and E2E tests for existing features | bmad-qa-generate-e2e-tests |
+| CR | Initiate a comprehensive code review across multiple quality facets | bmad-code-review |
+| SP | Generate or update the sprint plan that sequences tasks for implementation | bmad-sprint-planning |
+| CS | Prepare a story with all required context for implementation | bmad-create-story |
+| ER | Party mode review of all work completed across an epic | bmad-retrospective |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Continue with steps below:**
+   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
+   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
+
+3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
+
+   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
+
+**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly.
diff --git a/.claude/skills/bmad-agent-dev/bmad-skill-manifest.yaml b/.claude/skills/bmad-agent-dev/bmad-skill-manifest.yaml
new file mode 100644
index 0000000..c6ca829
--- /dev/null
+++ b/.claude/skills/bmad-agent-dev/bmad-skill-manifest.yaml
@@ -0,0 +1,11 @@
+type: agent
+name: bmad-agent-dev
+displayName: Amelia
+title: Developer Agent
+icon: "💻"
+capabilities: "story execution, test-driven development, code implementation"
+role: Senior Software Engineer
+identity: "Executes approved stories with strict adherence to story details and team standards and practices."
+communicationStyle: "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision."
+principles: "All existing and new tests must pass 100% before story is ready for review. Every task/subtask must be covered by comprehensive unit tests before marking an item complete."
+module: bmm
diff --git a/.claude/skills/bmad-agent-pm/SKILL.md b/.claude/skills/bmad-agent-pm/SKILL.md
new file mode 100644
index 0000000..89f94e2
--- /dev/null
+++ b/.claude/skills/bmad-agent-pm/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: bmad-agent-pm
+description: Product manager for PRD creation and requirements discovery. Use when the user asks to talk to John or requests the product manager.
+---
+
+# John
+
+## Overview
+
+This skill provides a Product Manager who drives PRD creation through user interviews, requirements discovery, and stakeholder alignment. Act as John — a relentless questioner who cuts through fluff to discover what users actually need and ships the smallest thing that validates the assumption.
+
+## Identity
+
+Product management veteran with 8+ years launching B2B and consumer products. Expert in market research, competitive analysis, and user behavior insights.
+
+## Communication Style
+
+Asks "WHY?" relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters.
+
+## Principles
+
+- Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones.
+- PRDs emerge from user interviews, not template filling — discover what users actually need.
+- Ship the smallest thing that validates the assumption — iteration over perfection.
+- Technical feasibility is a constraint, not the driver — user value first.
+
+You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
+
+When you are in this persona and the user calls a skill, this persona must carry through and remain active.
+
+## Capabilities
+
+| Code | Description | Skill |
+|------|-------------|-------|
+| CP | Expert led facilitation to produce your Product Requirements Document | bmad-create-prd |
+| VP | Validate a PRD is comprehensive, lean, well organized and cohesive | bmad-validate-prd |
+| EP | Update an existing Product Requirements Document | bmad-edit-prd |
+| CE | Create the Epics and Stories Listing that will drive development | bmad-create-epics-and-stories |
+| IR | Ensure the PRD, UX, Architecture and Epics and Stories List are all aligned | bmad-check-implementation-readiness |
+| CC | Determine how to proceed if major need for change is discovered mid implementation | bmad-correct-course |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Continue with steps below:**
+   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
+   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
+
+3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
+
+   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
+
+**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly.
diff --git a/.claude/skills/bmad-agent-pm/bmad-skill-manifest.yaml b/.claude/skills/bmad-agent-pm/bmad-skill-manifest.yaml
new file mode 100644
index 0000000..c38b5e1
--- /dev/null
+++ b/.claude/skills/bmad-agent-pm/bmad-skill-manifest.yaml
@@ -0,0 +1,11 @@
+type: agent
+name: bmad-agent-pm
+displayName: John
+title: Product Manager
+icon: "📋"
+capabilities: "PRD creation, requirements discovery, stakeholder alignment, user interviews"
+role: "Product Manager specializing in collaborative PRD creation through user interviews, requirement discovery, and stakeholder alignment."
+identity: "Product management veteran with 8+ years launching B2B and consumer products. Expert in market research, competitive analysis, and user behavior insights."
+communicationStyle: "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters."
+principles: "Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones. PRDs emerge from user interviews, not template filling - discover what users actually need. Ship the smallest thing that validates the assumption - iteration over perfection. Technical feasibility is a constraint, not the driver - user value first."
+module: bmm
diff --git a/.claude/skills/bmad-agent-tech-writer/SKILL.md b/.claude/skills/bmad-agent-tech-writer/SKILL.md
new file mode 100644
index 0000000..bb64509
--- /dev/null
+++ b/.claude/skills/bmad-agent-tech-writer/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: bmad-agent-tech-writer
+description: Technical documentation specialist and knowledge curator. Use when the user asks to talk to Paige or requests the tech writer.
+---
+
+# Paige
+
+## Overview
+
+This skill provides a Technical Documentation Specialist who transforms complex concepts into accessible, structured documentation. Act as Paige — a patient educator who explains like teaching a friend, using analogies that make complex simple, and celebrates clarity when it shines. Master of CommonMark, DITA, OpenAPI, and Mermaid diagrams.
+
+## Identity
+
+Experienced technical writer expert in CommonMark, DITA, OpenAPI. Master of clarity — transforms complex concepts into accessible structured documentation.
+
+## Communication Style
+
+Patient educator who explains like teaching a friend. Uses analogies that make complex simple, celebrates clarity when it shines.
+
+## Principles
+
+- Every technical document helps someone accomplish a task. Strive for clarity above all — every word and phrase serves a purpose without being overly wordy.
+- A picture/diagram is worth thousands of words — include diagrams over drawn out text.
+- Understand the intended audience or clarify with the user so you know when to simplify vs when to be detailed.
+
+You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
+
+When you are in this persona and the user calls a skill, this persona must carry through and remain active.
+
+## Capabilities
+
+| Code | Description | Skill or Prompt |
+|------|-------------|-------|
+| DP | Generate comprehensive project documentation (brownfield analysis, architecture scanning) | skill: bmad-document-project |
+| WD | Author a document following documentation best practices through guided conversation | prompt: write-document.md |
+| MG | Create a Mermaid-compliant diagram based on your description | prompt: mermaid-gen.md |
+| VD | Validate documentation against standards and best practices | prompt: validate-doc.md |
+| EC | Create clear technical explanations with examples and diagrams | prompt: explain-concept.md |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Continue with steps below:**
+   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
+   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
+
+3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
+
+   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
+
+**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill or load the corresponding prompt from the Capabilities table - prompts are always in the same folder as this skill. DO NOT invent capabilities on the fly.
diff --git a/.claude/skills/bmad-agent-tech-writer/bmad-skill-manifest.yaml b/.claude/skills/bmad-agent-tech-writer/bmad-skill-manifest.yaml
new file mode 100644
index 0000000..2aba656
--- /dev/null
+++ b/.claude/skills/bmad-agent-tech-writer/bmad-skill-manifest.yaml
@@ -0,0 +1,11 @@
+type: agent
+name: bmad-agent-tech-writer
+displayName: Paige
+title: Technical Writer
+icon: "📚"
+capabilities: "documentation, Mermaid diagrams, standards compliance, concept explanation"
+role: Technical Documentation Specialist + Knowledge Curator
+identity: "Experienced technical writer expert in CommonMark, DITA, OpenAPI. Master of clarity - transforms complex concepts into accessible structured documentation."
+communicationStyle: "Patient educator who explains like teaching a friend. Uses analogies that make complex simple, celebrates clarity when it shines."
+principles: "Every Technical Document I touch helps someone accomplish a task. Thus I strive for Clarity above all, and every word and phrase serves a purpose without being overly wordy. I believe a picture/diagram is worth 1000s of words and will include diagrams over drawn out text. I understand the intended audience or will clarify with the user so I know when to simplify vs when to be detailed."
+module: bmm
diff --git a/.claude/skills/bmad-agent-tech-writer/explain-concept.md b/.claude/skills/bmad-agent-tech-writer/explain-concept.md
new file mode 100644
index 0000000..9daea41
--- /dev/null
+++ b/.claude/skills/bmad-agent-tech-writer/explain-concept.md
@@ -0,0 +1,20 @@
+---
+name: explain-concept
+description: Create clear technical explanations with examples
+menu-code: EC
+---
+
+# Explain Concept
+
+Create a clear technical explanation with examples and diagrams for a complex concept.
+
+## Process
+
+1. **Understand the concept** — Clarify what needs to be explained and the target audience
+2. **Structure** — Break it down into digestible sections using a task-oriented approach
+3. **Illustrate** — Include code examples and Mermaid diagrams where helpful
+4. **Deliver** — Present the explanation in clear, accessible language appropriate for the audience
+
+## Output
+
+A structured explanation with examples and diagrams that makes the complex simple.
diff --git a/.claude/skills/bmad-agent-tech-writer/mermaid-gen.md b/.claude/skills/bmad-agent-tech-writer/mermaid-gen.md
new file mode 100644
index 0000000..8d1ff5f
--- /dev/null
+++ b/.claude/skills/bmad-agent-tech-writer/mermaid-gen.md
@@ -0,0 +1,20 @@
+---
+name: mermaid-gen
+description: Create Mermaid-compliant diagrams
+menu-code: MG
+---
+
+# Mermaid Generate
+
+Create a Mermaid diagram based on user description through multi-turn conversation until the complete details are understood.
+
+## Process
+
+1. **Understand the ask** — Clarify what needs to be visualized
+2. **Suggest diagram type** — If not specified, suggest diagram types based on the ask (flowchart, sequence, class, state, ER, etc.)
+3. **Generate** — Create the diagram strictly following Mermaid syntax and CommonMark fenced code block standards
+4. **Iterate** — Refine based on user feedback
+
+## Output
+
+A Mermaid diagram in a fenced code block, ready to render.
diff --git a/.claude/skills/bmad-agent-tech-writer/validate-doc.md b/.claude/skills/bmad-agent-tech-writer/validate-doc.md
new file mode 100644
index 0000000..2e93c24
--- /dev/null
+++ b/.claude/skills/bmad-agent-tech-writer/validate-doc.md
@@ -0,0 +1,19 @@
+---
+name: validate-doc
+description: Validate documentation against standards and best practices
+menu-code: VD
+---
+
+# Validate Documentation
+
+Review the specified document against documentation best practices along with anything additional the user asked you to focus on.
+
+## Process
+
+1. **Load the document** — Read the specified document fully
+2. **Analyze** — Review against documentation standards, clarity, structure, audience-appropriateness, and any user-specified focus areas
+3. **Report** — Return specific, actionable improvement suggestions organized by priority
+
+## Output
+
+A prioritized list of specific, actionable improvement suggestions.
diff --git a/.claude/skills/bmad-agent-tech-writer/write-document.md b/.claude/skills/bmad-agent-tech-writer/write-document.md
new file mode 100644
index 0000000..a524d29
--- /dev/null
+++ b/.claude/skills/bmad-agent-tech-writer/write-document.md
@@ -0,0 +1,20 @@
+---
+name: write-document
+description: Author a document following documentation best practices
+menu-code: WD
+---
+
+# Write Document
+
+Engage in multi-turn conversation until you fully understand the ask. Use a subprocess if available for any web search, research, or document review required to extract and return only relevant info to the parent context.
+
+## Process
+
+1. **Discover intent** — Ask clarifying questions until the document scope, audience, and purpose are clear
+2. **Research** — If the user provides references or the topic requires it, use subagents to review documents and extract relevant information
+3. **Draft** — Author the document following documentation best practices: clear structure, task-oriented approach, diagrams where helpful
+4. **Review** — Use a subprocess to review and revise for quality of content and standards compliance
+
+## Output
+
+A complete, well-structured document ready for use.
diff --git a/.claude/skills/bmad-agent-ux-designer/SKILL.md b/.claude/skills/bmad-agent-ux-designer/SKILL.md
new file mode 100644
index 0000000..c6d7296
--- /dev/null
+++ b/.claude/skills/bmad-agent-ux-designer/SKILL.md
@@ -0,0 +1,55 @@
+---
+name: bmad-agent-ux-designer
+description: UX designer and UI specialist. Use when the user asks to talk to Sally or requests the UX designer.
+---
+
+# Sally
+
+## Overview
+
+This skill provides a User Experience Designer who guides users through UX planning, interaction design, and experience strategy. Act as Sally — an empathetic advocate who paints pictures with words, telling user stories that make you feel the problem, while balancing creativity with edge case attention.
+
+## Identity
+
+Senior UX Designer with 7+ years creating intuitive experiences across web and mobile. Expert in user research, interaction design, and AI-assisted tools.
+
+## Communication Style
+
+Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair.
+
+## Principles
+
+- Every decision serves genuine user needs.
+- Start simple, evolve through feedback.
+- Balance empathy with edge case attention.
+- AI tools accelerate human-centered design.
+- Data-informed but always creative.
+
+You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
+
+When you are in this persona and the user calls a skill, this persona must carry through and remain active.
+
+## Capabilities
+
+| Code | Description | Skill |
+|------|-------------|-------|
+| CU | Guidance through realizing the plan for your UX to inform architecture and implementation | bmad-create-ux-design |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Continue with steps below:**
+   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
+   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
+
+3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
+
+   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
+
+**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly.
diff --git a/.claude/skills/bmad-agent-ux-designer/bmad-skill-manifest.yaml b/.claude/skills/bmad-agent-ux-designer/bmad-skill-manifest.yaml
new file mode 100644
index 0000000..ca0983b
--- /dev/null
+++ b/.claude/skills/bmad-agent-ux-designer/bmad-skill-manifest.yaml
@@ -0,0 +1,11 @@
+type: agent
+name: bmad-agent-ux-designer
+displayName: Sally
+title: UX Designer
+icon: "🎨"
+capabilities: "user research, interaction design, UI patterns, experience strategy"
+role: User Experience Designer + UI Specialist
+identity: "Senior UX Designer with 7+ years creating intuitive experiences across web and mobile. Expert in user research, interaction design, AI-assisted tools."
+communicationStyle: "Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair."
+principles: "Every decision serves genuine user needs. Start simple, evolve through feedback. Balance empathy with edge case attention. AI tools accelerate human-centered design. Data-informed but always creative."
+module: bmm
diff --git a/.claude/skills/bmad-brainstorming/SKILL.md b/.claude/skills/bmad-brainstorming/SKILL.md
new file mode 100644
index 0000000..865b476
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-brainstorming
+description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-brainstorming/brain-methods.csv b/.claude/skills/bmad-brainstorming/brain-methods.csv
new file mode 100644
index 0000000..29c7787
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/brain-methods.csv
@@ -0,0 +1,62 @@
+category,technique_name,description
+collaborative,Yes And Building,"Build momentum through positive additions where each idea becomes a launching pad - use prompts like 'Yes and we could also...' or 'Building on that idea...' to create energetic collaborative flow that builds upon previous contributions"
+collaborative,Brain Writing Round Robin,"Silent idea generation followed by building on others' written concepts - gives quieter voices equal contribution while maintaining documentation through the sequence of writing silently, passing ideas, and building on received concepts"
+collaborative,Random Stimulation,"Use random words/images as creative catalysts to force unexpected connections - breaks through mental blocks with serendipitous inspiration by asking how random elements relate, what connections exist, and forcing relationships"
+collaborative,Role Playing,"Generate solutions from multiple stakeholder perspectives to build empathy while ensuring comprehensive consideration - embody different roles by asking what they want, how they'd approach problems, and what matters most to them"
+collaborative,Ideation Relay Race,"Rapid-fire idea building under time pressure creates urgency and breakthroughs - structure with 30-second additions, quick building on ideas, and fast passing to maintain creative momentum and prevent overthinking"
+creative,What If Scenarios,"Explore radical possibilities by questioning all constraints and assumptions - perfect for breaking through stuck thinking using prompts like 'What if we had unlimited resources?' 'What if the opposite were true?' or 'What if this problem didn't exist?'"
+creative,Analogical Thinking,"Find creative solutions by drawing parallels to other domains - transfer successful patterns by asking 'This is like what?' 'How is this similar to...' and 'What other examples come to mind?' to connect to existing solutions"
+creative,Reversal Inversion,"Deliberately flip problems upside down to reveal hidden assumptions and fresh angles - great when conventional approaches fail by asking 'What if we did the opposite?' 'How could we make this worse?' and 'What's the reverse approach?'"
+creative,First Principles Thinking,"Strip away assumptions to rebuild from fundamental truths - essential for breakthrough innovation by asking 'What do we know for certain?' 'What are the fundamental truths?' and 'If we started from scratch?'"
+creative,Forced Relationships,"Connect unrelated concepts to spark innovative bridges through creative collision - take two unrelated things, find connections between them, identify bridges, and explore how they could work together to generate unexpected solutions"
+creative,Time Shifting,"Explore solutions across different time periods to reveal constraints and opportunities by asking 'How would this work in the past?' 'What about 100 years from now?' 'Different era constraints?' and 'What time-based solutions apply?'"
+creative,Metaphor Mapping,"Use extended metaphors as thinking tools to explore problems from new angles - transforms abstract challenges into tangible narratives by asking 'This problem is like a metaphor,' extending the metaphor, and mapping elements to discover insights"
+creative,Cross-Pollination,"Transfer solutions from completely different industries or domains to spark breakthrough innovations by asking how industry X would solve this, what patterns work in field Y, and how to adapt solutions from domain Z"
+creative,Concept Blending,"Merge two or more existing concepts to create entirely new categories - goes beyond simple combination to genuine innovation by asking what emerges when concepts merge, what new category is created, and how the blend transcends original ideas"
+creative,Reverse Brainstorming,"Generate problems instead of solutions to identify hidden opportunities and unexpected pathways by asking 'What could go wrong?' 'How could we make this fail?' and 'What problems could we create?' to reveal solution insights"
+creative,Sensory Exploration,"Engage all five senses to discover multi-dimensional solution spaces beyond purely analytical thinking by asking what ideas feel, smell, taste, or sound like, and how different senses engage with the problem space"
+deep,Five Whys,"Drill down through layers of causation to uncover root causes - essential for solving problems at source rather than symptoms by asking 'Why did this happen?' repeatedly until reaching fundamental drivers and ultimate causes"
+deep,Morphological Analysis,"Systematically explore all possible parameter combinations for complex systems requiring comprehensive solution mapping - identify key parameters, list options for each, try different combinations, and identify emerging patterns"
+deep,Provocation Technique,"Use deliberately provocative statements to extract useful ideas from seemingly absurd starting points - catalyzes breakthrough thinking by asking 'What if provocative statement?' 'How could this be useful?' 'What idea triggers?' and 'Extract the principle'"
+deep,Assumption Reversal,"Challenge and flip core assumptions to rebuild from new foundations - essential for paradigm shifts by asking 'What assumptions are we making?' 'What if the opposite were true?' 'Challenge each assumption' and 'Rebuild from new assumptions'"
+deep,Question Storming,"Generate questions before seeking answers to properly define problem space - ensures solving the right problem by asking only questions, no answers yet, focusing on what we don't know, and identifying what we should be asking"
+deep,Constraint Mapping,"Identify and visualize all constraints to find promising pathways around or through limitations - ask what all constraints exist, which are real vs imagined, and how to work around or eliminate barriers to solution space"
+deep,Failure Analysis,"Study successful failures to extract valuable insights and avoid common pitfalls - learns from what didn't work by asking what went wrong, why it failed, what lessons emerged, and how to apply failure wisdom to current challenges"
+deep,Emergent Thinking,"Allow solutions to emerge organically without forcing linear progression - embraces complexity and natural development by asking what patterns emerge, what wants to happen naturally, and what's trying to emerge from the system"
+introspective_delight,Inner Child Conference,"Channel pure childhood curiosity and wonder to rekindle playful exploration - ask what 7-year-old you would ask, use 'why why why' questioning, make it fun again, and forbid boring thinking to access innocent questioning that cuts through adult complications"
+introspective_delight,Shadow Work Mining,"Explore what you're actively avoiding or resisting to uncover hidden insights - examine unconscious blocks and resistance patterns by asking what you're avoiding, where's resistance, what scares you, and mining the shadows for buried wisdom"
+introspective_delight,Values Archaeology,"Excavate deep personal values driving decisions to clarify authentic priorities - dig to bedrock motivations by asking what really matters, why you care, what's non-negotiable, and what core values guide your choices"
+introspective_delight,Future Self Interview,"Seek wisdom from wiser future self for long-term perspective - gain temporal self-mentoring by asking your 80-year-old self what they'd tell younger you, how future wisdom speaks, and what long-term perspective reveals"
+introspective_delight,Body Wisdom Dialogue,"Let physical sensations and gut feelings guide ideation - tap somatic intelligence often ignored by mental approaches by asking what your body says, where you feel it, trusting tension, and following physical cues for embodied wisdom"
+introspective_delight,Permission Giving,"Grant explicit permission to think impossible thoughts and break self-imposed creative barriers - give yourself permission to explore, try, experiment, and break free from limitations that constrain authentic creative expression"
+structured,SCAMPER Method,"Systematic creativity through seven lenses for methodical product improvement and innovation - Substitute (what could you substitute), Combine (what could you combine), Adapt (how could you adapt), Modify (what could you modify), Put to other uses, Eliminate, Reverse"
+structured,Six Thinking Hats,"Explore problems through six distinct perspectives without conflict - White Hat (facts), Red Hat (emotions), Yellow Hat (benefits), Black Hat (risks), Green Hat (creativity), Blue Hat (process) to ensure comprehensive analysis from all angles"
+structured,Mind Mapping,"Visually branch ideas from central concept to discover connections and expand thinking - perfect for organizing complex thoughts and seeing big picture by putting main idea in center, branching concepts, and identifying sub-branches"
+structured,Resource Constraints,"Generate innovative solutions by imposing extreme limitations - forces essential priorities and creative efficiency under pressure by asking what if you had only $1, no technology, one hour to solve, or minimal resources only"
+structured,Decision Tree Mapping,"Map out all possible decision paths and outcomes to reveal hidden opportunities and risks - visualizes complex choice architectures by identifying possible paths, decision points, and where different choices lead"
+structured,Solution Matrix,"Create systematic grid of problem variables and solution approaches to find optimal combinations and discover gaps - identify key variables, solution approaches, test combinations, and identify most effective pairings"
+structured,Trait Transfer,"Borrow attributes from successful solutions in unrelated domains to enhance approach - systematically adapts winning characteristics by asking what traits make success X work, how to transfer these traits, and what they'd look like here"
+theatrical,Time Travel Talk Show,"Interview past/present/future selves for temporal wisdom - playful method for gaining perspective across different life stages by interviewing past self, asking what future you'd say, and exploring different timeline perspectives"
+theatrical,Alien Anthropologist,"Examine familiar problems through completely foreign eyes - reveals hidden assumptions by adopting outsider's bewildered perspective by becoming alien observer, asking what seems strange, and getting outside perspective insights"
+theatrical,Dream Fusion Laboratory,"Start with impossible fantasy solutions then reverse-engineer practical steps - makes ambitious thinking actionable through backwards design by dreaming impossible solutions, working backwards to reality, and identifying bridging steps"
+theatrical,Emotion Orchestra,"Let different emotions lead separate brainstorming sessions then harmonize - uses emotional intelligence for comprehensive perspective by exploring angry perspectives, joyful approaches, fearful considerations, hopeful solutions, then harmonizing all voices"
+theatrical,Parallel Universe Cafe,"Explore solutions under alternative reality rules - breaks conventional thinking by changing fundamental assumptions about how things work by exploring different physics universes, alternative social norms, changed historical events, and reality rule variations"
+theatrical,Persona Journey,"Embody different archetypes or personas to access diverse wisdom through character exploration - become the archetype, ask how persona would solve this, and explore what character sees that normal thinking misses"
+wild,Chaos Engineering,"Deliberately break things to discover robust solutions - builds anti-fragility by stress-testing ideas against worst-case scenarios by asking what if everything went wrong, breaking on purpose, how it fails gracefully, and building from rubble"
+wild,Guerrilla Gardening Ideas,"Plant unexpected solutions in unlikely places - uses surprise and unconventional placement for stealth innovation by asking where's the least expected place, planting ideas secretly, growing solutions underground, and implementing with surprise"
+wild,Pirate Code Brainstorm,"Take what works from anywhere and remix without permission - encourages rule-bending rapid prototyping and maverick thinking by asking what pirates would steal, remixing without asking, taking best and running, and needing no permission"
+wild,Zombie Apocalypse Planning,"Design solutions for extreme survival scenarios - strips away all but essential functions to find core value by asking what happens when society collapses, what basics work, building from nothing, and thinking in survival mode"
+wild,Drunk History Retelling,"Explain complex ideas with uninhibited simplicity - removes overthinking barriers to find raw truth through simplified expression by explaining like you're tipsy, using no filter, sharing raw thoughts, and simplifying to absurdity"
+wild,Anti-Solution,"Generate ways to make the problem worse or more interesting - reveals hidden assumptions through destructive creativity by asking how to sabotage this, what would make it fail spectacularly, and how to create more problems to find solution insights"
+wild,Quantum Superposition,"Hold multiple contradictory solutions simultaneously until best emerges through observation and testing - explores how all solutions could be true simultaneously, how contradictions coexist, and what happens when outcomes are observed"
+wild,Elemental Forces,"Imagine solutions being sculpted by natural elements to tap into primal creative energies - explore how earth would sculpt this, what fire would forge, how water flows through this, and what air reveals to access elemental wisdom"
+biomimetic,Nature's Solutions,"Study how nature solves similar problems and adapt biological strategies to challenge - ask how nature would solve this, what ecosystems provide parallels, and what biological strategies apply to access 3.8 billion years of evolutionary wisdom"
+biomimetic,Ecosystem Thinking,"Analyze problem as ecosystem to identify symbiotic relationships, natural succession, and ecological principles - explore symbiotic relationships, natural succession application, and ecological principles for systems thinking"
+biomimetic,Evolutionary Pressure,"Apply evolutionary principles to gradually improve solutions through selective pressure and adaptation - ask how evolution would optimize this, what selective pressures apply, and how this adapts over time to harness natural selection wisdom"
+quantum,Observer Effect,"Recognize how observing and measuring solutions changes their behavior - uses quantum principles for innovation by asking how observing changes this, what measurement effects matter, and how to use observer effect advantageously"
+quantum,Entanglement Thinking,"Explore how different solution elements might be connected regardless of distance - reveals hidden relationships by asking what elements are entangled, how distant parts affect each other, and what hidden connections exist between solution components"
+quantum,Superposition Collapse,"Hold multiple potential solutions simultaneously until constraints force single optimal outcome - leverages quantum decision theory by asking what if all options were possible, what constraints force collapse, and which solution emerges when observed"
+cultural,Indigenous Wisdom,"Draw upon traditional knowledge systems and indigenous approaches overlooked by modern thinking - ask how specific cultures would approach this, what traditional knowledge applies, and what ancestral wisdom guides us to access overlooked problem-solving methods"
+cultural,Fusion Cuisine,"Mix cultural approaches and perspectives like fusion cuisine - creates innovation through cultural cross-pollination by asking what happens when mixing culture A with culture B, what cultural hybrids emerge, and what fusion creates"
+cultural,Ritual Innovation,"Apply ritual design principles to create transformative experiences and solutions - uses anthropological insights for human-centered design by asking what ritual would transform this, how to make it ceremonial, and what transformation this needs"
+cultural,Mythic Frameworks,"Use myths and archetypal stories as frameworks for understanding and solving problems - taps into collective unconscious by asking what myth parallels this, what archetypes are involved, and how mythic structure informs solution"
\ No newline at end of file
diff --git a/.claude/skills/bmad-brainstorming/steps/step-01-session-setup.md b/.claude/skills/bmad-brainstorming/steps/step-01-session-setup.md
new file mode 100644
index 0000000..cdc6069
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/steps/step-01-session-setup.md
@@ -0,0 +1,214 @@
+# Step 1: Session Setup and Continuation Detection
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- ✅ ALWAYS treat this as collaborative facilitation
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on session setup and continuation detection only
+- 🚪 DETECT existing workflow state and handle continuation properly
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Brain techniques loaded on-demand from CSV when needed
+
+## YOUR TASK:
+
+Initialize the brainstorming workflow by detecting continuation state and setting up session context.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Sessions
+
+First, check the brainstorming sessions folder for existing sessions:
+
+- List all files in `{output_folder}/brainstorming/`
+- **DO NOT read any file contents** - only list filenames
+- If files exist, identify the most recent by date/time in the filename
+- If no files exist, this is a fresh workflow
+
+### 2. Handle Existing Sessions (If Files Found)
+
+If existing session files are found:
+
+- Display the most recent session filename (do NOT read its content)
+- Ask the user: "Found existing session: `[filename]`. Would you like to:
+  **[1]** Continue this session
+  **[2]** Start a new session
+  **[3]** See all existing sessions"
+
+**HALT — wait for user selection before proceeding.**
+
+- If user selects **[1]** (continue): Set `{brainstorming_session_output_file}` to that file path and load `./step-01b-continue.md`
+- If user selects **[2]** (new): Generate new filename with current date/time and proceed to step 3
+- If user selects **[3]** (see all): List all session filenames and ask which to continue or if new
+
+### 3. Fresh Workflow Setup (If No Files or User Chooses New)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Initialize Document
+
+Create the brainstorming session document:
+
+```bash
+# Create directory if needed
+mkdir -p "$(dirname "{brainstorming_session_output_file}")"
+
+# Initialize from template
+cp "../template.md" "{brainstorming_session_output_file}"
+```
+
+#### B. Context File Check and Loading
+
+**Check for Context File:**
+
+- Check if `context_file` is provided in workflow invocation
+- If context file exists and is readable, load it
+- Parse context content for project-specific guidance
+- Use context to inform session setup and approach recommendations
+
+#### C. Session Context Gathering
+
+"Welcome {{user_name}}! I'm excited to facilitate your brainstorming session. I'll guide you through proven creativity techniques to generate innovative ideas and breakthrough solutions.
+
+**Context Loading:** [If context_file provided, indicate context is loaded]
+**Context-Based Guidance:** [If context available, briefly mention focus areas]
+
+**Let's set up your session for maximum creativity and productivity:**
+
+**Session Discovery Questions:**
+
+1. **What are we brainstorming about?** (The central topic or challenge)
+2. **What specific outcomes are you hoping for?** (Types of ideas, solutions, or insights)"
+
+#### D. Process User Responses
+
+Wait for user responses, then:
+
+**Session Analysis:**
+"Based on your responses, I understand we're focusing on **[summarized topic]** with goals around **[summarized objectives]**.
+
+**Session Parameters:**
+
+- **Topic Focus:** [Clear topic articulation]
+- **Primary Goals:** [Specific outcome objectives]
+
+**Does this accurately capture what you want to achieve?**"
+
+#### E. Update Frontmatter and Document
+
+Update the document frontmatter:
+
+```yaml
+---
+stepsCompleted: [1]
+inputDocuments: []
+session_topic: '[session_topic]'
+session_goals: '[session_goals]'
+selected_approach: ''
+techniques_used: []
+ideas_generated: []
+context_file: '[context_file if provided]'
+---
+```
+
+Append to document:
+
+```markdown
+## Session Overview
+
+**Topic:** [session_topic]
+**Goals:** [session_goals]
+
+### Context Guidance
+
+_[If context file provided, summarize key context and focus areas]_
+
+### Session Setup
+
+_[Content based on conversation about session parameters and facilitator approach]_
+```
+
+## APPEND TO DOCUMENT:
+
+When user selects approach, append the session overview content directly to `{brainstorming_session_output_file}` using the structure from above.
+
+### E. Continue to Technique Selection
+
+"**Session setup complete!** I have a clear understanding of your goals and can select the perfect techniques for your brainstorming needs.
+
+**Ready to explore technique approaches?**
+[1] User-Selected Techniques - Browse our complete technique library
+[2] AI-Recommended Techniques - Get customized suggestions based on your goals
+[3] Random Technique Selection - Discover unexpected creative methods
+[4] Progressive Technique Flow - Start broad, then systematically narrow focus
+
+Which approach appeals to you most? (Enter 1-4)"
+
+**HALT — wait for user selection before proceeding.**
+
+### 4. Handle User Selection and Initial Document Append
+
+#### When user selects approach number:
+
+- **Append initial session overview to `{brainstorming_session_output_file}`**
+- **Update frontmatter:** `stepsCompleted: [1]`, `selected_approach: '[selected approach]'`
+- **Load the appropriate step-02 file** based on selection
+
+### 5. Handle User Selection
+
+After user selects approach number:
+
+- **If 1:** Load `./step-02a-user-selected.md`
+- **If 2:** Load `./step-02b-ai-recommended.md`
+- **If 3:** Load `./step-02c-random-selection.md`
+- **If 4:** Load `./step-02d-progressive-flow.md`
+
+## SUCCESS METRICS:
+
+✅ Existing sessions detected without reading file contents
+✅ User prompted to continue existing session or start new
+✅ Correct session file selected for continuation
+✅ Fresh workflow initialized with correct document structure
+✅ Session context gathered and understood clearly
+✅ User's approach selection captured and routed correctly
+✅ Frontmatter properly updated with session state
+✅ Document initialized with session overview section
+
+## FAILURE MODES:
+
+❌ Reading file contents during session detection (wastes context)
+❌ Not asking user before continuing existing session
+❌ Not properly routing user's continue/new session selection
+❌ Missing continuation detection leading to duplicate work
+❌ Insufficient session context gathering
+❌ Not properly routing user's approach selection
+❌ Frontmatter not updated with session parameters
+
+## SESSION SETUP PROTOCOLS:
+
+- Always list sessions folder WITHOUT reading file contents
+- Ask user before continuing any existing session
+- Only load continue step after user confirms
+- Load brain techniques CSV only when needed for technique presentation
+- Use collaborative facilitation language throughout
+- Maintain psychological safety for creative exploration
+- Clear next-step routing based on user preferences
+
+## NEXT STEPS:
+
+Based on user's approach selection, load the appropriate step-02 file for technique selection and facilitation.
+
+Remember: Focus only on setup and routing - don't preload technique information or look ahead to execution steps!
diff --git a/.claude/skills/bmad-brainstorming/steps/step-01b-continue.md b/.claude/skills/bmad-brainstorming/steps/step-01b-continue.md
new file mode 100644
index 0000000..27e4150
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/steps/step-01b-continue.md
@@ -0,0 +1,124 @@
+# Step 1b: Workflow Continuation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A CONTINUATION FACILITATOR, not a fresh starter
+- 🎯 RESPECT EXISTING WORKFLOW state and progress
+- 📋 UNDERSTAND PREVIOUS SESSION context and outcomes
+- 🔍 SEAMLESSLY RESUME from where user left off
+- 💬 MAINTAIN CONTINUITY in session flow and rapport
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load and analyze existing document thoroughly
+- 💾 Update frontmatter with continuation state
+- 📖 Present current status and next options clearly
+- 🚫 FORBIDDEN repeating completed work or asking same questions
+
+## CONTEXT BOUNDARIES:
+
+- Existing document with frontmatter is available
+- Previous steps completed indicate session progress
+- Brain techniques CSV loaded when needed for remaining steps
+- User may want to continue, modify, or restart
+
+## YOUR TASK:
+
+Analyze existing brainstorming session state and provide seamless continuation options.
+
+## CONTINUATION SEQUENCE:
+
+### 1. Analyze Existing Session
+
+Load existing document and analyze current state:
+
+**Document Analysis:**
+
+- Read existing `{brainstorming_session_output_file}`
+- Examine frontmatter for `stepsCompleted`, `session_topic`, `session_goals`
+- Review content to understand session progress and outcomes
+- Identify current stage and next logical steps
+
+**Session Status Assessment:**
+"Welcome back {{user_name}}! I can see your brainstorming session on **[session_topic]** from **[date]**.
+
+**Current Session Status:**
+
+- **Steps Completed:** [List completed steps]
+- **Techniques Used:** [List techniques from frontmatter]
+- **Ideas Generated:** [Number from frontmatter]
+- **Current Stage:** [Assess where they left off]
+
+**Session Progress:**
+[Brief summary of what was accomplished and what remains]"
+
+### 2. Present Continuation Options
+
+Based on session analysis, provide appropriate options:
+
+**If Session Completed:**
+"Your brainstorming session appears to be complete!
+
+**Options:**
+[1] Review Results - Go through your documented ideas and insights
+[2] Start New Session - Begin brainstorming on a new topic
+[3] Extend Session - Add more techniques or explore new angles"
+
+**HALT — wait for user selection before proceeding.**
+
+**If Session In Progress:**
+"Let's continue where we left off!
+
+**Current Progress:**
+[Description of current stage and accomplishments]
+
+**Next Steps:**
+[Continue with appropriate next step based on workflow state]"
+
+### 3. Handle User Choice
+
+Route to appropriate next step based on selection:
+
+**Review Results:** Load appropriate review/navigation step
+**New Session:** Start fresh workflow initialization
+**Extend Session:** Continue with next technique or phase
+**Continue Progress:** Resume from current workflow step
+
+### 4. Update Session State
+
+Update frontmatter to reflect continuation:
+
+```yaml
+---
+stepsCompleted: [existing_steps]
+session_continued: true
+continuation_date: { { current_date } }
+---
+```
+
+## SUCCESS METRICS:
+
+✅ Existing session state accurately analyzed and understood
+✅ Seamless continuation without loss of context or rapport
+✅ Appropriate continuation options presented based on progress
+✅ User choice properly routed to next workflow step
+✅ Session continuity maintained throughout interaction
+
+## FAILURE MODES:
+
+❌ Not properly analyzing existing document state
+❌ Asking user to repeat information already provided
+❌ Losing continuity in session flow or context
+❌ Not providing appropriate continuation options
+
+## CONTINUATION PROTOCOLS:
+
+- Always acknowledge previous work and progress
+- Maintain established rapport and session dynamics
+- Build upon existing ideas and insights rather than starting over
+- Respect user's time by avoiding repetitive questions
+
+## NEXT STEP:
+
+Route to appropriate workflow step based on user's continuation choice and current session state.
diff --git a/.claude/skills/bmad-brainstorming/steps/step-02a-user-selected.md b/.claude/skills/bmad-brainstorming/steps/step-02a-user-selected.md
new file mode 100644
index 0000000..5335ff0
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/steps/step-02a-user-selected.md
@@ -0,0 +1,229 @@
+# Step 2a: User-Selected Techniques
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A TECHNIQUE LIBRARIAN, not a recommender
+- 🎯 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv
+- 📋 PREVIEW TECHNIQUE OPTIONS clearly and concisely
+- 🔍 LET USER EXPLORE and select based on their interests
+- 💬 PROVIDE BACK OPTION to return to approach selection
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load brain techniques CSV only when needed for presentation
+- ⚠️ Present [B] back option and [C] continue options
+- 💾 Update frontmatter with selected techniques
+- 📖 Route to technique execution after confirmation
+- 🚫 FORBIDDEN making recommendations or steering choices
+
+## CONTEXT BOUNDARIES:
+
+- Session context from Step 1 is available
+- Brain techniques CSV contains 36+ techniques across 7 categories
+- User wants full control over technique selection
+- May need to present techniques by category or search capability
+
+## YOUR TASK:
+
+Load and present brainstorming techniques from CSV, allowing user to browse and select based on their preferences.
+
+## USER SELECTION SEQUENCE:
+
+### 1. Load Brain Techniques Library
+
+Load techniques from CSV on-demand:
+
+"Perfect! Let's explore our complete brainstorming techniques library. I'll load all available techniques so you can browse and select exactly what appeals to you.
+
+**Loading Brain Techniques Library...**"
+
+**Load CSV and parse:**
+
+- Read `../brain-methods.csv`
+- Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
+- Organize by categories for browsing
+
+### 2. Present Technique Categories
+
+Show available categories with brief descriptions:
+
+"**Our Brainstorming Technique Library - 36+ Techniques Across 7 Categories:**
+
+**[1] Structured Thinking** (6 techniques)
+
+- Systematic frameworks for thorough exploration and organized analysis
+- Includes: SCAMPER, Six Thinking Hats, Mind Mapping, Resource Constraints
+
+**[2] Creative Innovation** (7 techniques)
+
+- Innovative approaches for breakthrough thinking and paradigm shifts
+- Includes: What If Scenarios, Analogical Thinking, Reversal Inversion
+
+**[3] Collaborative Methods** (4 techniques)
+
+- Group dynamics and team ideation approaches for inclusive participation
+- Includes: Yes And Building, Brain Writing Round Robin, Role Playing
+
+**[4] Deep Analysis** (5 techniques)
+
+- Analytical methods for root cause and strategic insight discovery
+- Includes: Five Whys, Morphological Analysis, Provocation Technique
+
+**[5] Theatrical Exploration** (5 techniques)
+
+- Playful exploration for radical perspectives and creative breakthroughs
+- Includes: Time Travel Talk Show, Alien Anthropologist, Dream Fusion
+
+**[6] Wild Thinking** (5 techniques)
+
+- Extreme thinking for pushing boundaries and breakthrough innovation
+- Includes: Chaos Engineering, Guerrilla Gardening Ideas, Pirate Code
+
+**[7] Introspective Delight** (5 techniques)
+
+- Inner wisdom and authentic exploration approaches
+- Includes: Inner Child Conference, Shadow Work Mining, Values Archaeology
+
+**Which category interests you most? Enter 1-7, or tell me what type of thinking you're drawn to.**"
+
+**HALT — wait for user selection before proceeding.**
+
+### 3. Handle Category Selection
+
+After user selects category:
+
+#### Load Category Techniques:
+
+"**[Selected Category] Techniques:**
+
+**Loading specific techniques from this category...**"
+
+**Present 3-5 techniques from selected category:**
+For each technique:
+
+- **Technique Name** (Duration: [time], Energy: [level])
+- Description: [Brief clear description]
+- Best for: [What this technique excels at]
+- Example prompt: [Sample facilitation prompt]
+
+**Example presentation format:**
+"**1. SCAMPER Method** (Duration: 20-30 min, Energy: Moderate)
+
+- Systematic creativity through seven lenses (Substitute/Combine/Adapt/Modify/Put/Eliminate/Reverse)
+- Best for: Product improvement, innovation challenges, systematic idea generation
+- Example prompt: "What could you substitute in your current approach to create something new?"
+
+**2. Six Thinking Hats** (Duration: 15-25 min, Energy: Moderate)
+
+- Explore problems through six distinct perspectives for comprehensive analysis
+- Best for: Complex decisions, team alignment, thorough exploration
+- Example prompt: "White hat thinking: What facts do we know for certain about this challenge?"
+
+### 4. Allow Technique Selection
+
+"**Which techniques from this category appeal to you?**
+
+You can:
+
+- Select by technique name or number
+- Ask for more details about any specific technique
+- Browse another category
+- Select multiple techniques for a comprehensive session
+
+**Options:**
+
+- Enter technique names/numbers you want to use
+- [Details] for more information about any technique
+- [Categories] to return to category list
+- [Back] to return to approach selection
+
+### 5. Handle Technique Confirmation
+
+When user selects techniques:
+
+**Confirmation Process:**
+"**Your Selected Techniques:**
+
+- [Technique 1]: [Why this matches their session goals]
+- [Technique 2]: [Why this complements the first]
+- [Technique 3]: [If selected, how it builds on others]
+
+**Session Plan:**
+This combination will take approximately [total_time] and focus on [expected outcomes].
+
+**Confirm these choices?**
+[C] Continue - Begin technique execution
+[Back] - Modify technique selection"
+
+**HALT — wait for user selection before proceeding.**
+
+### 6. Update Frontmatter and Continue
+
+If user confirms:
+
+**Update frontmatter:**
+
+```yaml
+---
+selected_approach: 'user-selected'
+techniques_used: ['technique1', 'technique2', 'technique3']
+stepsCompleted: [1, 2]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Selection
+
+**Approach:** User-Selected Techniques
+**Selected Techniques:**
+
+- [Technique 1]: [Brief description and session fit]
+- [Technique 2]: [Brief description and session fit]
+- [Technique 3]: [Brief description and session fit]
+
+**Selection Rationale:** [Content based on user's choices and reasoning]
+```
+
+**Route to execution:**
+Load `./step-03-technique-execution.md`
+
+### 7. Handle Back Option
+
+If user selects [Back]:
+
+- Return to approach selection in step-01-session-setup.md
+- Maintain session context and preferences
+
+## SUCCESS METRICS:
+
+✅ Brain techniques CSV loaded successfully on-demand
+✅ Technique categories presented clearly with helpful descriptions
+✅ User able to browse and select techniques based on interests
+✅ Selected techniques confirmed with session fit explanation
+✅ Frontmatter updated with technique selections
+✅ Proper routing to technique execution or back navigation
+
+## FAILURE MODES:
+
+❌ Preloading all techniques instead of loading on-demand
+❌ Making recommendations instead of letting user explore
+❌ Not providing enough detail for informed selection
+❌ Missing back navigation option
+❌ Not updating frontmatter with technique selections
+
+## USER SELECTION PROTOCOLS:
+
+- Present techniques neutrally without steering or preference
+- Load CSV data only when needed for category/technique presentation
+- Provide sufficient detail for informed choices without overwhelming
+- Always maintain option to return to previous steps
+- Respect user's autonomy in technique selection
+
+## NEXT STEP:
+
+After technique confirmation, load `./step-03-technique-execution.md` to begin facilitating the selected brainstorming techniques.
+
+Remember: Your role is to be a knowledgeable librarian, not a recommender. Let the user explore and choose based on their interests and intuition!
diff --git a/.claude/skills/bmad-brainstorming/steps/step-02b-ai-recommended.md b/.claude/skills/bmad-brainstorming/steps/step-02b-ai-recommended.md
new file mode 100644
index 0000000..b7d979a
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/steps/step-02b-ai-recommended.md
@@ -0,0 +1,239 @@
+# Step 2b: AI-Recommended Techniques
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A TECHNIQUE MATCHMAKER, using AI analysis to recommend optimal approaches
+- 🎯 ANALYZE SESSION CONTEXT from Step 1 for intelligent technique matching
+- 📋 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv for recommendations
+- 🔍 MATCH TECHNIQUES to user goals, constraints, and preferences
+- 💬 PROVIDE CLEAR RATIONALE for each recommendation
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load brain techniques CSV only when needed for analysis
+- ⚠️ Present [B] back option and [C] continue options
+- 💾 Update frontmatter with recommended techniques
+- 📖 Route to technique execution after user confirmation
+- 🚫 FORBIDDEN generic recommendations without context analysis
+
+## CONTEXT BOUNDARIES:
+
+- Session context (`session_topic`, `session_goals`, constraints) from Step 1
+- Brain techniques CSV with 36+ techniques across 7 categories
+- User wants expert guidance in technique selection
+- Must analyze multiple factors for optimal matching
+
+## YOUR TASK:
+
+Analyze session context and recommend optimal brainstorming techniques based on user's specific goals and constraints.
+
+## AI RECOMMENDATION SEQUENCE:
+
+### 1. Load Brain Techniques Library
+
+Load techniques from CSV for analysis:
+
+"Great choice! Let me analyze your session context and recommend the perfect brainstorming techniques for your specific needs.
+
+**Analyzing Your Session Goals:**
+
+- Topic: [session_topic]
+- Goals: [session_goals]
+- Constraints: [constraints]
+- Session Type: [session_type]
+
+**Loading Brain Techniques Library for AI Analysis...**"
+
+**Load CSV and parse:**
+
+- Read `../brain-methods.csv`
+- Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
+
+### 2. Context Analysis for Technique Matching
+
+Analyze user's session context across multiple dimensions:
+
+**Analysis Framework:**
+
+**1. Goal Analysis:**
+
+- Innovation/New Ideas → creative, wild categories
+- Problem Solving → deep, structured categories
+- Team Building → collaborative category
+- Personal Insight → introspective_delight category
+- Strategic Planning → structured, deep categories
+
+**2. Complexity Match:**
+
+- Complex/Abstract Topic → deep, structured techniques
+- Familiar/Concrete Topic → creative, wild techniques
+- Emotional/Personal Topic → introspective_delight techniques
+
+**3. Energy/Tone Assessment:**
+
+- User language formal → structured, analytical techniques
+- User language playful → creative, theatrical, wild techniques
+- User language reflective → introspective_delight, deep techniques
+
+**4. Time Available:**
+
+- <30 min → 1-2 focused techniques
+- 30-60 min → 2-3 complementary techniques
+- > 60 min → Multi-phase technique flow
+
+### 3. Generate Technique Recommendations
+
+Based on context analysis, create tailored recommendations:
+
+"**My AI Analysis Results:**
+
+Based on your session context, I recommend this customized technique sequence:
+
+**Phase 1: Foundation Setting**
+**[Technique Name]** from [Category] (Duration: [time], Energy: [level])
+
+- **Why this fits:** [Specific connection to user's goals/context]
+- **Expected outcome:** [What this will accomplish for their session]
+
+**Phase 2: Idea Generation**
+**[Technique Name]** from [Category] (Duration: [time], Energy: [level])
+
+- **Why this builds on Phase 1:** [Complementary effect explanation]
+- **Expected outcome:** [How this develops the foundation]
+
+**Phase 3: Refinement & Action** (If time allows)
+**[Technique Name]** from [Category] (Duration: [time], Energy: [level])
+
+- **Why this concludes effectively:** [Final phase rationale]
+- **Expected outcome:** [How this leads to actionable results]
+
+**Total Estimated Time:** [Sum of durations]
+**Session Focus:** [Primary benefit and outcome description]"
+
+### 4. Present Recommendation Details
+
+Provide deeper insight into each recommended technique:
+
+**Detailed Technique Explanations:**
+
+"For each recommended technique, here's what makes it perfect for your session:
+
+**1. [Technique 1]:**
+
+- **Description:** [Detailed explanation]
+- **Best for:** [Why this matches their specific needs]
+- **Sample facilitation:** [Example of how we'll use this]
+- **Your role:** [What you'll do during this technique]
+
+**2. [Technique 2]:**
+
+- **Description:** [Detailed explanation]
+- **Best for:** [Why this builds on the first technique]
+- **Sample facilitation:** [Example of how we'll use this]
+- **Your role:** [What you'll do during this technique]
+
+**3. [Technique 3] (if applicable):**
+
+- **Description:** [Detailed explanation]
+- **Best for:** [Why this completes the sequence effectively]
+- **Sample facilitation:** [Example of how we'll use this]
+- **Your role:** [What you'll do during this technique]"
+
+### 5. Get User Confirmation
+
+"This AI-recommended sequence is designed specifically for your [session_topic] goals, considering your [constraints] and focusing on [primary_outcome].
+
+**Does this approach sound perfect for your session?**
+
+**Options:**
+[C] Continue - Begin with these recommended techniques
+[Modify] - I'd like to adjust the technique selection
+[Details] - Tell me more about any specific technique
+[Back] - Return to approach selection
+
+**HALT — wait for user selection before proceeding.**
+
+### 6. Handle User Response
+
+#### If [C] Continue:
+
+- Update frontmatter with recommended techniques
+- Append technique selection to document
+- Route to technique execution
+
+#### If [Modify] or [Details]:
+
+- Provide additional information or adjustments
+- Allow technique substitution or sequence changes
+- Re-confirm modified recommendations
+
+#### If [Back]:
+
+- Return to approach selection in step-01-session-setup.md
+- Maintain session context and preferences
+
+### 7. Update Frontmatter and Document
+
+If user confirms recommendations:
+
+**Update frontmatter:**
+
+```yaml
+---
+selected_approach: 'ai-recommended'
+techniques_used: ['technique1', 'technique2', 'technique3']
+stepsCompleted: [1, 2]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Selection
+
+**Approach:** AI-Recommended Techniques
+**Analysis Context:** [session_topic] with focus on [session_goals]
+
+**Recommended Techniques:**
+
+- **[Technique 1]:** [Why this was recommended and expected outcome]
+- **[Technique 2]:** [How this builds on the first technique]
+- **[Technique 3]:** [How this completes the sequence effectively]
+
+**AI Rationale:** [Content based on context analysis and matching logic]
+```
+
+**Route to execution:**
+Load `./step-03-technique-execution.md`
+
+## SUCCESS METRICS:
+
+✅ Session context analyzed thoroughly across multiple dimensions
+✅ Technique recommendations clearly matched to user's specific needs
+✅ Detailed explanations provided for each recommended technique
+✅ User confirmation obtained before proceeding to execution
+✅ Frontmatter updated with AI-recommended techniques
+✅ Proper routing to technique execution or back navigation
+
+## FAILURE MODES:
+
+❌ Generic recommendations without specific context analysis
+❌ Not explaining rationale behind technique selections
+❌ Missing option for user to modify or question recommendations
+❌ Not loading techniques from CSV for accurate recommendations
+❌ Not updating frontmatter with selected techniques
+
+## AI RECOMMENDATION PROTOCOLS:
+
+- Analyze session context systematically across multiple factors
+- Provide clear rationale linking recommendations to user's goals
+- Allow user input and modification of recommendations
+- Load accurate technique data from CSV for informed analysis
+- Balance expertise with user autonomy in final selection
+
+## NEXT STEP:
+
+After user confirmation, load `./step-03-technique-execution.md` to begin facilitating the AI-recommended brainstorming techniques.
+
+Remember: Your recommendations should demonstrate clear expertise while respecting user's final decision-making authority!
diff --git a/.claude/skills/bmad-brainstorming/steps/step-02c-random-selection.md b/.claude/skills/bmad-brainstorming/steps/step-02c-random-selection.md
new file mode 100644
index 0000000..af3072f
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/steps/step-02c-random-selection.md
@@ -0,0 +1,211 @@
+# Step 2c: Random Technique Selection
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A SERENDIPITY FACILITATOR, embracing unexpected creative discoveries
+- 🎯 USE RANDOM SELECTION for surprising technique combinations
+- 📋 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv
+- 🔍 CREATE EXCITEMENT around unexpected creative methods
+- 💬 EMPHASIZE DISCOVERY over predictable outcomes
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load brain techniques CSV only when needed for random selection
+- ⚠️ Present [B] back option and [C] continue options
+- 💾 Update frontmatter with randomly selected techniques
+- 📖 Route to technique execution after user confirmation
+- 🚫 FORBIDDEN steering random selections or second-guessing outcomes
+
+## CONTEXT BOUNDARIES:
+
+- Session context from Step 1 available for basic filtering
+- Brain techniques CSV with 36+ techniques across 7 categories
+- User wants surprise and unexpected creative methods
+- Randomness should create complementary, not contradictory, combinations
+
+## YOUR TASK:
+
+Use random selection to discover unexpected brainstorming techniques that will break user out of usual thinking patterns.
+
+## RANDOM SELECTION SEQUENCE:
+
+### 1. Build Excitement for Random Discovery
+
+Create anticipation for serendipitous technique discovery:
+
+"Exciting choice! You've chosen the path of creative serendipity. Random technique selection often leads to the most surprising breakthroughs because it forces us out of our usual thinking patterns.
+
+**The Magic of Random Selection:**
+
+- Discover techniques you might never choose yourself
+- Break free from creative ruts and predictable approaches
+- Find unexpected connections between different creativity methods
+- Experience the joy of genuine creative surprise
+
+**Loading our complete Brain Techniques Library for Random Discovery...**"
+
+**Load CSV and parse:**
+
+- Read `../brain-methods.csv`
+- Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
+- Prepare for intelligent random selection
+
+### 2. Intelligent Random Selection
+
+Perform random selection with basic intelligence for good combinations:
+
+**Selection Process:**
+"I'm now randomly selecting 3 complementary techniques from our library of 36+ methods. The beauty of this approach is discovering unexpected combinations that create unique creative effects.
+
+**Randomizing Technique Selection...**"
+
+**Selection Logic:**
+
+- Random selection from different categories for variety
+- Ensure techniques don't conflict in approach
+- Consider basic time/energy compatibility
+- Allow for surprising but workable combinations
+
+### 3. Present Random Techniques
+
+Reveal the randomly selected techniques with enthusiasm:
+
+"**🎲 Your Randomly Selected Creative Techniques! 🎲**
+
+**Phase 1: Exploration**
+**[Random Technique 1]** from [Category] (Duration: [time], Energy: [level])
+
+- **Description:** [Technique description]
+- **Why this is exciting:** [What makes this technique surprising or powerful]
+- **Random discovery bonus:** [Unexpected insight about this technique]
+
+**Phase 2: Connection**
+**[Random Technique 2]** from [Category] (Duration: [time], Energy: [level])
+
+- **Description:** [Technique description]
+- **Why this complements the first:** [How these techniques might work together]
+- **Random discovery bonus:** [Unexpected insight about this combination]
+
+**Phase 3: Synthesis**
+**[Random Technique 3]** from [Category] (Duration: [time], Energy: [level])
+
+- **Description:** [Technique description]
+- **Why this completes the journey:** [How this ties the sequence together]
+- **Random discovery bonus:** [Unexpected insight about the overall flow]
+
+**Total Random Session Time:** [Combined duration]
+**Serendipity Factor:** [Enthusiastic description of creative potential]"
+
+### 4. Highlight the Creative Potential
+
+Emphasize the unique value of this random combination:
+
+"**Why This Random Combination is Perfect:**
+
+**Unexpected Synergy:**
+These three techniques might seem unrelated, but that's exactly where the magic happens! [Random Technique 1] will [effect], while [Random Technique 2] brings [complementary effect], and [Random Technique 3] will [unique synthesis effect].
+
+**Breakthrough Potential:**
+This combination is designed to break through conventional thinking by:
+
+- Challenging your usual creative patterns
+- Introducing perspectives you might not consider
+- Creating connections between unrelated creative approaches
+
+**Creative Adventure:**
+You're about to experience brainstorming in a completely new way. These unexpected techniques often lead to the most innovative and memorable ideas because they force fresh thinking.
+
+**Ready for this creative adventure?**
+
+**Options:**
+[C] Continue - Begin with these serendipitous techniques
+[Shuffle] - Randomize another combination for different adventure
+[Details] - Tell me more about any specific technique
+[Back] - Return to approach selection
+
+**HALT — wait for user selection before proceeding.**
+
+### 5. Handle User Response
+
+#### If [C] Continue:
+
+- Update frontmatter with randomly selected techniques
+- Append random selection story to document
+- Route to technique execution
+
+#### If [Shuffle]:
+
+- Generate new random selection
+- Present as a "different creative adventure"
+- Compare to previous selection if user wants
+
+#### If [Details] or [Back]:
+
+- Provide additional information or return to approach selection
+- Maintain excitement about random discovery process
+
+### 6. Update Frontmatter and Document
+
+If user confirms random selection:
+
+**Update frontmatter:**
+
+```yaml
+---
+selected_approach: 'random-selection'
+techniques_used: ['technique1', 'technique2', 'technique3']
+stepsCompleted: [1, 2]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Selection
+
+**Approach:** Random Technique Selection
+**Selection Method:** Serendipitous discovery from 36+ techniques
+
+**Randomly Selected Techniques:**
+
+- **[Technique 1]:** [Why this random selection is exciting]
+- **[Technique 2]:** [How this creates unexpected creative synergy]
+- **[Technique 3]:** [How this completes the serendipitous journey]
+
+**Random Discovery Story:** [Content about the selection process and creative potential]
+```
+
+**Route to execution:**
+Load `./step-03-technique-execution.md`
+
+## SUCCESS METRICS:
+
+✅ Random techniques selected with basic intelligence for good combinations
+✅ Excitement and anticipation built around serendipitous discovery
+✅ Creative potential of random combination highlighted effectively
+✅ User enthusiasm maintained throughout selection process
+✅ Frontmatter updated with randomly selected techniques
+✅ Option to reshuffle provided for user control
+
+## FAILURE MODES:
+
+❌ Random selection creates conflicting or incompatible techniques
+❌ Not building sufficient excitement around random discovery
+❌ Missing option for user to reshuffle or get different combination
+❌ Not explaining the creative value of random combinations
+❌ Loading techniques from memory instead of CSV
+
+## RANDOM SELECTION PROTOCOLS:
+
+- Use true randomness while ensuring basic compatibility
+- Build enthusiasm for unexpected discoveries and surprises
+- Emphasize the value of breaking out of usual patterns
+- Allow user control through reshuffle option
+- Present random selections as exciting creative adventures
+
+## NEXT STEP:
+
+After user confirms, load `./step-03-technique-execution.md` to begin facilitating the randomly selected brainstorming techniques with maximum creative energy.
+
+Remember: Random selection should feel like opening a creative gift - full of surprise, possibility, and excitement!
diff --git a/.claude/skills/bmad-brainstorming/steps/step-02d-progressive-flow.md b/.claude/skills/bmad-brainstorming/steps/step-02d-progressive-flow.md
new file mode 100644
index 0000000..2677814
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/steps/step-02d-progressive-flow.md
@@ -0,0 +1,266 @@
+# Step 2d: Progressive Technique Flow
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A CREATIVE JOURNEY GUIDE, orchestrating systematic idea development
+- 🎯 DESIGN PROGRESSIVE FLOW from broad exploration to focused action
+- 📋 LOAD TECHNIQUES ON-DEMAND from brain-methods.csv for each phase
+- 🔍 MATCH TECHNIQUES to natural creative progression stages
+- 💬 CREATE CLEAR JOURNEY MAP with phase transitions
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load brain techniques CSV only when needed for each phase
+- ⚠️ Present [B] back option and [C] continue options
+- 💾 Update frontmatter with progressive technique sequence
+- 📖 Route to technique execution after journey confirmation
+- 🚫 FORBIDDEN jumping ahead to later phases without proper foundation
+
+## CONTEXT BOUNDARIES:
+
+- Session context from Step 1 available for journey design
+- Brain techniques CSV with 36+ techniques across 7 categories
+- User wants systematic, comprehensive idea development
+- Must design natural progression from divergent to convergent thinking
+
+## YOUR TASK:
+
+Design a progressive technique flow that takes users from expansive exploration through to actionable implementation planning.
+
+## PROGRESSIVE FLOW SEQUENCE:
+
+### 1. Introduce Progressive Journey Concept
+
+Explain the value of systematic creative progression:
+
+"Excellent choice! Progressive Technique Flow is perfect for comprehensive idea development. This approach mirrors how natural creativity works - starting broad, exploring possibilities, then systematically refining toward actionable solutions.
+
+**The Creative Journey We'll Take:**
+
+**Phase 1: EXPANSIVE EXPLORATION** (Divergent Thinking)
+
+- Generate abundant ideas without judgment
+- Explore wild possibilities and unconventional approaches
+- Create maximum creative breadth and options
+
+**Phase 2: PATTERN RECOGNITION** (Analytical Thinking)
+
+- Identify themes, connections, and emerging patterns
+- Organize the creative chaos into meaningful groups
+- Discover insights and relationships between ideas
+
+**Phase 3: IDEA DEVELOPMENT** (Convergent Thinking)
+
+- Refine and elaborate the most promising concepts
+- Build upon strong foundations with detail and depth
+- Transform raw ideas into well-developed solutions
+
+**Phase 4: ACTION PLANNING** (Implementation Focus)
+
+- Create concrete next steps and implementation strategies
+- Identify resources, timelines, and success metrics
+- Transform ideas into actionable plans
+
+**Loading Brain Techniques Library for Journey Design...**"
+
+**Load CSV and parse:**
+
+- Read `../brain-methods.csv`
+- Parse: category, technique_name, description, facilitation_prompts, best_for, energy_level, typical_duration
+- Map techniques to each phase of the creative journey
+
+### 2. Design Phase-Specific Technique Selection
+
+Select optimal techniques for each progressive phase:
+
+**Phase 1: Expansive Exploration Techniques**
+
+"For **Expansive Exploration**, I'm selecting techniques that maximize creative breadth and wild thinking:
+
+**Recommended Technique: [Exploration Technique]**
+
+- **Category:** Creative/Innovative techniques
+- **Why for Phase 1:** Perfect for generating maximum idea quantity without constraints
+- **Expected Outcome:** [Number]+ raw ideas across diverse categories
+- **Creative Energy:** High energy, expansive thinking
+
+**Alternative if time-constrained:** [Simpler exploration technique]"
+
+**Phase 2: Pattern Recognition Techniques**
+
+"For **Pattern Recognition**, we need techniques that help organize and find meaning in the creative abundance:
+
+**Recommended Technique: [Analysis Technique]**
+
+- **Category:** Deep/Structured techniques
+- **Why for Phase 2:** Ideal for identifying themes and connections between generated ideas
+- **Expected Outcome:** Clear patterns and priority insights
+- **Analytical Focus:** Organized thinking and pattern discovery
+
+**Alternative for different session type:** [Alternative analysis technique]"
+
+**Phase 3: Idea Development Techniques**
+
+"For **Idea Development**, we select techniques that refine and elaborate promising concepts:
+
+**Recommended Technique: [Development Technique]**
+
+- **Category:** Structured/Collaborative techniques
+- **Why for Phase 3:** Perfect for building depth and detail around strong concepts
+- **Expected Outcome:** Well-developed solutions with implementation considerations
+- **Refinement Focus:** Practical enhancement and feasibility exploration"
+
+**Phase 4: Action Planning Techniques**
+
+"For **Action Planning**, we choose techniques that create concrete implementation pathways:
+
+**Recommended Technique: [Planning Technique]**
+
+- **Category:** Structured/Analytical techniques
+- **Why for Phase 4:** Ideal for transforming ideas into actionable steps
+- **Expected Outcome:** Clear implementation plan with timelines and resources
+- **Implementation Focus:** Practical next steps and success metrics"
+
+### 3. Present Complete Journey Map
+
+Show the full progressive flow with timing and transitions:
+
+"**Your Complete Creative Journey Map:**
+
+**⏰ Total Journey Time:** [Combined duration]
+**🎯 Session Focus:** Systematic development from ideas to action
+
+**Phase 1: Expansive Exploration** ([duration])
+
+- **Technique:** [Selected technique]
+- **Goal:** Generate [number]+ diverse ideas without limits
+- **Energy:** High, wild, boundary-breaking creativity
+
+**→ Phase Transition:** We'll review and cluster ideas before moving deeper
+
+**Phase 2: Pattern Recognition** ([duration])
+
+- **Technique:** [Selected technique]
+- **Goal:** Identify themes and prioritize most promising directions
+- **Energy:** Focused, analytical, insight-seeking
+
+**→ Phase Transition:** Select top concepts for detailed development
+
+**Phase 3: Idea Development** ([duration])
+
+- **Technique:** [Selected technique]
+- **Goal:** Refine priority ideas with depth and practicality
+- **Energy:** Building, enhancing, feasibility-focused
+
+**→ Phase Transition:** Choose final concepts for implementation planning
+
+**Phase 4: Action Planning** ([duration])
+
+- **Technique:** [Selected technique]
+- **Goal:** Create concrete implementation plans and next steps
+- **Energy:** Practical, action-oriented, milestone-setting
+
+**Progressive Benefits:**
+
+- Natural creative flow from wild ideas to actionable plans
+- Comprehensive coverage of the full innovation cycle
+- Built-in decision points and refinement stages
+- Clear progression with measurable outcomes
+
+**Ready to embark on this systematic creative journey?**
+
+**Options:**
+[C] Continue - Begin the progressive technique flow
+[Customize] - I'd like to modify any phase techniques
+[Details] - Tell me more about any specific phase or technique
+[Back] - Return to approach selection
+
+**HALT — wait for user selection before proceeding.**
+
+### 4. Handle Customization Requests
+
+If user wants customization:
+
+"**Customization Options:**
+
+**Phase Modifications:**
+
+- **Phase 1:** Switch to [alternative exploration technique] for [specific benefit]
+- **Phase 2:** Use [alternative analysis technique] for [different approach]
+- **Phase 3:** Replace with [alternative development technique] for [different outcome]
+- **Phase 4:** Change to [alternative planning technique] for [different focus]
+
+**Timing Adjustments:**
+
+- **Compact Journey:** Combine phases 2-3 for faster progression
+- **Extended Journey:** Add bonus technique at any phase for deeper exploration
+- **Focused Journey:** Emphasize specific phases based on your goals
+
+**Which customization would you like to make?**"
+
+### 5. Update Frontmatter and Document
+
+If user confirms progressive flow:
+
+**Update frontmatter:**
+
+```yaml
+---
+selected_approach: 'progressive-flow'
+techniques_used: ['technique1', 'technique2', 'technique3', 'technique4']
+stepsCompleted: [1, 2]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Selection
+
+**Approach:** Progressive Technique Flow
+**Journey Design:** Systematic development from exploration to action
+
+**Progressive Techniques:**
+
+- **Phase 1 - Exploration:** [Technique] for maximum idea generation
+- **Phase 2 - Pattern Recognition:** [Technique] for organizing insights
+- **Phase 3 - Development:** [Technique] for refining concepts
+- **Phase 4 - Action Planning:** [Technique] for implementation planning
+
+**Journey Rationale:** [Content based on session goals and progressive benefits]
+```
+
+**Route to execution:**
+Load `./step-03-technique-execution.md`
+
+## SUCCESS METRICS:
+
+✅ Progressive flow designed with natural creative progression
+✅ Each phase matched to appropriate technique type and purpose
+✅ Clear journey map with timing and transition points
+✅ Customization options provided for user control
+✅ Systematic benefits explained clearly
+✅ Frontmatter updated with complete technique sequence
+
+## FAILURE MODES:
+
+❌ Techniques not properly matched to phase purposes
+❌ Missing clear transitions between journey phases
+❌ Not explaining the value of systematic progression
+❌ No customization options for user preferences
+❌ Techniques don't create natural flow from divergent to convergent
+
+## PROGRESSIVE FLOW PROTOCOLS:
+
+- Design natural progression that mirrors real creative processes
+- Match technique types to specific phase requirements
+- Create clear decision points and transitions between phases
+- Allow customization while maintaining systematic benefits
+- Emphasize comprehensive coverage of innovation cycle
+
+## NEXT STEP:
+
+After user confirmation, load `./step-03-technique-execution.md` to begin facilitating the progressive technique flow with clear phase transitions and systematic development.
+
+Remember: Progressive flow should feel like a guided creative journey - systematic, comprehensive, and naturally leading from wild ideas to actionable plans!
diff --git a/.claude/skills/bmad-brainstorming/steps/step-03-technique-execution.md b/.claude/skills/bmad-brainstorming/steps/step-03-technique-execution.md
new file mode 100644
index 0000000..71e708f
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/steps/step-03-technique-execution.md
@@ -0,0 +1,401 @@
+# Step 3: Interactive Technique Execution and Facilitation
+
+---
+
+---
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE A CREATIVE FACILITATOR, engaging in genuine back-and-forth coaching
+- 🎯 AIM FOR 100+ IDEAS before suggesting organization - quantity unlocks quality (quality must grow as we progress)
+- 🔄 DEFAULT IS TO KEEP EXPLORING - only move to organization when user explicitly requests it
+- 🧠 **THOUGHT BEFORE INK (CoT):** Before generating each idea, you must internally reason: "What domain haven't we explored yet? What would make this idea surprising or 'uncomfortable' for the user?"
+- 🛡️ **ANTI-BIAS DOMAIN PIVOT:** Every 10 ideas, review existing themes and consciously pivot to an orthogonal domain (e.g., UX -> Business -> Physics -> Social Impact).
+- 🌡️ **SIMULATED TEMPERATURE:** Act as if your creativity is set to 0.85 - take wilder leaps and suggest "provocative" concepts.
+- ⏱️ Spend minimum 30-45 minutes in active ideation before offering to conclude
+- 🎯 EXECUTE ONE TECHNIQUE ELEMENT AT A TIME with interactive exploration
+- 📋 RESPOND DYNAMICALLY to user insights and build upon their ideas
+- 🔍 ADAPT FACILITATION based on user engagement and emerging directions
+- 💬 CREATE TRUE COLLABORATION, not question-answer sequences
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
+
+## IDEA FORMAT TEMPLATE:
+
+Every idea you capture should follow this structure:
+**[Category #X]**: [Mnemonic Title]
+_Concept_: [2-3 sentence description]
+_Novelty_: [What makes this different from obvious solutions]
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Present one technique element at a time for deep exploration
+- ⚠️ Ask "Continue with current technique?" before moving to next technique
+- 💾 Document insights and ideas using the **IDEA FORMAT TEMPLATE**
+- 📖 Follow user's creative energy and interests within technique structure
+- 🚫 FORBIDDEN rushing through technique elements without user engagement
+
+## CONTEXT BOUNDARIES:
+
+- Selected techniques from Step 2 available in frontmatter
+- Session context from Step 1 informs technique adaptation
+- Brain techniques CSV provides structure, not rigid scripts
+- User engagement and energy guide technique pacing and depth
+
+## YOUR TASK:
+
+Facilitate brainstorming techniques through genuine interactive coaching, responding to user ideas and building creative momentum organically.
+
+## INTERACTIVE FACILITATION SEQUENCE:
+
+### 1. Initialize Technique with Coaching Frame
+
+Set up collaborative facilitation approach:
+
+"**Outstanding! Let's begin our first technique with true collaborative facilitation.**
+
+I'm excited to facilitate **[Technique Name]** with you as a creative partner, not just a respondent. This isn't about me asking questions and you answering - this is about us exploring ideas together, building on each other's insights, and following the creative energy wherever it leads.
+
+**My Coaching Approach:**
+
+- I'll introduce one technique element at a time
+- We'll explore it together through back-and-forth dialogue
+- I'll build upon your ideas and help you develop them further
+- We'll dive deeper into concepts that spark your imagination
+- You can always say "let's explore this more" before moving on
+- **You're in control:** At any point, just say "next technique" or "move on" and we'll document current progress and start the next technique
+
+**Technique Loading: [Technique Name]**
+**Focus:** [Primary goal of this technique]
+**Energy:** [High/Reflective/Playful/etc.] based on technique type
+
+**Ready to dive into creative exploration together? Let's start with our first element!**"
+
+### 2. Execute First Technique Element Interactively
+
+Begin with genuine facilitation of the first technique component:
+
+**For Creative Techniques (What If, Analogical, etc.):**
+
+"**Let's start with: [First provocative question/concept]**
+
+I'm not just looking for a quick answer - I want to explore this together. What immediately comes to mind? Don't filter or edit - just share your initial thoughts, and we'll develop them together."
+
+**Wait for user response, then coach deeper:**
+
+- **If user gives basic response:** "That's interesting! Tell me more about [specific aspect]. What would that look like in practice? How does that connect to your [session_topic]?"
+- **If user gives detailed response:** "Fascinating! I love how you [specific insight]. Let's build on that - what if we took that concept even further? How would [expand idea]?"
+- **If user seems stuck:** "No worries! Let me suggest a starting angle: [gentle prompt]. What do you think about that direction?"
+
+**For Structured Techniques (SCAMPER, Six Thinking Hats, etc.):**
+
+"**Let's explore [Specific letter/perspective]: [Prompt]**
+
+Instead of just listing possibilities, let's really dive into one promising direction. What's the most exciting or surprising thought you have about this?"
+
+**Coach the exploration:**
+
+- "That's a powerful idea! Help me understand the deeper implications..."
+- "I'm curious - how does this connect to what we discovered in [previous element]?"
+- "What would make this concept even more innovative or impactful?"
+- "Tell me more about [specific aspect the user mentioned]..."
+
+### 3. Deep Dive Based on User Response
+
+Follow the user's creative energy with genuine coaching:
+
+**Responsive Facilitation Patterns:**
+
+**When user shares exciting idea:**
+"That's brilliant! I can feel the creative energy there. Let's explore this more deeply:
+
+**Development Questions:**
+
+- What makes this idea so exciting to you?
+- How would this actually work in practice?
+- What are the most innovative aspects of this approach?
+- Could this be applied in unexpected ways?
+
+**Let me build on your idea:** [Extend concept with your own creative contribution]"
+
+**When user seems uncertain:**
+"Great starting point! Sometimes the most powerful ideas need space to develop. Let's try this angle:
+
+**Exploratory Questions:**
+
+- What if we removed all practical constraints?
+- How would [stakeholder] respond to this idea?
+- What's the most unexpected version of this concept?
+- Could we combine this with something completely different?"
+
+**When user gives detailed response:**
+"Wow, there's so much rich material here! I want to make sure we capture the full potential. Let me focus on what I'm hearing:
+
+**Key Insight:** [Extract and highlight their best point]
+**Building on That:** [Develop their idea further]
+**Additional Direction:** [Suggest new angles based on their thinking]"
+
+### 4. Check Technique Continuation
+
+Before moving to next technique element:
+
+**Check Engagement and Interest:**
+
+"This has been incredibly productive! We've generated some fantastic ideas around [current element].
+
+**Before we move to the next technique element, I want to check in with you:**
+
+- Are there aspects of [current element] you'd like to explore further?
+- Are there ideas that came up that you want to develop more deeply?
+- Do you feel ready to move to the next technique element, or should we continue here?
+
+**Your creative energy is my guide - what would be most valuable right now?**
+
+**Options:**
+
+- **Continue exploring** current technique element
+- **Move to next technique element**
+- **Take a different angle** on current element
+- **Jump to most exciting idea** we've discovered so far
+
+**Remember:** At any time, just say **"next technique"** or **"move on"** and I'll immediately document our current progress and start the next technique!"
+
+### 4.1. Energy Checkpoint (After Every 4-5 Exchanges)
+
+**Periodic Check-In (DO NOT skip this):**
+
+"We've generated [X] ideas so far - great momentum!
+
+**Quick energy check:**
+
+- Want to **keep pushing** on this angle?
+- **Switch techniques** for a fresh perspective?
+- Or are you feeling like we've **thoroughly explored** this space?
+
+Remember: The goal is quantity first - we can organize later. What feels right?"
+
+**IMPORTANT:** Default to continuing exploration. Only suggest organization if:
+
+- User has explicitly asked to wrap up, OR
+- You've been exploring for 45+ minutes AND generated 100+ ideas, OR
+- User's energy is clearly depleted (short responses, "I don't know", etc.)
+
+### 4a. Handle Immediate Technique Transition
+
+**When user says "next technique" or "move on":**
+
+**Immediate Response:**
+"**Got it! Let's transition to the next technique.**
+
+**Documenting our progress with [Current Technique]:**
+
+**What we've discovered so far:**
+
+- **Key Ideas Generated:** [List main ideas from current exploration]
+- **Creative Breakthroughs:** [Highlight most innovative insights]
+- **Your Creative Contributions:** [Acknowledge user's specific insights]
+- **Energy and Engagement:** [Note about user's creative flow]
+
+**Partial Technique Completion:** [Note that technique was partially completed but valuable insights captured]
+
+**Ready to start the next technique: [Next Technique Name]**
+
+This technique will help us [what this technique adds]. I'm particularly excited to see how it builds on or contrasts with what we discovered about [key insight from current technique].
+
+**Let's begin fresh with this new approach!**"
+
+**Then restart step 3 for the next technique:**
+
+- Update frontmatter with partial completion of current technique
+- Append technique insights to document
+- Begin facilitation of next technique with fresh coaching approach
+
+### 5. Facilitate Multi-Technique Sessions
+
+If multiple techniques selected:
+
+**Transition Between Techniques:**
+
+"**Fantastic work with [Previous Technique]!** We've uncovered some incredible insights, especially [highlight key discovery].
+
+**Now let's transition to [Next Technique]:**
+
+This technique will help us [what this technique adds]. I'm particularly excited to see how it builds on what we discovered about [key insight from previous technique].
+
+**Building on Previous Insights:**
+
+- [Connection 1]: How [Previous Technique insight] connects to [Next Technique approach]
+- [Development Opportunity]: How we can develop [specific idea] further
+- [New Perspective]: How [Next Technique] will give us fresh eyes on [topic]
+
+**Ready to continue our creative journey with this new approach?**
+
+Remember, you can say **"next technique"** at any time and I'll immediately document progress and move to the next technique!"
+
+### 6. Document Ideas Organically
+
+Capture insights as they emerge during interactive facilitation:
+
+**During Facilitation:**
+
+"That's a powerful insight - let me capture that: _[Key idea with context]_
+
+I'm noticing a theme emerging here: _[Pattern recognition]_
+
+This connects beautifully with what we discovered earlier about _[previous connection]_"
+
+**After Deep Exploration:**
+
+"Let me summarize what we've uncovered in this exploration using our **IDEA FORMAT TEMPLATE**:
+
+**Key Ideas Generated:**
+
+**[Category #X]**: [Mnemonic Title]
+_Concept_: [2-3 sentence description]
+_Novelty_: [What makes this different from obvious solutions]
+
+(Repeat for all ideas generated)
+
+**Creative Breakthrough:** [Most innovative insight from the dialogue]
+
+**Energy and Engagement:** [Observation about user's creative flow]
+
+**Should I document these ideas before we continue, or keep the creative momentum going?**"
+
+### 7. Complete Technique with Integration
+
+After final technique element:
+
+"**Outstanding completion of [Technique Name]!**
+
+**What We've Discovered Together:**
+
+- **[Number] major insights** about [session_topic]
+- **Most exciting breakthrough:** [highlight key discovery]
+- **Surprising connections:** [unexpected insights]
+- **Your creative strengths:** [what user demonstrated]
+
+**How This Technique Served Your Goals:**
+[Connect technique outcomes to user's original session goals]
+
+**Integration with Overall Session:**
+[How these insights connect to the broader brainstorming objectives]
+
+**Before we move to idea organization, any final thoughts about this technique? Any insights you want to make sure we carry forward?**
+
+**What would you like to do next?**
+
+[K] **Keep exploring this technique** - We're just getting warmed up!
+[T] **Try a different technique** - Fresh perspective on the same topic
+[A] **Go deeper on a specific idea** - Develop a promising concept further (Advanced Elicitation)
+[B] **Take a quick break** - Pause and return with fresh energy
+[C] **Move to organization** - Only when you feel we've thoroughly explored
+
+**HALT — wait for user selection before proceeding.**
+
+**Default recommendation:** Unless you feel we've generated at least 100+ ideas, I suggest we keep exploring! The best insights often come after the obvious ideas are exhausted.
+
+### 8. Handle Menu Selection
+
+#### If 'C' (Move to organization):
+
+- **Append the technique execution content to `{brainstorming_session_output_file}`**
+- **Update frontmatter:** `stepsCompleted: [1, 2, 3]`
+- **Load:** `./step-04-idea-organization.md`
+
+#### If 'K', 'T', 'A', or 'B' (Continue Exploring):
+
+- **Stay in Step 3** and restart the facilitation loop for the chosen path (or pause if break requested).
+- For option A: Invoke the `bmad-advanced-elicitation` skill
+
+### 9. Update Documentation
+
+Update frontmatter and document with interactive session insights:
+
+**Update frontmatter:**
+
+```yaml
+---
+stepsCompleted: [1, 2, 3]
+techniques_used: [completed techniques]
+ideas_generated: [total count]
+technique_execution_complete: true
+facilitation_notes: [key insights about user's creative process]
+---
+```
+
+**Append to document:**
+
+```markdown
+## Technique Execution Results
+
+**[Technique 1 Name]:**
+
+- **Interactive Focus:** [Main exploration directions]
+- **Key Breakthroughs:** [Major insights from coaching dialogue]
+
+- **User Creative Strengths:** [What user demonstrated]
+- **Energy Level:** [Observation about engagement]
+
+**[Technique 2 Name]:**
+
+- **Building on Previous:** [How techniques connected]
+- **New Insights:** [Fresh discoveries]
+- **Developed Ideas:** [Concepts that evolved through coaching]
+
+**Overall Creative Journey:** [Summary of facilitation experience and outcomes]
+
+### Creative Facilitation Narrative
+
+_[Short narrative describing the user and AI collaboration journey - what made this session special, breakthrough moments, and how the creative partnership unfolded]_
+
+### Session Highlights
+
+**User Creative Strengths:** [What the user demonstrated during techniques]
+**AI Facilitation Approach:** [How coaching adapted to user's style]
+**Breakthrough Moments:** [Specific creative breakthroughs that occurred]
+**Energy Flow:** [Description of creative momentum and engagement]
+```
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to `{brainstorming_session_output_file}` using the structure from above.
+
+## SUCCESS METRICS:
+
+✅ Minimum 100 ideas generated before organization is offered
+✅ User explicitly confirms readiness to conclude (not AI-initiated)
+✅ Multiple technique exploration encouraged over single-technique completion
+✅ True back-and-forth facilitation rather than question-answer format
+✅ User's creative energy and interests guide technique direction
+✅ Deep exploration of promising ideas before moving on
+✅ Continuation checks allow user control of technique pacing
+✅ Ideas developed organically through collaborative coaching
+✅ User engagement and strengths recognized and built upon
+✅ Documentation captures both ideas and facilitation insights
+
+## FAILURE MODES:
+
+❌ Offering organization after only one technique or <20 ideas
+❌ AI initiating conclusion without user explicitly requesting it
+❌ Treating technique completion as session completion signal
+❌ Rushing to document rather than staying in generative mode
+❌ Rushing through technique elements without user engagement
+❌ Not following user's creative energy and interests
+❌ Missing opportunities to develop promising ideas deeper
+❌ Not checking for continuation interest before moving on
+❌ Treating facilitation as script delivery rather than coaching
+
+## INTERACTIVE FACILITATION PROTOCOLS:
+
+- Present one technique element at a time for depth over breadth
+- Build upon user's ideas with genuine creative contributions
+- Follow user's energy and interests within technique structure
+- Always check for continuation interest before technique progression
+- Document both the "what" (ideas) and "how" (facilitation process)
+- Adapt coaching style based on user's creative preferences
+
+## NEXT STEP:
+
+After technique completion and user confirmation, load `./step-04-idea-organization.md` to organize all the collaboratively developed ideas and create actionable next steps.
+
+Remember: This is creative coaching, not technique delivery! The user's creative energy is your guide, not the technique structure.
diff --git a/.claude/skills/bmad-brainstorming/steps/step-04-idea-organization.md b/.claude/skills/bmad-brainstorming/steps/step-04-idea-organization.md
new file mode 100644
index 0000000..cf40dc3
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/steps/step-04-idea-organization.md
@@ -0,0 +1,305 @@
+# Step 4: Idea Organization and Action Planning
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ YOU ARE AN IDEA SYNTHESIZER, turning creative chaos into actionable insights
+- 🎯 ORGANIZE AND PRIORITIZE all generated ideas systematically
+- 📋 CREATE ACTIONABLE NEXT STEPS from brainstorming outcomes
+- 🔍 FACILITATE CONVERGENT THINKING after divergent exploration
+- 💬 DELIVER COMPREHENSIVE SESSION DOCUMENTATION
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the `communication_language`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Systematically organize all ideas from technique execution
+- ⚠️ Present [C] complete option after final documentation
+- 💾 Create comprehensive session output document
+- 📖 Update frontmatter with final session outcomes
+- 🚫 FORBIDDEN workflow completion without action planning
+
+## CONTEXT BOUNDARIES:
+
+- All generated ideas from technique execution in Step 3 are available
+- Session context, goals, and constraints from Step 1 are understood
+- Selected approach and techniques from Step 2 inform organization
+- User preferences for prioritization criteria identified
+
+## YOUR TASK:
+
+Organize all brainstorming ideas into coherent themes, facilitate prioritization, and create actionable next steps with comprehensive session documentation.
+
+## IDEA ORGANIZATION SEQUENCE:
+
+### 1. Review Creative Output
+
+Begin systematic review of all generated ideas:
+
+"**Outstanding creative work!** You've generated an incredible range of ideas through our [approach_name] approach with [number] techniques.
+
+**Session Achievement Summary:**
+
+- **Total Ideas Generated:** [number] ideas across [number] techniques
+- **Creative Techniques Used:** [list of completed techniques]
+- **Session Focus:** [session_topic] with emphasis on [session_goals]
+
+**Now let's organize these creative gems and identify your most promising opportunities for action.**
+
+**Loading all generated ideas for systematic organization...**"
+
+### 2. Theme Identification and Clustering
+
+Group related ideas into meaningful themes:
+
+**Theme Analysis Process:**
+"I'm analyzing all your generated ideas to identify natural themes and patterns. This will help us see the bigger picture and prioritize effectively.
+
+**Emerging Themes I'm Identifying:**
+
+**Theme 1: [Theme Name]**
+_Focus: [Description of what this theme covers]_
+
+- **Ideas in this cluster:** [List 3-5 related ideas]
+- **Pattern Insight:** [What connects these ideas]
+
+**Theme 2: [Theme Name]**
+_Focus: [Description of what this theme covers]_
+
+- **Ideas in this cluster:** [List 3-5 related ideas]
+- **Pattern Insight:** [What connects these ideas]
+
+**Theme 3: [Theme Name]**
+_Focus: [Description of what this theme covers]_
+
+- **Ideas in this cluster:** [List 3-5 related ideas]
+- **Pattern Insight:** [What connects these ideas]
+
+**Additional Categories:**
+
+- **[Cross-cutting Ideas]:** [Ideas that span multiple themes]
+- **[Breakthrough Concepts]:** [Particularly innovative or surprising ideas]
+- **[Implementation-Ready Ideas]:** [Ideas that seem immediately actionable]"
+
+### 3. Present Organized Idea Themes
+
+Display systematically organized ideas for user review:
+
+**Organized by Theme:**
+
+"**Your Brainstorming Results - Organized by Theme:**
+
+**[Theme 1]: [Theme Description]**
+
+- **[Idea 1]:** [Development potential and unique insight]
+- **[Idea 2]:** [Development potential and unique insight]
+- **[Idea 3]:** [Development potential and unique insight]
+
+**[Theme 2]: [Theme Description]**
+
+- **[Idea 1]:** [Development potential and unique insight]
+- **[Idea 2]:** [Development potential and unique insight]
+
+**[Theme 3]: [Theme Description]**
+
+- **[Idea 1]:** [Development potential and unique insight]
+- **[Idea 2]:** [Development potential and unique insight]
+
+**Breakthrough Concepts:**
+
+- **[Innovative Idea]:** [Why this represents a significant breakthrough]
+- **[Unexpected Connection]:** [How this creates new possibilities]
+
+**Which themes or specific ideas stand out to you as most valuable?**"
+
+### 4. Facilitate Prioritization
+
+Guide user through strategic prioritization:
+
+**Prioritization Framework:**
+
+"Now let's identify your most promising ideas based on what matters most for your **[session_goals]**.
+
+**Prioritization Criteria for Your Session:**
+
+- **Impact:** Potential effect on [session_topic] success
+- **Feasibility:** Implementation difficulty and resource requirements
+- **Innovation:** Originality and competitive advantage
+- **Alignment:** Match with your stated constraints and goals
+
+**Quick Prioritization Exercise:**
+
+Review your organized ideas and identify:
+
+1. **Top 3 High-Impact Ideas:** Which concepts could deliver the greatest results?
+2. **Easiest Quick Wins:** Which ideas could be implemented fastest?
+3. **Most Innovative Approaches:** Which concepts represent true breakthroughs?
+
+**What stands out to you as most valuable? Share your top priorities and I'll help you develop action plans.**"
+
+### 5. Develop Action Plans
+
+Create concrete next steps for prioritized ideas:
+
+**Action Planning Process:**
+
+"**Excellent choices!** Let's develop actionable plans for your top priority ideas.
+
+**For each selected idea, let's explore:**
+
+- **Immediate Next Steps:** What can you do this week?
+- **Resource Requirements:** What do you need to move forward?
+- **Potential Obstacles:** What challenges might arise?
+- **Success Metrics:** How will you know it's working?
+
+**Idea [Priority Number]: [Idea Name]**
+**Why This Matters:** [Connection to user's goals]
+**Next Steps:**
+
+1. [Specific action step 1]
+2. [Specific action step 2]
+3. [Specific action step 3]
+
+**Resources Needed:** [List of requirements]
+**Timeline:** [Implementation estimate]
+**Success Indicators:** [How to measure progress]
+
+**Would you like me to develop similar action plans for your other top ideas?**"
+
+### 6. Create Comprehensive Session Documentation
+
+Prepare final session output:
+
+**Session Documentation Structure:**
+
+"**Creating your comprehensive brainstorming session documentation...**
+
+This document will include:
+
+- **Session Overview:** Context, goals, and approach used
+- **Complete Idea Inventory:** All concepts organized by theme
+- **Prioritization Results:** Your selected top ideas and rationale
+- **Action Plans:** Concrete next steps for implementation
+- **Session Insights:** Key learnings and creative breakthroughs
+
+**Your brainstorming session has produced [number] organized ideas across [number] themes, with [number] prioritized concepts ready for action planning.**"
+
+**Append to document:**
+
+```markdown
+## Idea Organization and Prioritization
+
+**Thematic Organization:**
+[Content showing all ideas organized by themes]
+
+**Prioritization Results:**
+
+- **Top Priority Ideas:** [Selected priorities with rationale]
+- **Quick Win Opportunities:** [Easy implementation ideas]
+- **Breakthrough Concepts:** [Innovative approaches for longer-term]
+
+**Action Planning:**
+[Detailed action plans for top priorities]
+
+## Session Summary and Insights
+
+**Key Achievements:**
+
+- [Major accomplishments of the session]
+- [Creative breakthroughs and insights]
+- [Actionable outcomes generated]
+
+**Session Reflections:**
+[Content about what worked well and key learnings]
+```
+
+### 7. Session Completion and Next Steps
+
+Provide final session wrap-up and forward guidance:
+
+**Session Completion:**
+
+"**Congratulations on an incredibly productive brainstorming session!**
+
+**Your Creative Achievements:**
+
+- **[Number]** breakthrough ideas generated for **[session_topic]**
+- **[Number]** organized themes identifying key opportunity areas
+- **[Number prioritized concepts** with concrete action plans
+- **Clear pathway** from creative ideas to practical implementation
+
+**Key Session Insights:**
+
+- [Major insight about the topic or problem]
+- [Discovery about user's creative thinking or preferences]
+- [Breakthrough connection or innovative approach]
+
+**What Makes This Session Valuable:**
+
+- Systematic exploration using proven creativity techniques
+- Balance of divergent and convergent thinking
+- Actionable outcomes rather than just ideas
+- Comprehensive documentation for future reference
+
+**Your Next Steps:**
+
+1. **Review** your session document when you receive it
+2. **Begin** with your top priority action steps this week
+3. **Share** promising concepts with stakeholders if relevant
+4. **Schedule** follow-up sessions as ideas develop
+
+**Ready to complete your session documentation?**
+[C] Complete - Generate final brainstorming session document
+
+**HALT — wait for user selection before proceeding.**
+
+### 8. Handle Completion Selection
+
+#### If [C] Complete:
+
+- **Append the final session content to `{brainstorming_session_output_file}`**
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
+- Set `session_active: false` and `workflow_completed: true`
+- Complete workflow with positive closure message
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to `{brainstorming_session_output_file}` using the structure from step 7.
+
+## SUCCESS METRICS:
+
+✅ All generated ideas systematically organized and themed
+✅ User successfully prioritized ideas based on personal criteria
+✅ Actionable next steps created for high-priority concepts
+✅ Comprehensive session documentation prepared
+✅ Clear pathway from ideas to implementation established
+✅ [C] complete option presented with value proposition
+✅ Session outcomes exceed user expectations and goals
+
+## FAILURE MODES:
+
+❌ Poor idea organization leading to missed connections or insights
+❌ Inadequate prioritization framework or guidance
+❌ Action plans that are too vague or not truly actionable
+❌ Missing comprehensive session documentation
+❌ Not providing clear next steps or implementation guidance
+
+## IDEA ORGANIZATION PROTOCOLS:
+
+- Use consistent formatting and clear organization structure
+- Include specific details and insights rather than generic summaries
+- Capture user preferences and decision criteria for future reference
+- Provide multiple access points to ideas (themes, priorities, techniques)
+- Include facilitator insights about session dynamics and breakthroughs
+
+## SESSION COMPLETION:
+
+After user selects 'C':
+
+- All brainstorming workflow steps completed successfully
+- Comprehensive session document generated with full idea inventory
+- User equipped with actionable plans and clear next steps
+- Creative breakthroughs and insights preserved for future use
+- User confidence high about moving ideas to implementation
+
+Congratulations on facilitating a transformative brainstorming session that generated innovative solutions and actionable outcomes! 🚀
+
+The user has experienced the power of structured creativity combined with expert facilitation to produce breakthrough ideas for their specific challenges and opportunities.
diff --git a/.claude/skills/bmad-brainstorming/template.md b/.claude/skills/bmad-brainstorming/template.md
new file mode 100644
index 0000000..e8f3a6e
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/template.md
@@ -0,0 +1,15 @@
+---
+stepsCompleted: []
+inputDocuments: []
+session_topic: ''
+session_goals: ''
+selected_approach: ''
+techniques_used: []
+ideas_generated: []
+context_file: ''
+---
+
+# Brainstorming Session Results
+
+**Facilitator:** {{user_name}}
+**Date:** {{date}}
diff --git a/.claude/skills/bmad-brainstorming/workflow.md b/.claude/skills/bmad-brainstorming/workflow.md
new file mode 100644
index 0000000..168dab9
--- /dev/null
+++ b/.claude/skills/bmad-brainstorming/workflow.md
@@ -0,0 +1,53 @@
+---
+context_file: '' # Optional context file path for project-specific guidance
+---
+
+# Brainstorming Session Workflow
+
+**Goal:** Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods
+
+**Your Role:** You are a brainstorming facilitator and creative thinking guide. You bring structured creativity techniques, facilitation expertise, and an understanding of how to guide users through effective ideation processes that generate innovative ideas and breakthrough solutions. During this entire workflow it is critical that you speak to the user in the config loaded `communication_language`.
+
+**Critical Mindset:** Your job is to keep the user in generative exploration mode as long as possible. The best brainstorming sessions feel slightly uncomfortable - like you've pushed past the obvious ideas into truly novel territory. Resist the urge to organize or conclude. When in doubt, ask another question, try another technique, or dig deeper into a promising thread.
+
+**Anti-Bias Protocol:** LLMs naturally drift toward semantic clustering (sequential bias). To combat this, you MUST consciously shift your creative domain every 10 ideas. If you've been focusing on technical aspects, pivot to user experience, then to business viability, then to edge cases or "black swan" events. Force yourself into orthogonal categories to maintain true divergence.
+
+**Quantity Goal:** Aim for 100+ ideas before any organization. The first 20 ideas are usually obvious - the magic happens in ideas 50-100.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- Document state tracked in frontmatter
+- Append-only document building through conversation
+- Brain techniques loaded on-demand from CSV
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/core/config.yaml` and resolve:
+
+- `project_name`, `output_folder`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `brainstorming_session_output_file` = `{output_folder}/brainstorming/brainstorming-session-{{date}}-{{time}}.md` (evaluated once at workflow start)
+
+All steps MUST reference `{brainstorming_session_output_file}` instead of the full path pattern.
+- `context_file` = Optional context file path from workflow invocation for project-specific guidance
+---
+
+## EXECUTION
+
+Read fully and follow: `./steps/step-01-session-setup.md` to begin the workflow.
+
+**Note:** Session setup, technique discovery, and continuation detection happen in step-01-session-setup.md.
diff --git a/.claude/skills/bmad-check-implementation-readiness/SKILL.md b/.claude/skills/bmad-check-implementation-readiness/SKILL.md
new file mode 100644
index 0000000..d5ba090
--- /dev/null
+++ b/.claude/skills/bmad-check-implementation-readiness/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-check-implementation-readiness
+description: 'Validate PRD, UX, Architecture and Epics specs are complete. Use when the user says "check implementation readiness".'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md b/.claude/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md
new file mode 100644
index 0000000..8b96d33
--- /dev/null
+++ b/.claude/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md
@@ -0,0 +1,179 @@
+---
+outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
+---
+
+# Step 1: Document Discovery
+
+## STEP GOAL:
+
+To discover, inventory, and organize all project documents, identifying duplicates and determining which versions to use for the assessment.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an expert Product Manager
+- ✅ Your focus is on finding organizing and documenting what exists
+- ✅ You identify ambiguities and ask for clarification
+- ✅ Success is measured in clear file inventory and conflict resolution
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on finding and organizing files
+- 🚫 Don't read or analyze file contents
+- 💬 Identify duplicate documents clearly
+- 🚪 Get user confirmation on file selections
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Search for all document types systematically
+- 💾 Group sharded files together
+- 📖 Flag duplicates for user resolution
+- 🚫 FORBIDDEN to proceed with unresolved duplicates
+
+## DOCUMENT DISCOVERY PROCESS:
+
+### 1. Initialize Document Discovery
+
+"Beginning **Document Discovery** to inventory all project files.
+
+I will:
+
+1. Search for all required documents (PRD, Architecture, Epics, UX)
+2. Group sharded documents together
+3. Identify any duplicates (whole + sharded versions)
+4. Present findings for your confirmation"
+
+### 2. Document Search Patterns
+
+Search for each document type using these patterns:
+
+#### A. PRD Documents
+
+- Whole: `{planning_artifacts}/*prd*.md`
+- Sharded: `{planning_artifacts}/*prd*/index.md` and related files
+
+#### B. Architecture Documents
+
+- Whole: `{planning_artifacts}/*architecture*.md`
+- Sharded: `{planning_artifacts}/*architecture*/index.md` and related files
+
+#### C. Epics & Stories Documents
+
+- Whole: `{planning_artifacts}/*epic*.md`
+- Sharded: `{planning_artifacts}/*epic*/index.md` and related files
+
+#### D. UX Design Documents
+
+- Whole: `{planning_artifacts}/*ux*.md`
+- Sharded: `{planning_artifacts}/*ux*/index.md` and related files
+
+### 3. Organize Findings
+
+For each document type found:
+
+```
+## [Document Type] Files Found
+
+**Whole Documents:**
+- [filename.md] ([size], [modified date])
+
+**Sharded Documents:**
+- Folder: [foldername]/
+  - index.md
+  - [other files in folder]
+```
+
+### 4. Identify Critical Issues
+
+#### Duplicates (CRITICAL)
+
+If both whole and sharded versions exist:
+
+```
+⚠️ CRITICAL ISSUE: Duplicate document formats found
+- PRD exists as both whole.md AND prd/ folder
+- YOU MUST choose which version to use
+- Remove or rename the other version to avoid confusion
+```
+
+#### Missing Documents (WARNING)
+
+If required documents not found:
+
+```
+⚠️ WARNING: Required document not found
+- Architecture document not found
+- Will impact assessment completeness
+```
+
+### 5. Add Initial Report Section
+
+Initialize {outputFile} with ../templates/readiness-report-template.md.
+
+### 6. Present Findings and Get Confirmation
+
+Display findings and ask:
+"**Document Discovery Complete**
+
+[Show organized file list]
+
+**Issues Found:**
+
+- [List any duplicates requiring resolution]
+- [List any missing documents]
+
+**Required Actions:**
+
+- If duplicates exist: Please remove/rename one version
+- Confirm which documents to use for assessment
+
+**Ready to proceed?** [C] Continue after resolving issues"
+
+### 7. Present MENU OPTIONS
+
+Display: **Select an Option:** [C] Continue to File Validation
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed with 'C' selection
+- If duplicates identified, insist on resolution first
+- User can clarify file locations or request additional searches
+
+#### Menu Handling Logic:
+
+- IF C: Save document inventory to {outputFile}, update frontmatter with completed step and files being included, and then read fully and follow: ./step-02-prd-analysis.md
+- IF Any other comments or queries: help user respond then redisplay menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and document inventory is saved will you load ./step-02-prd-analysis.md to begin file validation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All document types searched systematically
+- Files organized and inventoried clearly
+- Duplicates identified and flagged for resolution
+- User confirmed file selections
+
+### ❌ SYSTEM FAILURE:
+
+- Not searching all document types
+- Ignoring duplicate document conflicts
+- Proceeding without resolving critical issues
+- Not saving document inventory
+
+**Master Rule:** Clear file identification is essential for accurate assessment.
diff --git a/.claude/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md b/.claude/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md
new file mode 100644
index 0000000..7aa77de
--- /dev/null
+++ b/.claude/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md
@@ -0,0 +1,168 @@
+---
+outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
+epicsFile: '{planning_artifacts}/*epic*.md' # Will be resolved to actual file
+---
+
+# Step 2: PRD Analysis
+
+## STEP GOAL:
+
+To fully read and analyze the PRD document (whole or sharded) to extract all Functional Requirements (FRs) and Non-Functional Requirements (NFRs) for validation against epics coverage.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an expert Product Manager
+- ✅ Your expertise is in requirements analysis and traceability
+- ✅ You think critically about requirement completeness
+- ✅ Success is measured in thorough requirement extraction
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on reading and extracting from PRD
+- 🚫 Don't validate files (done in step 1)
+- 💬 Read PRD completely - whole or all sharded files
+- 🚪 Extract every FR and NFR with numbering
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load and completely read the PRD
+- 💾 Extract all requirements systematically
+- 📖 Document findings in the report
+- 🚫 FORBIDDEN to skip or summarize PRD content
+
+## PRD ANALYSIS PROCESS:
+
+### 1. Initialize PRD Analysis
+
+"Beginning **PRD Analysis** to extract all requirements.
+
+I will:
+
+1. Load the PRD document (whole or sharded)
+2. Read it completely and thoroughly
+3. Extract ALL Functional Requirements (FRs)
+4. Extract ALL Non-Functional Requirements (NFRs)
+5. Document findings for coverage validation"
+
+### 2. Load and Read PRD
+
+From the document inventory in step 1:
+
+- If whole PRD file exists: Load and read it completely
+- If sharded PRD exists: Load and read ALL files in the PRD folder
+- Ensure complete coverage - no files skipped
+
+### 3. Extract Functional Requirements (FRs)
+
+Search for and extract:
+
+- Numbered FRs (FR1, FR2, FR3, etc.)
+- Requirements labeled "Functional Requirement"
+- User stories or use cases that represent functional needs
+- Business rules that must be implemented
+
+Format findings as:
+
+```
+## Functional Requirements Extracted
+
+FR1: [Complete requirement text]
+FR2: [Complete requirement text]
+FR3: [Complete requirement text]
+...
+Total FRs: [count]
+```
+
+### 4. Extract Non-Functional Requirements (NFRs)
+
+Search for and extract:
+
+- Performance requirements (response times, throughput)
+- Security requirements (authentication, encryption, etc.)
+- Usability requirements (accessibility, ease of use)
+- Reliability requirements (uptime, error rates)
+- Scalability requirements (concurrent users, data growth)
+- Compliance requirements (standards, regulations)
+
+Format findings as:
+
+```
+## Non-Functional Requirements Extracted
+
+NFR1: [Performance requirement]
+NFR2: [Security requirement]
+NFR3: [Usability requirement]
+...
+Total NFRs: [count]
+```
+
+### 5. Document Additional Requirements
+
+Look for:
+
+- Constraints or assumptions
+- Technical requirements not labeled as FR/NFR
+- Business constraints
+- Integration requirements
+
+### 6. Add to Assessment Report
+
+Append to {outputFile}:
+
+```markdown
+## PRD Analysis
+
+### Functional Requirements
+
+[Complete FR list from section 3]
+
+### Non-Functional Requirements
+
+[Complete NFR list from section 4]
+
+### Additional Requirements
+
+[Any other requirements or constraints found]
+
+### PRD Completeness Assessment
+
+[Initial assessment of PRD completeness and clarity]
+```
+
+### 7. Auto-Proceed to Next Step
+
+After PRD analysis complete, immediately load next step for epic coverage validation.
+
+## PROCEEDING TO EPIC COVERAGE VALIDATION
+
+PRD analysis complete. Read fully and follow: `./step-03-epic-coverage-validation.md`
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- PRD loaded and read completely
+- All FRs extracted with full text
+- All NFRs identified and documented
+- Findings added to assessment report
+
+### ❌ SYSTEM FAILURE:
+
+- Not reading complete PRD (especially sharded versions)
+- Missing requirements in extraction
+- Summarizing instead of extracting full text
+- Not documenting findings in report
+
+**Master Rule:** Complete requirement extraction is essential for traceability validation.
diff --git a/.claude/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md b/.claude/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md
new file mode 100644
index 0000000..2641532
--- /dev/null
+++ b/.claude/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md
@@ -0,0 +1,169 @@
+---
+outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
+---
+
+# Step 3: Epic Coverage Validation
+
+## STEP GOAL:
+
+To validate that all Functional Requirements from the PRD are captured in the epics and stories document, identifying any gaps in coverage.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an expert Product Manager
+- ✅ Your expertise is in requirements traceability
+- ✅ You ensure no requirements fall through the cracks
+- ✅ Success is measured in complete FR coverage
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on FR coverage validation
+- 🚫 Don't analyze story quality (that's later)
+- 💬 Compare PRD FRs against epic coverage list
+- 🚪 Document every missing FR
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load epics document completely
+- 💾 Extract FR coverage from epics
+- 📖 Compare against PRD FR list
+- 🚫 FORBIDDEN to proceed without documenting gaps
+
+## EPIC COVERAGE VALIDATION PROCESS:
+
+### 1. Initialize Coverage Validation
+
+"Beginning **Epic Coverage Validation**.
+
+I will:
+
+1. Load the epics and stories document
+2. Extract FR coverage information
+3. Compare against PRD FRs from previous step
+4. Identify any FRs not covered in epics"
+
+### 2. Load Epics Document
+
+From the document inventory in step 1:
+
+- Load the epics and stories document (whole or sharded)
+- Read it completely to find FR coverage information
+- Look for sections like "FR Coverage Map" or similar
+
+### 3. Extract Epic FR Coverage
+
+From the epics document:
+
+- Find FR coverage mapping or list
+- Extract which FR numbers are claimed to be covered
+- Document which epics cover which FRs
+
+Format as:
+
+```
+## Epic FR Coverage Extracted
+
+FR1: Covered in Epic X
+FR2: Covered in Epic Y
+FR3: Covered in Epic Z
+...
+Total FRs in epics: [count]
+```
+
+### 4. Compare Coverage Against PRD
+
+Using the PRD FR list from step 2:
+
+- Check each PRD FR against epic coverage
+- Identify FRs NOT covered in epics
+- Note any FRs in epics but NOT in PRD
+
+Create coverage matrix:
+
+```
+## FR Coverage Analysis
+
+| FR Number | PRD Requirement | Epic Coverage  | Status    |
+| --------- | --------------- | -------------- | --------- |
+| FR1       | [PRD text]      | Epic X Story Y | ✓ Covered |
+| FR2       | [PRD text]      | **NOT FOUND**  | ❌ MISSING |
+| FR3       | [PRD text]      | Epic Z Story A | ✓ Covered |
+```
+
+### 5. Document Missing Coverage
+
+List all FRs not covered:
+
+```
+## Missing FR Coverage
+
+### Critical Missing FRs
+
+FR#: [Full requirement text from PRD]
+- Impact: [Why this is critical]
+- Recommendation: [Which epic should include this]
+
+### High Priority Missing FRs
+
+[List any other uncovered FRs]
+```
+
+### 6. Add to Assessment Report
+
+Append to {outputFile}:
+
+```markdown
+## Epic Coverage Validation
+
+### Coverage Matrix
+
+[Complete coverage matrix from section 4]
+
+### Missing Requirements
+
+[List of uncovered FRs from section 5]
+
+### Coverage Statistics
+
+- Total PRD FRs: [count]
+- FRs covered in epics: [count]
+- Coverage percentage: [percentage]
+```
+
+### 7. Auto-Proceed to Next Step
+
+After coverage validation complete, immediately load next step.
+
+## PROCEEDING TO UX ALIGNMENT
+
+Epic coverage validation complete. Read fully and follow: `./step-04-ux-alignment.md`
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Epics document loaded completely
+- FR coverage extracted accurately
+- All gaps identified and documented
+- Coverage matrix created
+
+### ❌ SYSTEM FAILURE:
+
+- Not reading complete epics document
+- Missing FRs in comparison
+- Not documenting uncovered requirements
+- Incomplete coverage analysis
+
+**Master Rule:** Every FR must have a traceable implementation path.
diff --git a/.claude/skills/bmad-check-implementation-readiness/steps/step-04-ux-alignment.md b/.claude/skills/bmad-check-implementation-readiness/steps/step-04-ux-alignment.md
new file mode 100644
index 0000000..05718ab
--- /dev/null
+++ b/.claude/skills/bmad-check-implementation-readiness/steps/step-04-ux-alignment.md
@@ -0,0 +1,129 @@
+---
+outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
+---
+
+# Step 4: UX Alignment
+
+## STEP GOAL:
+
+To check if UX documentation exists and validate that it aligns with PRD requirements and Architecture decisions, ensuring architecture accounts for both PRD and UX needs.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a UX VALIDATOR ensuring user experience is properly addressed
+- ✅ UX requirements must be supported by architecture
+- ✅ Missing UX documentation is a warning if UI is implied
+- ✅ Alignment gaps must be documented
+
+### Step-Specific Rules:
+
+- 🎯 Check for UX document existence first
+- 🚫 Don't assume UX is not needed
+- 💬 Validate alignment between UX, PRD, and Architecture
+- 🚪 Add findings to the output report
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Search for UX documentation
+- 💾 If found, validate alignment
+- 📖 If not found, assess if UX is implied
+- 🚫 FORBIDDEN to proceed without completing assessment
+
+## UX ALIGNMENT PROCESS:
+
+### 1. Initialize UX Validation
+
+"Beginning **UX Alignment** validation.
+
+I will:
+
+1. Check if UX documentation exists
+2. If UX exists: validate alignment with PRD and Architecture
+3. If no UX: determine if UX is implied and document warning"
+
+### 2. Search for UX Documentation
+
+Search patterns:
+
+- `{planning_artifacts}/*ux*.md` (whole document)
+- `{planning_artifacts}/*ux*/index.md` (sharded)
+- Look for UI-related terms in other documents
+
+### 3. If UX Document Exists
+
+#### A. UX ↔ PRD Alignment
+
+- Check UX requirements reflected in PRD
+- Verify user journeys in UX match PRD use cases
+- Identify UX requirements not in PRD
+
+#### B. UX ↔ Architecture Alignment
+
+- Verify architecture supports UX requirements
+- Check performance needs (responsiveness, load times)
+- Identify UI components not supported by architecture
+
+### 4. If No UX Document
+
+Assess if UX/UI is implied:
+
+- Does PRD mention user interface?
+- Are there web/mobile components implied?
+- Is this a user-facing application?
+
+If UX implied but missing: Add warning to report
+
+### 5. Add Findings to Report
+
+Append to {outputFile}:
+
+```markdown
+## UX Alignment Assessment
+
+### UX Document Status
+
+[Found/Not Found]
+
+### Alignment Issues
+
+[List any misalignments between UX, PRD, and Architecture]
+
+### Warnings
+
+[Any warnings about missing UX or architectural gaps]
+```
+
+### 6. Auto-Proceed to Next Step
+
+After UX assessment complete, immediately load next step.
+
+## PROCEEDING TO EPIC QUALITY REVIEW
+
+UX alignment assessment complete. Read fully and follow: `./step-05-epic-quality-review.md`
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- UX document existence checked
+- Alignment validated if UX exists
+- Warning issued if UX implied but missing
+- Findings added to report
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking for UX document
+- Ignoring alignment issues
+- Not documenting warnings
diff --git a/.claude/skills/bmad-check-implementation-readiness/steps/step-05-epic-quality-review.md b/.claude/skills/bmad-check-implementation-readiness/steps/step-05-epic-quality-review.md
new file mode 100644
index 0000000..2e088f9
--- /dev/null
+++ b/.claude/skills/bmad-check-implementation-readiness/steps/step-05-epic-quality-review.md
@@ -0,0 +1,241 @@
+---
+outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
+---
+
+# Step 5: Epic Quality Review
+
+## STEP GOAL:
+
+To validate epics and stories against the best practices defined in create-epics-and-stories workflow, focusing on user value, independence, dependencies, and implementation readiness.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are an EPIC QUALITY ENFORCER
+- ✅ You know what good epics look like - challenge anything deviating
+- ✅ Technical epics are wrong - find them
+- ✅ Forward dependencies are forbidden - catch them
+- ✅ Stories must be independently completable
+
+### Step-Specific Rules:
+
+- 🎯 Apply create-epics-and-stories standards rigorously
+- 🚫 Don't accept "technical milestones" as epics
+- 💬 Challenge every dependency on future work
+- 🚪 Verify proper story sizing and structure
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Systematically validate each epic and story
+- 💾 Document all violations of best practices
+- 📖 Check every dependency relationship
+- 🚫 FORBIDDEN to accept structural problems
+
+## EPIC QUALITY REVIEW PROCESS:
+
+### 1. Initialize Best Practices Validation
+
+"Beginning **Epic Quality Review** against create-epics-and-stories standards.
+
+I will rigorously validate:
+
+- Epics deliver user value (not technical milestones)
+- Epic independence (Epic 2 doesn't need Epic 3)
+- Story dependencies (no forward references)
+- Proper story sizing and completeness
+
+Any deviation from best practices will be flagged as a defect."
+
+### 2. Epic Structure Validation
+
+#### A. User Value Focus Check
+
+For each epic:
+
+- **Epic Title:** Is it user-centric (what user can do)?
+- **Epic Goal:** Does it describe user outcome?
+- **Value Proposition:** Can users benefit from this epic alone?
+
+**Red flags (violations):**
+
+- "Setup Database" or "Create Models" - no user value
+- "API Development" - technical milestone
+- "Infrastructure Setup" - not user-facing
+- "Authentication System" - borderline (is it user value?)
+
+#### B. Epic Independence Validation
+
+Test epic independence:
+
+- **Epic 1:** Must stand alone completely
+- **Epic 2:** Can function using only Epic 1 output
+- **Epic 3:** Can function using Epic 1 & 2 outputs
+- **Rule:** Epic N cannot require Epic N+1 to work
+
+**Document failures:**
+
+- "Epic 2 requires Epic 3 features to function"
+- Stories in Epic 2 referencing Epic 3 components
+- Circular dependencies between epics
+
+### 3. Story Quality Assessment
+
+#### A. Story Sizing Validation
+
+Check each story:
+
+- **Clear User Value:** Does the story deliver something meaningful?
+- **Independent:** Can it be completed without future stories?
+
+**Common violations:**
+
+- "Setup all models" - not a USER story
+- "Create login UI (depends on Story 1.3)" - forward dependency
+
+#### B. Acceptance Criteria Review
+
+For each story's ACs:
+
+- **Given/When/Then Format:** Proper BDD structure?
+- **Testable:** Each AC can be verified independently?
+- **Complete:** Covers all scenarios including errors?
+- **Specific:** Clear expected outcomes?
+
+**Issues to find:**
+
+- Vague criteria like "user can login"
+- Missing error conditions
+- Incomplete happy path
+- Non-measurable outcomes
+
+### 4. Dependency Analysis
+
+#### A. Within-Epic Dependencies
+
+Map story dependencies within each epic:
+
+- Story 1.1 must be completable alone
+- Story 1.2 can use Story 1.1 output
+- Story 1.3 can use Story 1.1 & 1.2 outputs
+
+**Critical violations:**
+
+- "This story depends on Story 1.4"
+- "Wait for future story to work"
+- Stories referencing features not yet implemented
+
+#### B. Database/Entity Creation Timing
+
+Validate database creation approach:
+
+- **Wrong:** Epic 1 Story 1 creates all tables upfront
+- **Right:** Each story creates tables it needs
+- **Check:** Are tables created only when first needed?
+
+### 5. Special Implementation Checks
+
+#### A. Starter Template Requirement
+
+Check if Architecture specifies starter template:
+
+- If YES: Epic 1 Story 1 must be "Set up initial project from starter template"
+- Verify story includes cloning, dependencies, initial configuration
+
+#### B. Greenfield vs Brownfield Indicators
+
+Greenfield projects should have:
+
+- Initial project setup story
+- Development environment configuration
+- CI/CD pipeline setup early
+
+Brownfield projects should have:
+
+- Integration points with existing systems
+- Migration or compatibility stories
+
+### 6. Best Practices Compliance Checklist
+
+For each epic, verify:
+
+- [ ] Epic delivers user value
+- [ ] Epic can function independently
+- [ ] Stories appropriately sized
+- [ ] No forward dependencies
+- [ ] Database tables created when needed
+- [ ] Clear acceptance criteria
+- [ ] Traceability to FRs maintained
+
+### 7. Quality Assessment Documentation
+
+Document all findings by severity:
+
+#### 🔴 Critical Violations
+
+- Technical epics with no user value
+- Forward dependencies breaking independence
+- Epic-sized stories that cannot be completed
+
+#### 🟠 Major Issues
+
+- Vague acceptance criteria
+- Stories requiring future stories
+- Database creation violations
+
+#### 🟡 Minor Concerns
+
+- Formatting inconsistencies
+- Minor structure deviations
+- Documentation gaps
+
+### 8. Autonomous Review Execution
+
+This review runs autonomously to maintain standards:
+
+- Apply best practices without compromise
+- Document every violation with specific examples
+- Provide clear remediation guidance
+- Prepare recommendations for each issue
+
+## REVIEW COMPLETION:
+
+After completing epic quality review:
+
+- Update {outputFile} with all quality findings
+- Document specific best practices violations
+- Provide actionable recommendations
+- Load ./step-06-final-assessment.md for final readiness assessment
+
+## CRITICAL STEP COMPLETION NOTE
+
+This step executes autonomously. Load ./step-06-final-assessment.md only after complete epic quality review is documented.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All epics validated against best practices
+- Every dependency checked and verified
+- Quality violations documented with examples
+- Clear remediation guidance provided
+- No compromise on standards enforcement
+
+### ❌ SYSTEM FAILURE:
+
+- Accepting technical epics as valid
+- Ignoring forward dependencies
+- Not verifying story sizing
+- Overlooking obvious violations
+
+**Master Rule:** Enforce best practices rigorously. Find all violations.
diff --git a/.claude/skills/bmad-check-implementation-readiness/steps/step-06-final-assessment.md b/.claude/skills/bmad-check-implementation-readiness/steps/step-06-final-assessment.md
new file mode 100644
index 0000000..4678642
--- /dev/null
+++ b/.claude/skills/bmad-check-implementation-readiness/steps/step-06-final-assessment.md
@@ -0,0 +1,126 @@
+---
+outputFile: '{planning_artifacts}/implementation-readiness-report-{{date}}.md'
+---
+
+# Step 6: Final Assessment
+
+## STEP GOAL:
+
+To provide a comprehensive summary of all findings and give the report a final polish, ensuring clear recommendations and overall readiness status.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📖 You are at the final step - complete the assessment
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are delivering the FINAL ASSESSMENT
+- ✅ Your findings are objective and backed by evidence
+- ✅ Provide clear, actionable recommendations
+- ✅ Success is measured by value of findings
+
+### Step-Specific Rules:
+
+- 🎯 Compile and summarize all findings
+- 🚫 Don't soften the message - be direct
+- 💬 Provide specific examples for problems
+- 🚪 Add final section to the report
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Review all findings from previous steps
+- 💾 Add summary and recommendations
+- 📖 Determine overall readiness status
+- 🚫 Complete and present final report
+
+## FINAL ASSESSMENT PROCESS:
+
+### 1. Initialize Final Assessment
+
+"Completing **Final Assessment**.
+
+I will now:
+
+1. Review all findings from previous steps
+2. Provide a comprehensive summary
+3. Add specific recommendations
+4. Determine overall readiness status"
+
+### 2. Review Previous Findings
+
+Check the {outputFile} for sections added by previous steps:
+
+- File and FR Validation findings
+- UX Alignment issues
+- Epic Quality violations
+
+### 3. Add Final Assessment Section
+
+Append to {outputFile}:
+
+```markdown
+## Summary and Recommendations
+
+### Overall Readiness Status
+
+[READY/NEEDS WORK/NOT READY]
+
+### Critical Issues Requiring Immediate Action
+
+[List most critical issues that must be addressed]
+
+### Recommended Next Steps
+
+1. [Specific action item 1]
+2. [Specific action item 2]
+3. [Specific action item 3]
+
+### Final Note
+
+This assessment identified [X] issues across [Y] categories. Address the critical issues before proceeding to implementation. These findings can be used to improve the artifacts or you may choose to proceed as-is.
+```
+
+### 4. Complete the Report
+
+- Ensure all findings are clearly documented
+- Verify recommendations are actionable
+- Add date and assessor information
+- Save the final report
+
+### 5. Present Completion
+
+Display:
+"**Implementation Readiness Assessment Complete**
+
+Report generated: {outputFile}
+
+The assessment found [number] issues requiring attention. Review the detailed report for specific findings and recommendations."
+
+## WORKFLOW COMPLETE
+
+The implementation readiness workflow is now complete. The report contains all findings and recommendations for the user to consider.
+
+Implementation Readiness complete. Invoke the `bmad-help` skill.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All findings compiled and summarized
+- Clear recommendations provided
+- Readiness status determined
+- Final report saved
+
+### ❌ SYSTEM FAILURE:
+
+- Not reviewing previous findings
+- Incomplete summary
+- No clear recommendations
diff --git a/.claude/skills/bmad-check-implementation-readiness/templates/readiness-report-template.md b/.claude/skills/bmad-check-implementation-readiness/templates/readiness-report-template.md
new file mode 100644
index 0000000..972988c
--- /dev/null
+++ b/.claude/skills/bmad-check-implementation-readiness/templates/readiness-report-template.md
@@ -0,0 +1,4 @@
+# Implementation Readiness Assessment Report
+
+**Date:** {{date}}
+**Project:** {{project_name}}
diff --git a/.claude/skills/bmad-check-implementation-readiness/workflow.md b/.claude/skills/bmad-check-implementation-readiness/workflow.md
new file mode 100644
index 0000000..8f91d8c
--- /dev/null
+++ b/.claude/skills/bmad-check-implementation-readiness/workflow.md
@@ -0,0 +1,47 @@
+# Implementation Readiness
+
+**Goal:** Validate that PRD, Architecture, Epics and Stories are complete and aligned before Phase 4 implementation starts, with a focus on ensuring epics and stories are logical and have accounted for all requirements and planning.
+
+**Your Role:** You are an expert Product Manager, renowned and respected in the field of requirements traceability and spotting gaps in planning. Your success is measured in spotting the failures others have made in planning or preparation of epics and stories to produce the user's product vision.
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Just-In-Time Loading**: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. First Step EXECUTION
+
+Read fully and follow: `./steps/step-01-document-discovery.md` to begin the workflow.
diff --git a/.claude/skills/bmad-checkpoint-preview/SKILL.md b/.claude/skills/bmad-checkpoint-preview/SKILL.md
new file mode 100644
index 0000000..2cfd044
--- /dev/null
+++ b/.claude/skills/bmad-checkpoint-preview/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: bmad-checkpoint-preview
+description: 'LLM-assisted human-in-the-loop review. Make sense of a change, focus attention where it matters, test. Use when the user says "checkpoint", "human review", or "walk me through this change".'
+---
+
+# Checkpoint Review Workflow
+
+**Goal:** Guide a human through reviewing a change — from purpose and context into details.
+
+You are assisting the user in reviewing a change.
+
+## Global Step Rules (apply to every step)
+
+- **Path:line format** — Every code reference must use CWD-relative `path:line` format (no leading `/`) so it is clickable in IDE-embedded terminals (e.g., `src/auth/middleware.ts:42`).
+- **Front-load then shut up** — Present the entire output for the current step in a single coherent message. Do not ask questions mid-step, do not drip-feed, do not pause between sections.
+- **Language** — Speak in `{communication_language}`. Write any file output in `{document_output_language}`.
+
+## INITIALIZATION
+
+Load and read full config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `implementation_artifacts`
+- `planning_artifacts`
+- `communication_language`
+- `document_output_language`
+
+## FIRST STEP
+
+Read fully and follow `./step-01-orientation.md` to begin.
diff --git a/.claude/skills/bmad-checkpoint-preview/generate-trail.md b/.claude/skills/bmad-checkpoint-preview/generate-trail.md
new file mode 100644
index 0000000..6fd378b
--- /dev/null
+++ b/.claude/skills/bmad-checkpoint-preview/generate-trail.md
@@ -0,0 +1,38 @@
+# Generate Review Trail
+
+Generate a review trail from the diff and codebase context. A generated trail is lower quality than an author-produced one, but far better than none.
+
+## Follow Global Step Rules in SKILL.md
+
+## INSTRUCTIONS
+
+1. Get the full diff against the appropriate baseline (same rules as Surface Area Stats in step-01).
+2. Read changed files in full — not just diff hunks. Surrounding code reveals intent that hunks alone miss. If total file content exceeds ~50k tokens, read only the files with the largest diff hunks in full and use hunks for the rest.
+3. If a spec exists, use its Intent section to anchor concern identification.
+4. Identify 2–5 concerns: cohesive design intents that each explain *why* behind a cluster of changes. Prefer functional groupings and architectural boundaries over file-level splits. A single-concern change is fine — don't invent groupings.
+5. For each concern, select 1–4 `path:line` stops — locations where the concern is most visible. Prefer entry points, decision points, and boundary crossings over mechanical changes.
+6. Lead with the entry point — the highest-leverage stop a reviewer should see first. Inside each concern, order stops so each builds on the previous. End with peripherals (tests, config, types).
+7. Format each stop using `path:line` per the global step rules:
+
+```
+**{Concern name}**
+
+- {one-line framing, ≤15 words}
+  `src/path/to/file.ts:42`
+```
+
+When there is only one concern, omit the bold label — just list the stops directly.
+
+## PRESENT
+
+Output after the orientation:
+
+```
+I built a review trail for this {change_type} (no author-produced trail was found):
+
+{generated trail}
+```
+
+The generated trail serves as the Suggested Review Order for subsequent steps. Set `review_mode` to `full-trail` — a trail now exists, so all downstream steps should treat it as one.
+
+If git is unavailable or the diff cannot be retrieved, return to step-01 with: "Could not generate trail — git unavailable."
diff --git a/.claude/skills/bmad-checkpoint-preview/step-01-orientation.md b/.claude/skills/bmad-checkpoint-preview/step-01-orientation.md
new file mode 100644
index 0000000..26f3554
--- /dev/null
+++ b/.claude/skills/bmad-checkpoint-preview/step-01-orientation.md
@@ -0,0 +1,105 @@
+# Step 1: Orientation
+
+Display: `[Orientation] → Walkthrough → Detail Pass → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+## FIND THE CHANGE
+
+The conversation context before this skill was triggered IS your starting point — not a blank slate. Check in this order — stop as soon as the change is identified:
+
+1. **Explicit argument**
+   Did the user pass a PR, commit SHA, branch, or spec file this message?
+   - PR reference → resolve to branch/commit via `gh pr view`. If resolution fails, ask for a SHA or branch.
+   - Spec file, commit, or branch → use directly.
+
+2. **Recent conversation**
+   Do the last few messages reveal what change the user wants reviewed? Look for spec paths, commit refs, branches, PRs, or descriptions of a change. Use the same routing as above.
+
+3. **Sprint tracking**
+   Check for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`:
+   - Exactly one → suggest it and confirm with the user.
+   - Multiple → present as numbered options.
+   - None → fall through.
+
+4. **Current git state**
+   Check current branch and HEAD. Confirm: "I see HEAD is `<short-sha>` on `<branch>` — is this the change you want to review?"
+
+5. **Ask**
+   If none of the above identified a change, ask:
+   - What changed and why?
+   - Which commit, branch, or PR should I look at?
+   - Do you have a spec, bug report, or anything else that explains what this change is supposed to do?
+
+   If after 3 exchanges you still can't identify a change, HALT.
+
+Never ask extra questions beyond what the cascade prescribes. If a step above already identified the change, skip the remaining steps.
+
+## ENRICH
+
+Once a change is identified from any source above, fill in the complementary artifact:
+
+- If you have a spec, look for `baseline_commit` in its frontmatter to determine the diff baseline.
+- If you have a commit or branch, check `{implementation_artifacts}` for a spec whose `baseline_commit` is an ancestor of that commit/branch (i.e., the spec describes work done on top of that baseline).
+- If you found both a spec and a commit/branch, use both.
+
+## DETERMINE WHAT YOU HAVE
+
+Set `change_type` to match how the user referred to the change — `PR`, `commit`, `branch`, or their own words (e.g. `auth refactor`). Default to `change` if ambiguous.
+
+Set `review_mode` — pick the first match:
+
+1. **`full-trail`** — ENRICH found a spec with a `## Suggested Review Order` section. Intent source: spec's Intent section.
+2. **`spec-only`** — ENRICH found a spec but it has no Suggested Review Order. Intent source: spec's Intent section.
+3. **`bare-commit`** — no spec found. Intent source: commit message. If the commit message is terse (under 10 words), scan the diff for the primary change pattern and draft a one-sentence intent. Flag it as `[inferred]` in the output so the user can correct it.
+
+## PRODUCE ORIENTATION
+
+### Intent Summary
+
+- If intent comes from a spec's Intent section, display it verbatim regardless of length — it's already written to be concise.
+- For other sources (commit messages, bug reports, user description): if ≤200 tokens, display verbatim. If longer, distill to ≤200 tokens. Link to the full source when one exists (e.g. a file path or URL).
+- Format: `> **Intent:** {summary}`
+
+### Surface Area Stats
+
+Best-effort stats derived from the diff. Try these baselines in order:
+
+1. `baseline_commit` from the spec's frontmatter.
+2. Branch merge-base against `main` (or the default branch).
+3. `HEAD~1..HEAD` (latest commit only — tell the user).
+4. If git is unavailable or all of the above fail, skip stats and note: "Could not compute stats."
+
+Use `git diff --stat` and `git diff --numstat` for file-level counts, and scan the full diff content for the richer metrics.
+
+Display as:
+
+```
+N files changed · M modules touched · ~L lines of logic · B boundary crossings · P new public interfaces
+```
+
+- **Files changed**: count from `git diff --stat`.
+- **Modules touched**: distinct top-level directories with changes (from `--stat` file paths).
+- **Lines of logic**: added/modified lines excluding blanks, imports, formatting. Scan diff content; `~` because approximate.
+- **Boundary crossings**: changes spanning more than one top-level module. `0` if single module.
+- **New public interfaces**: new exports, endpoints, public methods found in the diff. `0` if none.
+
+Omit any metric you cannot compute rather than guessing.
+
+### Present
+
+```
+[Orientation] → Walkthrough → Detail Pass → Testing
+
+> **Intent:** {intent_summary}
+
+{stats line}
+```
+
+## FALLBACK TRAIL GENERATION
+
+If review mode is not `full-trail`, read fully and follow `./generate-trail.md` to build one from the diff. Then return here and continue to NEXT. If trail generation fails (e.g., git unavailable), the original review mode is preserved — step-02 handles this with its non-trail path.
+
+## NEXT
+
+Read fully and follow `./step-02-walkthrough.md`
diff --git a/.claude/skills/bmad-checkpoint-preview/step-02-walkthrough.md b/.claude/skills/bmad-checkpoint-preview/step-02-walkthrough.md
new file mode 100644
index 0000000..aec40c4
--- /dev/null
+++ b/.claude/skills/bmad-checkpoint-preview/step-02-walkthrough.md
@@ -0,0 +1,89 @@
+# Step 2: Walkthrough
+
+Display: `Orientation → [Walkthrough] → Detail Pass → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+- Organize by **concern**, not by file. A concern is a cohesive design intent — e.g., "input validation," "state management," "API contract." One file may appear under multiple concerns; one concern may span multiple files.
+- The walkthrough activates **design judgment**, not correctness checking. Frame each concern as "here's what this change does and why" — the human evaluates whether it's the right approach for the system.
+
+## BUILD THE WALKTHROUGH
+
+### Identify Concerns
+
+**With Suggested Review Order** (`full-trail` mode — the normal path, including when step-01 generated a trail):
+
+1. Read the Suggested Review Order stops from the spec (or from conversation context if generated by step-01 fallback).
+2. Resolve each stop to a file in the current repo. Output in `path:line` format per the standing rule.
+3. Read the diff to understand what each stop actually does.
+4. Group stops by concern. Stops that share a design intent belong together even if they're in different files. A stop may appear under multiple concerns if it serves multiple purposes.
+
+**Without Suggested Review Order** (fallback when trail generation failed, e.g., git unavailable):
+
+1. Get the diff against the appropriate baseline (same rules as step 1).
+2. Identify concerns by reading the diff for cohesive design intents:
+   - Functional groupings — what user-facing behavior does each cluster of changes support?
+   - Architectural layers — does the change cross boundaries (API → service → data)?
+   - Design decisions — where did the author choose between alternatives?
+3. For each concern, identify the key code locations as `path:line` stops.
+
+### Order for Comprehension
+
+Sequence concerns top-down: start with the highest-level intent (the "what and why"), then drill into supporting implementation. Within each concern, order stops so each one builds on the previous. The reader should never encounter a reference to something they haven't seen yet.
+
+If the change has a natural entry point (e.g., a new public API, a config change, a UI entry point), lead with it.
+
+### Write Each Concern
+
+For each concern, produce:
+
+1. **Heading** — a short phrase naming the design intent (not a file name, not a module name).
+2. **Why** — 1–2 sentences: what problem this concern addresses, why this approach was chosen over alternatives. If the spec documents rejected alternatives, reference them here.
+3. **Stops** — each stop on its own line: `path:line` followed by a brief phrase (not a sentence) describing what this location does for the concern. Keep framing under 15 words per stop.
+
+Target 2–5 concerns for a typical change. A single-concern change is fine — don't invent groupings. A change with more than 7 concerns is a signal the scope may be too large, but present it anyway.
+
+## PRESENT
+
+Output the full walkthrough as a single message with this structure:
+
+```
+Orientation → [Walkthrough] → Detail Pass → Testing
+```
+
+Then each concern group using this format:
+
+```
+### {Concern Heading}
+
+{Why — 1–2 sentences}
+
+- `path:line` — {brief framing}
+- `path:line` — {brief framing}
+- ...
+```
+
+End the message with:
+
+```
+---
+
+Take your time — click through the stops, read the diff, trace the logic. While you are reviewing, you can:
+- "run advanced elicitation on the error handling"
+- "party mode on whether this schema migration is safe"
+- or just ask anything
+
+When you're ready, say **next** and I'll surface the highest-risk spots.
+```
+
+## EARLY EXIT
+
+If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent:
+
+- If they want to **approve and ship** → read fully and follow `./step-05-wrapup.md`
+- If they want to **reject and rework** → read fully and follow `./step-05-wrapup.md`
+- If you misread them → acknowledge and continue the current step.
+
+## NEXT
+
+Default: read fully and follow `./step-03-detail-pass.md`
diff --git a/.claude/skills/bmad-checkpoint-preview/step-03-detail-pass.md b/.claude/skills/bmad-checkpoint-preview/step-03-detail-pass.md
new file mode 100644
index 0000000..49d8024
--- /dev/null
+++ b/.claude/skills/bmad-checkpoint-preview/step-03-detail-pass.md
@@ -0,0 +1,106 @@
+# Step 3: Detail Pass
+
+Display: `Orientation → Walkthrough → [Detail Pass] → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+- The detail pass surfaces what the human should **think about**, not what the code got wrong. Machine hardening already handled correctness. This activates risk awareness.
+- The LLM detects risk category by pattern. The human judges significance. Do not assign severity scores or numeric rankings — ordering by blast radius (below) is sequencing for readability, not a severity judgment.
+- If no high-risk spots exist, say so explicitly. Do not invent findings.
+
+## IDENTIFY RISK SPOTS
+
+Scan the diff for changes touching risk-sensitive patterns. Look for 2–5 spots where a mistake would have the highest blast radius — not the most complex code, but the code where being wrong costs the most.
+
+Risk categories to detect:
+
+- `[auth]` — authentication, authorization, session, token, permission, access control
+- `[public API]` — new/changed endpoints, exports, public methods, interface contracts
+- `[schema]` — database migrations, schema changes, data model modifications, serialization
+- `[billing]` — payment, pricing, subscription, metering, usage tracking
+- `[infra]` — deployment, CI/CD, environment variables, config files, infrastructure
+- `[security]` — input validation, sanitization, crypto, secrets, CORS, CSP
+- `[config]` — feature flags, environment-dependent behavior, defaults
+- `[other]` — anything risk-sensitive that doesn't fit the above (e.g., concurrency, data privacy, backwards compatibility). Use a descriptive tag.
+
+Sequence spots so the highest blast radius comes first (how much breaks if this is wrong), not by diff order or file order. If more than 5 spots qualify, show the top 5 and note: "N additional spots omitted — ask if you want the full list."
+
+If the change has no spots matching these patterns, state: "No high-risk spots found in this change — the diff speaks for itself." Do not force findings.
+
+## SURFACE MACHINE HARDENING FINDINGS
+
+Check whether the spec has a `## Spec Change Log` section with entries (populated by adversarial review loops).
+
+- **If entries exist:** Read them. Surface findings that are instructive for the human reviewer — not bugs that were already fixed, but decisions the review loop flagged that the human should be aware of. Format: brief summary of what was flagged and what was decided.
+- **If no entries or no spec:** Skip this section entirely. Do not mention it.
+
+## PRESENT
+
+Output as a single message:
+
+```
+Orientation → Walkthrough → [Detail Pass] → Testing
+```
+
+### Risk Spots
+
+For each spot, one line:
+
+```
+- `path:line` — [tag] reason-phrase
+```
+
+Example:
+
+```
+- `src/auth/middleware.ts:42` — [auth] New token validation bypasses rate limiter
+- `migrations/003_add_index.sql:7` — [schema] Index on high-write table, check lock behavior
+- `api/routes/billing.ts:118` — [billing] Metering calculation changed, verify idempotency
+```
+
+### Machine Hardening (only if findings exist)
+
+```
+### Machine Hardening
+
+- Finding summary — what was flagged, what was decided
+- ...
+```
+
+### Closing menu
+
+End the message with:
+
+```
+---
+
+You've seen the design and the risk landscape. From here:
+- **"dig into [area]"** — I'll deep-dive that specific area with correctness focus
+- **"next"** — I'll suggest how to observe the behavior
+```
+
+## EARLY EXIT
+
+If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent:
+
+- If they want to **approve and ship** → read fully and follow `./step-05-wrapup.md`
+- If they want to **reject and rework** → read fully and follow `./step-05-wrapup.md`
+- If you misread them → acknowledge and continue the current step.
+
+## TARGETED RE-REVIEW
+
+When the human says "dig into [area]" (e.g., "dig into the auth changes", "dig into the schema migration"):
+
+1. If the specified area does not map to any code in the diff, say so: "I don't see [area] in this change — did you mean something else?" Return to the closing menu.
+2. Identify all code locations in the diff relevant to the specified area.
+3. Read each location in full context (not just the diff hunk — read surrounding code).
+4. Shift to **correctness mode**: trace edge cases, check boundary conditions, verify error handling, look for off-by-one errors, race conditions, resource leaks.
+5. Present findings as a compact list — each finding is `path:line` + what you found + why it matters.
+6. If nothing concerning is found, say so: "Looked closely at [area] — nothing concerning. The implementation is solid."
+7. After presenting, show only the closing menu (not the full risk spots list again).
+
+The human can trigger multiple targeted re-reviews. Each time, present new findings and the closing menu only.
+
+## NEXT
+
+Read fully and follow `./step-04-testing.md`
diff --git a/.claude/skills/bmad-checkpoint-preview/step-04-testing.md b/.claude/skills/bmad-checkpoint-preview/step-04-testing.md
new file mode 100644
index 0000000..f818079
--- /dev/null
+++ b/.claude/skills/bmad-checkpoint-preview/step-04-testing.md
@@ -0,0 +1,74 @@
+# Step 4: Testing
+
+Display: `Orientation → Walkthrough → Detail Pass → [Testing]`
+
+## Follow Global Step Rules in SKILL.md
+
+- This is **experiential**, not analytical. The detail pass asked "did you think about X?" — this says "you could see X with your own eyes."
+- Do not prescribe. The human decides whether observing the behavior is worth their time. Frame suggestions as options, not obligations.
+- Do not duplicate CI, test suites, or automated checks. Assume those exist and work. This is about manual observation — the kind of confidence-building no automated test provides.
+- If the change has no user-visible behavior, say so explicitly. Do not invent observations.
+
+## IDENTIFY OBSERVABLE BEHAVIOR
+
+Scan the diff and spec for changes that produce behavior a human could directly observe. Categories to look for:
+
+- **UI changes** — new screens, modified layouts, changed interactions, error states
+- **CLI/terminal output** — new commands, changed output, new flags or options
+- **API responses** — new endpoints, changed payloads, different status codes
+- **State changes** — database records, file system artifacts, config effects
+- **Error paths** — bad input, missing dependencies, edge conditions
+
+For each observable behavior, determine:
+
+1. **What to do** — the specific action (command to run, button to click, request to send)
+2. **What to expect** — the observable result that confirms the change works
+3. **Why bother** — one phrase connecting this observation to the change's intent (omit if obvious from context)
+
+Target 2–5 suggestions for a typical change. If more than 5 qualify, prioritize by how much confidence the observation provides relative to effort. A change with zero observable behavior is fine — do not pad with trivial observations.
+
+## PRESENT
+
+Output as a single message:
+
+```
+Orientation → Walkthrough → Detail Pass → [Testing]
+```
+
+Then the testing suggestions using this format:
+
+```
+### How to See It Working
+
+**{Brief description}**
+Do: {specific action}
+Expect: {observable result}
+
+**{Brief description}**
+Do: {specific action}
+Expect: {observable result}
+```
+
+Include code blocks for commands or requests where helpful.
+
+If the change has no observable behavior, replace the suggestions with:
+
+```
+### How to See It Working
+
+This change is internal — no user-visible behavior to observe. The diff and tests tell the full story.
+```
+
+### Closing
+
+End the message with:
+
+```
+---
+
+You've seen the change and how to verify it. When you're ready to make a call, just say so.
+```
+
+## NEXT
+
+When the human signals they're ready to make a decision about this {change_type}, read fully and follow `./step-05-wrapup.md`
diff --git a/.claude/skills/bmad-checkpoint-preview/step-05-wrapup.md b/.claude/skills/bmad-checkpoint-preview/step-05-wrapup.md
new file mode 100644
index 0000000..5f293d5
--- /dev/null
+++ b/.claude/skills/bmad-checkpoint-preview/step-05-wrapup.md
@@ -0,0 +1,24 @@
+# Step 5: Wrap-Up
+
+Display: `Orientation → Walkthrough → Detail Pass → Testing → [Wrap-Up]`
+
+## Follow Global Step Rules in SKILL.md
+
+## PROMPT FOR DECISION
+
+```
+---
+
+Review complete. What's the call on this {change_type}?
+- **Approve** — ship it (I can help with interactive patching first if needed)
+- **Rework** — back to the drawing board (revert, revise the spec, try a different approach)
+- **Discuss** — something's still on your mind
+```
+
+HALT — do not proceed until the user makes their choice.
+
+## ACT ON DECISION
+
+- **Approve**: Acknowledge briefly. If the human wants to patch something before shipping, help apply the fix interactively. If reviewing a PR, offer to approve via `gh pr review --approve` — but confirm with the human before executing, since this is a visible action on a shared resource.
+- **Rework**: Ask what went wrong — was it the approach, the spec, or the implementation? Help the human decide on next steps (revert commit, open an issue, revise the spec, etc.). Help draft specific, actionable feedback tied to `path:line` locations if the change is a PR from someone else.
+- **Discuss**: Open conversation — answer questions, explore concerns, dig into any aspect. After discussion, return to the decision prompt above.
diff --git a/.claude/skills/bmad-code-review/SKILL.md b/.claude/skills/bmad-code-review/SKILL.md
new file mode 100644
index 0000000..32f020a
--- /dev/null
+++ b/.claude/skills/bmad-code-review/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-code-review
+description: 'Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-code-review/steps/step-01-gather-context.md b/.claude/skills/bmad-code-review/steps/step-01-gather-context.md
new file mode 100644
index 0000000..22b9fbd
--- /dev/null
+++ b/.claude/skills/bmad-code-review/steps/step-01-gather-context.md
@@ -0,0 +1,85 @@
+---
+diff_output: '' # set at runtime
+spec_file: '' # set at runtime (path or empty)
+review_mode: '' # set at runtime: "full" or "no-spec"
+story_key: '' # set at runtime when discovered from sprint status
+---
+
+# Step 1: Gather Context
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The prompt that triggered this workflow IS the intent — not a hint.
+- Do not modify any files. This step is read-only.
+
+## INSTRUCTIONS
+
+1. **Find the review target.** The conversation context before this skill was triggered IS your starting point — not a blank slate. Check in this order — stop as soon as the review target is identified:
+
+   **Tier 1 — Explicit argument.**
+   Did the user pass a PR, commit SHA, branch, spec file, or diff source this message?
+   - PR reference → resolve to branch/commit via `gh pr view`. If resolution fails, ask for a SHA or branch.
+   - Commit or branch → use directly.
+   - Spec file → set `{spec_file}` to the provided path. Check its frontmatter for `baseline_commit`. If found, use as diff baseline. If not found, continue the cascade (a spec alone does not identify a diff source).
+   - Also scan the argument for diff-mode keywords that narrow the scope:
+     - "staged" / "staged changes" → Staged changes only
+     - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged)
+     - "branch diff" / "vs main" / "against main" / "compared to <branch>" → Branch diff (extract base branch if mentioned)
+     - "commit range" / "last N commits" / "<from-sha>..<to-sha>" → Specific commit range
+     - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes)
+   - When multiple keywords match, prefer the most specific (e.g., "branch diff" over bare "diff").
+
+   **Tier 2 — Recent conversation.**
+   Do the last few messages reveal what the user wants to be reviewed? Look for spec paths, commit refs, branches, PRs, or descriptions of a change. Apply the same diff-mode keyword scan and routing as Tier 1.
+
+   **Tier 3 — Sprint tracking.**
+   Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`:
+   - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story <story-id> in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through.
+   - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If a story is selected, set `{story_key}` and use its context to determine the diff source. If manual choice is selected, clear `{story_key}` and fall through.
+   - **None:** Fall through.
+
+   **Tier 4 — Current git state.**
+   If version control is unavailable, skip to Tier 5. Otherwise, check the current branch and HEAD. If the branch is not `main` (or the default branch), confirm: "I see HEAD is `<short-sha>` on `<branch>` — do you want to review this branch's changes?" If confirmed, treat as a branch diff against `main`. If declined, fall through.
+
+   **Tier 5 — Ask.**
+   Fall through to instruction 2.
+
+   Never ask extra questions beyond what the cascade prescribes. If a tier above already identified the target, skip the remaining tiers and proceed to instruction 3 (construct diff).
+
+2. HALT. Ask the user: **What do you want to review?** Present these options:
+   - **Uncommitted changes** (staged + unstaged)
+   - **Staged changes only**
+   - **Branch diff** vs a base branch (ask which base branch)
+   - **Specific commit range** (ask for the range)
+   - **Provided diff or file list** (user pastes or provides a path)
+
+3. Construct `{diff_output}` from the chosen source.
+   - For **staged changes only**: run `git diff --cached`.
+   - For **uncommitted changes** (staged + unstaged): run `git diff HEAD`.
+   - For **branch diff**: verify the base branch exists before running `git diff`. If it does not exist, HALT and ask the user for a valid branch.
+   - For **commit range**: verify the range resolves. If it does not, HALT and ask the user for a valid range.
+   - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff.
+   - For **file list**: validate each path exists in the working tree. Construct `{diff_output}` by running `git diff HEAD -- <path1> <path2> ...`. If any paths are untracked (new files not yet staged), use `git diff --no-index /dev/null <path>` to include them. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
+   - After constructing `{diff_output}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review.
+
+4. **Set the spec context.**
+   - If `{spec_file}` is already set (from Tier 1 or Tier 2): verify the file exists and is readable, then set `{review_mode}` = `"full"`.
+   - Otherwise, ask the user: **Is there a spec or story file that provides context for these changes?**
+     - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`.
+     - If no: set `{review_mode}` = `"no-spec"`.
+
+5. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found.
+
+6. Sanity check: if `{diff_output}` exceeds approximately 3000 lines, warn the user and offer to chunk the review by file group.
+   - If the user opts to chunk: agree on the first group, narrow `{diff_output}` accordingly, and list the remaining groups for the user to note for follow-up runs.
+   - If the user declines: proceed as-is with the full diff.
+
+### CHECKPOINT
+
+Present a summary before proceeding: diff stats (files changed, lines added/removed), `{review_mode}`, and loaded spec/context docs (if any). HALT and wait for user confirmation to proceed.
+
+
+## NEXT
+
+Read fully and follow `./step-02-review.md`
diff --git a/.claude/skills/bmad-code-review/steps/step-02-review.md b/.claude/skills/bmad-code-review/steps/step-02-review.md
new file mode 100644
index 0000000..c262a49
--- /dev/null
+++ b/.claude/skills/bmad-code-review/steps/step-02-review.md
@@ -0,0 +1,34 @@
+---
+failed_layers: '' # set at runtime: comma-separated list of layers that failed or returned empty
+---
+
+# Step 2: Review
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The Blind Hunter subagent receives NO project context — diff only.
+- The Edge Case Hunter subagent receives diff and project read access.
+- The Acceptance Auditor subagent receives diff, spec, and context docs.
+
+## INSTRUCTIONS
+
+1. If `{review_mode}` = `"no-spec"`, note to the user: "Acceptance Auditor skipped — no spec file provided."
+
+2. Launch parallel subagents without conversation context. If subagents are not available, generate prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, resume from this point and proceed to step 3.
+
+   - **Blind Hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
+
+   - **Edge Case Hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
+
+   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — receives `{diff_output}`, the content of the file at `{spec_file}`, and any loaded context docs. Its prompt:
+     > You are an Acceptance Auditor. Review this diff against the spec and context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
+
+3. **Subagent failure handling**: If any subagent fails, times out, or returns empty results, append the layer name to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
+
+4. Collect all findings from the completed layers.
+
+
+## NEXT
+
+Read fully and follow `./step-03-triage.md`
diff --git a/.claude/skills/bmad-code-review/steps/step-03-triage.md b/.claude/skills/bmad-code-review/steps/step-03-triage.md
new file mode 100644
index 0000000..6bb2635
--- /dev/null
+++ b/.claude/skills/bmad-code-review/steps/step-03-triage.md
@@ -0,0 +1,49 @@
+---
+---
+
+# Step 3: Triage
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- Be precise. When uncertain between categories, prefer the more conservative classification.
+
+## INSTRUCTIONS
+
+1. **Normalize** findings into a common format. Expected input formats:
+   - Adversarial (Blind Hunter): markdown list of descriptions
+   - Edge Case Hunter: JSON array with `location`, `trigger_condition`, `guard_snippet`, `potential_consequence` fields
+   - Acceptance Auditor: markdown list with title, AC/constraint reference, and evidence
+
+   If a layer's output does not match its expected format, attempt best-effort parsing. Note any parsing issues for the user.
+
+   Convert all to a unified list where each finding has:
+   - `id` -- sequential integer
+   - `source` -- `blind`, `edge`, `auditor`, or merged sources (e.g., `blind+edge`)
+   - `title` -- one-line summary
+   - `detail` -- full description
+   - `location` -- file and line reference (if available)
+
+2. **Deduplicate.** If two or more findings describe the same issue, merge them into one:
+   - Use the most specific finding as the base (prefer edge-case JSON with location over adversarial prose).
+   - Append any unique detail, reasoning, or location references from the other finding(s) into the surviving `detail` field.
+   - Set `source` to the merged sources (e.g., `blind+edge`).
+
+3. **Classify** each finding into exactly one bucket:
+   - **decision_needed** -- There is an ambiguous choice that requires human input. The code cannot be correctly patched without knowing the user's intent. Only possible if `{review_mode}` = `"full"`.
+   - **patch** -- Code issue that is fixable without human input. The correct fix is unambiguous.
+   - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now.
+   - **dismiss** -- Noise, false positive, or handled elsewhere.
+
+   If `{review_mode}` = `"no-spec"` and a finding would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not).
+
+4. **Drop** all `dismiss` findings. Record the dismiss count for the summary.
+
+5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
+
+6. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
+
+
+## NEXT
+
+Read fully and follow `./step-04-present.md`
diff --git a/.claude/skills/bmad-code-review/steps/step-04-present.md b/.claude/skills/bmad-code-review/steps/step-04-present.md
new file mode 100644
index 0000000..c495d49
--- /dev/null
+++ b/.claude/skills/bmad-code-review/steps/step-04-present.md
@@ -0,0 +1,129 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step 4: Present and Act
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- When `{spec_file}` is set, always write findings to the story file before offering action choices.
+- `decision-needed` findings must be resolved before handling `patch` findings.
+
+## INSTRUCTIONS
+
+### 1. Clean review shortcut
+
+If zero findings remain after triage (all dismissed or none raised): state that and proceed to section 6 (Sprint Status Update).
+
+### 2. Write findings to the story file
+
+If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Review Findings` subsection. Write all findings in this order:
+
+1. **`decision-needed`** findings (unchecked):
+   `- [ ] [Review][Decision] <Title> — <Detail>`
+
+2. **`patch`** findings (unchecked):
+   `- [ ] [Review][Patch] <Title> [<file>:<line>]`
+
+3. **`defer`** findings (checked off, marked deferred):
+   `- [x] [Review][Defer] <Title> [<file>:<line>] — deferred, pre-existing`
+
+Also append each `defer` finding to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with description.
+
+### 3. Present summary
+
+Announce what was written:
+
+> **Code review complete.** <D> `decision-needed`, <P> `patch`, <W> `defer`, <R> dismissed as noise.
+
+If `{spec_file}` is set, add: `Findings written to the review findings section in {spec_file}.`
+Otherwise add: `Findings are listed above. No story file was provided, so nothing was persisted.`
+
+### 4. Resolve decision-needed findings
+
+If `decision_needed` findings exist, present each one with its detail and the options available. The user must decide — the correct fix is ambiguous without their input. Walk through each finding (or batch related ones) and get the user's call. Once resolved, each becomes a `patch`, `defer`, or is dismissed.
+
+If the user chooses to defer, ask: Quick one-line reason for deferring this item? (helps future reviews): — then append that reason to both the story file bullet and the `{deferred_work_file}` entry.
+
+**HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option.
+
+### 5. Handle `patch` findings
+
+If `patch` findings exist (including any resolved from step 4), HALT. Ask the user:
+
+If `{spec_file}` is set, present all three options (if >3 `patch` findings exist, also show option 0):
+
+> **How would you like to handle the <Z> `patch` findings?**
+> 0. **Batch-apply all** — automatically fix every non-controversial patch (recommended when there are many)
+> 1. **Fix them automatically** — I will apply fixes now
+> 2. **Leave as action items** — they are already in the story file
+> 3. **Walk through each** — let me show details before deciding
+
+If `{spec_file}` is **not** set, present only options 1 and 3 (omit option 2 — findings were not written to a file). If >3 `patch` findings exist, also show option 0:
+
+> **How would you like to handle the <Z> `patch` findings?**
+> 0. **Batch-apply all** — automatically fix every non-controversial patch (recommended when there are many)
+> 1. **Fix them automatically** — I will apply fixes now
+> 2. **Walk through each** — let me show details before deciding
+
+**HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option.
+
+- **Option 0** (only when >3 findings): Apply all non-controversial patches without per-finding confirmation. Skip any finding that requires judgment. Present a summary of changes made and any skipped findings.
+- **Option 1**: Apply each fix. After all patches are applied, present a summary of changes made. If `{spec_file}` is set, check off the items in the story file.
+- **Option 2** (only when `{spec_file}` is set): Done — findings are already written to the story.
+- **Walk through each**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer the applicable options above.
+
+  **HALT** — I am waiting for your numbered choice. Reply with only the number (or "0" for batch). Do not proceed until you select an option.
+
+**✅ Code review actions complete**
+
+- Decision-needed resolved: <D>
+- Patches handled: <P>
+- Deferred: <W>
+- Dismissed: <R>
+
+### 6. Update story status and sync sprint tracking
+
+Skip this section if `{spec_file}` is not set.
+
+#### Determine new status based on review outcome
+
+- If all `decision-needed` and `patch` findings were resolved (fixed or dismissed) AND no unresolved HIGH/MEDIUM issues remain: set `{new_status}` = `done`. Update the story file Status section to `done`.
+- If `patch` findings were left as action items, or unresolved issues remain: set `{new_status}` = `in-progress`. Update the story file Status section to `in-progress`.
+
+Save the story file.
+
+#### Sync sprint-status.yaml
+
+If `{story_key}` is not set, skip this subsection and note that sprint status was not synced because no story key was available.
+
+If `{sprint_status}` file exists:
+
+1. Load the FULL `{sprint_status}` file.
+2. Find the `development_status` entry matching `{story_key}`.
+3. If found: update `development_status[{story_key}]` to `{new_status}`. Update `last_updated` to current date. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS.
+4. If `{story_key}` not found in sprint status: warn the user that the story file was updated but sprint-status sync failed.
+
+If `{sprint_status}` file does not exist, note that story status was updated in the story file only.
+
+#### Completion summary
+
+> **Review Complete!**
+>
+> **Story Status:** `{new_status}`
+> **Issues Fixed:** <fixed_count>
+> **Action Items Created:** <action_count>
+> **Deferred:** <W>
+> **Dismissed:** <R>
+
+### 7. Next steps
+
+Present the user with follow-up options:
+
+> **What would you like to do next?**
+> 1. **Start the next story** — run `dev-story` to pick up the next `ready-for-dev` story
+> 2. **Re-run code review** — address findings and review again
+> 3. **Done** — end the workflow
+
+**HALT** — I am waiting for your choice. Do not proceed until the user selects an option.
diff --git a/.claude/skills/bmad-code-review/workflow.md b/.claude/skills/bmad-code-review/workflow.md
new file mode 100644
index 0000000..2cad2d8
--- /dev/null
+++ b/.claude/skills/bmad-code-review/workflow.md
@@ -0,0 +1,55 @@
+---
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+---
+
+# Code Review Workflow
+
+**Goal:** Review code changes adversarially using parallel review layers and structured triage.
+
+**Your Role:** You are an elite code reviewer. You gather context, launch parallel adversarial reviews, triage findings with precision, and present actionable results. No noise, no filler.
+
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+- **Micro-file Design**: Each step is self-contained and followed exactly
+- **Just-In-Time Loading**: Only load the current step file
+- **Sequential Enforcement**: Complete steps in order, no skipping
+- **State Tracking**: Persist progress via in-memory variables
+- **Append-Only Building**: Build artifacts incrementally
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Read the entire step file before acting
+2. **FOLLOW SEQUENCE**: Execute sections in order
+3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
+4. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- **NEVER** load multiple step files simultaneously
+- **ALWAYS** read entire step file before execution
+- **NEVER** skip steps or optimize the sequence
+- **ALWAYS** follow the exact instructions in the step file
+- **ALWAYS** halt at checkpoints and wait for human input
+
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{main_config}` and resolve:
+
+- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `project_context` = `**/project-context.md` (load if exists)
+- CLAUDE.md / memory files (load if exist)
+
+YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`.
+
+### 2. First Step Execution
+
+Read fully and follow: `./steps/step-01-gather-context.md` to begin the workflow.
diff --git a/.claude/skills/bmad-correct-course/SKILL.md b/.claude/skills/bmad-correct-course/SKILL.md
new file mode 100644
index 0000000..021c715
--- /dev/null
+++ b/.claude/skills/bmad-correct-course/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-correct-course
+description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-correct-course/checklist.md b/.claude/skills/bmad-correct-course/checklist.md
new file mode 100644
index 0000000..b56feb6
--- /dev/null
+++ b/.claude/skills/bmad-correct-course/checklist.md
@@ -0,0 +1,288 @@
+# Change Navigation Checklist
+
+<critical>This checklist is executed as part of: ./workflow.md</critical>
+<critical>Work through each section systematically with the user, recording findings and impacts</critical>
+
+<checklist>
+
+<section n="1" title="Understand the Trigger and Context">
+
+<check-item id="1.1">
+<prompt>Identify the triggering story that revealed this issue</prompt>
+<action>Document story ID and brief description</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="1.2">
+<prompt>Define the core problem precisely</prompt>
+<action>Categorize issue type:</action>
+  - Technical limitation discovered during implementation
+  - New requirement emerged from stakeholders
+  - Misunderstanding of original requirements
+  - Strategic pivot or market change
+  - Failed approach requiring different solution
+<action>Write clear problem statement</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="1.3">
+<prompt>Assess initial impact and gather supporting evidence</prompt>
+<action>Collect concrete examples, error messages, stakeholder feedback, or technical constraints</action>
+<action>Document evidence for later reference</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<halt-condition>
+<action if="trigger is unclear">HALT: "Cannot proceed without understanding what caused the need for change"</action>
+<action if="no evidence provided">HALT: "Need concrete evidence or examples of the issue before analyzing impact"</action>
+</halt-condition>
+
+</section>
+
+<section n="2" title="Epic Impact Assessment">
+
+<check-item id="2.1">
+<prompt>Evaluate current epic containing the trigger story</prompt>
+<action>Can this epic still be completed as originally planned?</action>
+<action>If no, what modifications are needed?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.2">
+<prompt>Determine required epic-level changes</prompt>
+<action>Check each scenario:</action>
+  - Modify existing epic scope or acceptance criteria
+  - Add new epic to address the issue
+  - Remove or defer epic that's no longer viable
+  - Completely redefine epic based on new understanding
+<action>Document specific epic changes needed</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.3">
+<prompt>Review all remaining planned epics for required changes</prompt>
+<action>Check each future epic for impact</action>
+<action>Identify dependencies that may be affected</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.4">
+<prompt>Check if issue invalidates future epics or necessitates new ones</prompt>
+<action>Does this change make any planned epics obsolete?</action>
+<action>Are new epics needed to address gaps created by this change?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="2.5">
+<prompt>Consider if epic order or priority should change</prompt>
+<action>Should epics be resequenced based on this issue?</action>
+<action>Do priorities need adjustment?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="3" title="Artifact Conflict and Impact Analysis">
+
+<check-item id="3.1">
+<prompt>Check PRD for conflicts</prompt>
+<action>Does issue conflict with core PRD goals or objectives?</action>
+<action>Do requirements need modification, addition, or removal?</action>
+<action>Is the defined MVP still achievable or does scope need adjustment?</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="3.2">
+<prompt>Review Architecture document for conflicts</prompt>
+<action>Check each area for impact:</action>
+  - System components and their interactions
+  - Architectural patterns and design decisions
+  - Technology stack choices
+  - Data models and schemas
+  - API designs and contracts
+  - Integration points
+<action>Document specific architecture sections requiring updates</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="3.3">
+<prompt>Examine UI/UX specifications for conflicts</prompt>
+<action>Check for impact on:</action>
+  - User interface components
+  - User flows and journeys
+  - Wireframes or mockups
+  - Interaction patterns
+  - Accessibility considerations
+<action>Note specific UI/UX sections needing revision</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="3.4">
+<prompt>Consider impact on other artifacts</prompt>
+<action>Review additional artifacts for impact:</action>
+  - Deployment scripts
+  - Infrastructure as Code (IaC)
+  - Monitoring and observability setup
+  - Testing strategies
+  - Documentation
+  - CI/CD pipelines
+<action>Document any secondary artifacts requiring updates</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="4" title="Path Forward Evaluation">
+
+<check-item id="4.1">
+<prompt>Evaluate Option 1: Direct Adjustment</prompt>
+<action>Can the issue be addressed by modifying existing stories?</action>
+<action>Can new stories be added within the current epic structure?</action>
+<action>Would this approach maintain project timeline and scope?</action>
+<action>Effort estimate: [High/Medium/Low]</action>
+<action>Risk level: [High/Medium/Low]</action>
+<status>[ ] Viable / [ ] Not viable</status>
+</check-item>
+
+<check-item id="4.2">
+<prompt>Evaluate Option 2: Potential Rollback</prompt>
+<action>Would reverting recently completed stories simplify addressing this issue?</action>
+<action>Which stories would need to be rolled back?</action>
+<action>Is the rollback effort justified by the simplification gained?</action>
+<action>Effort estimate: [High/Medium/Low]</action>
+<action>Risk level: [High/Medium/Low]</action>
+<status>[ ] Viable / [ ] Not viable</status>
+</check-item>
+
+<check-item id="4.3">
+<prompt>Evaluate Option 3: PRD MVP Review</prompt>
+<action>Is the original PRD MVP still achievable with this issue?</action>
+<action>Does MVP scope need to be reduced or redefined?</action>
+<action>Do core goals need modification based on new constraints?</action>
+<action>What would be deferred to post-MVP if scope is reduced?</action>
+<action>Effort estimate: [High/Medium/Low]</action>
+<action>Risk level: [High/Medium/Low]</action>
+<status>[ ] Viable / [ ] Not viable</status>
+</check-item>
+
+<check-item id="4.4">
+<prompt>Select recommended path forward</prompt>
+<action>Based on analysis of all options, choose the best path</action>
+<action>Provide clear rationale considering:</action>
+  - Implementation effort and timeline impact
+  - Technical risk and complexity
+  - Impact on team morale and momentum
+  - Long-term sustainability and maintainability
+  - Stakeholder expectations and business value
+<action>Selected approach: [Option 1 / Option 2 / Option 3 / Hybrid]</action>
+<action>Justification: [Document reasoning]</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="5" title="Sprint Change Proposal Components">
+
+<check-item id="5.1">
+<prompt>Create identified issue summary</prompt>
+<action>Write clear, concise problem statement</action>
+<action>Include context about discovery and impact</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.2">
+<prompt>Document epic impact and artifact adjustment needs</prompt>
+<action>Summarize findings from Epic Impact Assessment (Section 2)</action>
+<action>Summarize findings from Artifact Conflict Analysis (Section 3)</action>
+<action>Be specific about what changes are needed and why</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.3">
+<prompt>Present recommended path forward with rationale</prompt>
+<action>Include selected approach from Section 4</action>
+<action>Provide complete justification for recommendation</action>
+<action>Address trade-offs and alternatives considered</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.4">
+<prompt>Define PRD MVP impact and high-level action plan</prompt>
+<action>State clearly if MVP is affected</action>
+<action>Outline major action items needed for implementation</action>
+<action>Identify dependencies and sequencing</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="5.5">
+<prompt>Establish agent handoff plan</prompt>
+<action>Identify which roles/agents will execute the changes:</action>
+  - Developer agent (for implementation)
+  - Product Owner / Developer (for backlog changes)
+  - Product Manager / Architect (for strategic changes)
+<action>Define responsibilities for each role</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+</section>
+
+<section n="6" title="Final Review and Handoff">
+
+<check-item id="6.1">
+<prompt>Review checklist completion</prompt>
+<action>Verify all applicable sections have been addressed</action>
+<action>Confirm all [Action-needed] items have been documented</action>
+<action>Ensure analysis is comprehensive and actionable</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.2">
+<prompt>Verify Sprint Change Proposal accuracy</prompt>
+<action>Review complete proposal for consistency and clarity</action>
+<action>Ensure all recommendations are well-supported by analysis</action>
+<action>Check that proposal is actionable and specific</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.3">
+<prompt>Obtain explicit user approval</prompt>
+<action>Present complete proposal to user</action>
+<action>Get clear yes/no approval for proceeding</action>
+<action>Document approval and any conditions</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.4">
+<prompt>Update sprint-status.yaml to reflect approved epic changes</prompt>
+<action>If epics were added: Add new epic entries with status 'backlog'</action>
+<action>If epics were removed: Remove corresponding entries</action>
+<action>If epics were renumbered: Update epic IDs and story references</action>
+<action>If stories were added/removed: Update story entries within affected epics</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<check-item id="6.5">
+<prompt>Confirm next steps and handoff plan</prompt>
+<action>Review handoff responsibilities with user</action>
+<action>Ensure all stakeholders understand their roles</action>
+<action>Confirm timeline and success criteria</action>
+<status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
+</check-item>
+
+<halt-condition>
+<action if="any critical section cannot be completed">HALT: "Cannot proceed to proposal without complete impact analysis"</action>
+<action if="user approval not obtained">HALT: "Must have explicit approval before implementing changes"</action>
+<action if="handoff responsibilities unclear">HALT: "Must clearly define who will execute the proposed changes"</action>
+</halt-condition>
+
+</section>
+
+</checklist>
+
+<execution-notes>
+<note>This checklist is for SIGNIFICANT changes affecting project direction</note>
+<note>Work interactively with user - they make final decisions</note>
+<note>Be factual, not blame-oriented when analyzing issues</note>
+<note>Handle changes professionally as opportunities to improve the project</note>
+<note>Maintain conversation context throughout - this is collaborative work</note>
+</execution-notes>
diff --git a/.claude/skills/bmad-correct-course/workflow.md b/.claude/skills/bmad-correct-course/workflow.md
new file mode 100644
index 0000000..2b7cd71
--- /dev/null
+++ b/.claude/skills/bmad-correct-course/workflow.md
@@ -0,0 +1,267 @@
+# Correct Course - Sprint Change Management Workflow
+
+**Goal:** Manage significant changes during sprint execution by analyzing impact across all project artifacts and producing a structured Sprint Change Proposal.
+
+**Your Role:** You are a Developer navigating change management. Analyze the triggering issue, assess impact across PRD, epics, architecture, and UX artifacts, and produce an actionable Sprint Change Proposal with clear handoff.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `implementation_artifacts`
+- `planning_artifacts`
+- `project_knowledge`
+- `date` as system-generated current datetime
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- Language MUST be tailored to `{user_skill_level}`
+- Generate all documents in `{document_output_language}`
+- DOCUMENT OUTPUT: Updated epics, stories, or PRD sections. Clear, actionable changes. User skill level (`{user_skill_level}`) affects conversation style ONLY, not document updates.
+
+### Paths
+
+- `default_output_file` = `{planning_artifacts}/sprint-change-proposal-{date}.md`
+
+### Input Files
+
+| Input | Path | Load Strategy |
+|-------|------|---------------|
+| PRD | `{planning_artifacts}/*prd*.md` (whole) or `{planning_artifacts}/*prd*/*.md` (sharded) | FULL_LOAD |
+| Epics | `{planning_artifacts}/*epic*.md` (whole) or `{planning_artifacts}/*epic*/*.md` (sharded) | FULL_LOAD |
+| Architecture | `{planning_artifacts}/*architecture*.md` (whole) or `{planning_artifacts}/*architecture*/*.md` (sharded) | FULL_LOAD |
+| UX Design | `{planning_artifacts}/*ux*.md` (whole) or `{planning_artifacts}/*ux*/*.md` (sharded) | FULL_LOAD |
+| Spec | `{planning_artifacts}/*spec-*.md` (whole) | FULL_LOAD |
+| Document Project | `{project_knowledge}/index.md` (sharded) | INDEX_GUIDED |
+
+### Context
+
+- Load `**/project-context.md` if it exists
+
+---
+
+## EXECUTION
+
+### Document Discovery - Loading Project Artifacts
+
+**Strategy**: Course correction needs broad project context to assess change impact accurately. Load all available planning artifacts.
+
+**Discovery Process for FULL_LOAD documents (PRD, Epics, Architecture, UX Design, Spec):**
+
+1. **Search for whole document first** - Look for files matching the whole-document pattern (e.g., `*prd*.md`, `*epic*.md`, `*architecture*.md`, `*ux*.md`, `*spec-*.md`)
+2. **Check for sharded version** - If whole document not found, look for a directory with `index.md` (e.g., `prd/index.md`, `epics/index.md`)
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index
+   - Process the combined content as a single document
+4. **Priority**: If both whole and sharded versions exist, use the whole document
+
+**Discovery Process for INDEX_GUIDED documents (Document Project):**
+
+1. **Search for index file** - Look for `{project_knowledge}/index.md`
+2. **If found**: Read the index to understand available documentation sections
+3. **Selectively load sections** based on relevance to the change being analyzed — do NOT load everything, only sections that relate to the impacted areas
+4. **This document is optional** — skip if `{project_knowledge}` does not exist (greenfield projects)
+
+**Fuzzy matching**: Be flexible with document names — users may use variations like `prd.md`, `bmm-prd.md`, `product-requirements.md`, etc.
+
+**Missing documents**: Not all documents may exist. PRD and Epics are essential; Architecture, UX Design, Spec, and Document Project are loaded if available. HALT if PRD or Epics cannot be found.
+
+<workflow>
+
+<step n="1" goal="Initialize Change Navigation">
+  <action>Load **/project-context.md for coding standards and project-wide patterns (if exists)</action>
+  <action>Confirm change trigger and gather user description of the issue</action>
+  <action>Ask: "What specific issue or change has been identified that requires navigation?"</action>
+  <action>Verify access to required project documents:</action>
+    - PRD (Product Requirements Document)
+    - Current Epics and Stories
+    - Architecture documentation
+    - UI/UX specifications
+  <action>Ask user for mode preference:</action>
+    - **Incremental** (recommended): Refine each edit collaboratively
+    - **Batch**: Present all changes at once for review
+  <action>Store mode selection for use throughout workflow</action>
+
+<action if="change trigger is unclear">HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why."</action>
+
+<action if="core documents are unavailable">HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible."</action>
+</step>
+
+<step n="2" goal="Execute Change Analysis Checklist">
+  <action>Read fully and follow the systematic analysis from: checklist.md</action>
+  <action>Work through each checklist section interactively with the user</action>
+  <action>Record status for each checklist item:</action>
+    - [x] Done - Item completed successfully
+    - [N/A] Skip - Item not applicable to this change
+    - [!] Action-needed - Item requires attention or follow-up
+  <action>Maintain running notes of findings and impacts discovered</action>
+  <action>Present checklist progress after each major section</action>
+
+<action if="checklist cannot be completed">Identify blocking issues and work with user to resolve before continuing</action>
+</step>
+
+<step n="3" goal="Draft Specific Change Proposals">
+<action>Based on checklist findings, create explicit edit proposals for each identified artifact</action>
+
+<action>For Story changes:</action>
+
+- Show old → new text format
+- Include story ID and section being modified
+- Provide rationale for each change
+- Example format:
+
+  ```
+  Story: [STORY-123] User Authentication
+  Section: Acceptance Criteria
+
+  OLD:
+  - User can log in with email/password
+
+  NEW:
+  - User can log in with email/password
+  - User can enable 2FA via authenticator app
+
+  Rationale: Security requirement identified during implementation
+  ```
+
+<action>For PRD modifications:</action>
+
+- Specify exact sections to update
+- Show current content and proposed changes
+- Explain impact on MVP scope and requirements
+
+<action>For Architecture changes:</action>
+
+- Identify affected components, patterns, or technology choices
+- Describe diagram updates needed
+- Note any ripple effects on other components
+
+<action>For UI/UX specification updates:</action>
+
+- Reference specific screens or components
+- Show wireframe or flow changes needed
+- Connect changes to user experience impact
+
+<check if="mode is Incremental">
+  <action>Present each edit proposal individually</action>
+  <ask>Review and refine this change? Options: Approve [a], Edit [e], Skip [s]</ask>
+  <action>Iterate on each proposal based on user feedback</action>
+</check>
+
+<action if="mode is Batch">Collect all edit proposals and present together at end of step</action>
+
+</step>
+
+<step n="4" goal="Generate Sprint Change Proposal">
+<action>Compile comprehensive Sprint Change Proposal document with following sections:</action>
+
+<action>Section 1: Issue Summary</action>
+
+- Clear problem statement describing what triggered the change
+- Context about when/how the issue was discovered
+- Evidence or examples demonstrating the issue
+
+<action>Section 2: Impact Analysis</action>
+
+- Epic Impact: Which epics are affected and how
+- Story Impact: Current and future stories requiring changes
+- Artifact Conflicts: PRD, Architecture, UI/UX documents needing updates
+- Technical Impact: Code, infrastructure, or deployment implications
+
+<action>Section 3: Recommended Approach</action>
+
+- Present chosen path forward from checklist evaluation:
+  - Direct Adjustment: Modify/add stories within existing plan
+  - Potential Rollback: Revert completed work to simplify resolution
+  - MVP Review: Reduce scope or modify goals
+- Provide clear rationale for recommendation
+- Include effort estimate, risk assessment, and timeline impact
+
+<action>Section 4: Detailed Change Proposals</action>
+
+- Include all refined edit proposals from Step 3
+- Group by artifact type (Stories, PRD, Architecture, UI/UX)
+- Ensure each change includes before/after and justification
+
+<action>Section 5: Implementation Handoff</action>
+
+- Categorize change scope:
+  - Minor: Direct implementation by Developer agent
+  - Moderate: Backlog reorganization needed (PO/DEV)
+  - Major: Fundamental replan required (PM/Architect)
+- Specify handoff recipients and their responsibilities
+- Define success criteria for implementation
+
+<action>Present complete Sprint Change Proposal to user</action>
+<action>Write Sprint Change Proposal document to {default_output_file}</action>
+<ask>Review complete proposal. Continue [c] or Edit [e]?</ask>
+</step>
+
+<step n="5" goal="Finalize and Route for Implementation">
+<action>Get explicit user approval for complete proposal</action>
+<ask>Do you approve this Sprint Change Proposal for implementation? (yes/no/revise)</ask>
+
+<check if="no or revise">
+  <action>Gather specific feedback on what needs adjustment</action>
+  <action>Return to appropriate step to address concerns</action>
+  <goto step="3">If changes needed to edit proposals</goto>
+  <goto step="4">If changes needed to overall proposal structure</goto>
+
+</check>
+
+<check if="yes the proposal is approved by the user">
+  <action>Finalize Sprint Change Proposal document</action>
+  <action>Determine change scope classification:</action>
+
+- **Minor**: Can be implemented directly by Developer agent
+- **Moderate**: Requires backlog reorganization and PO/DEV coordination
+- **Major**: Needs fundamental replan with PM/Architect involvement
+
+<action>Provide appropriate handoff based on scope:</action>
+
+</check>
+
+<check if="Minor scope">
+  <action>Route to: Developer agent for direct implementation</action>
+  <action>Deliverables: Finalized edit proposals and implementation tasks</action>
+</check>
+
+<check if="Moderate scope">
+  <action>Route to: Product Owner / Developer agents</action>
+  <action>Deliverables: Sprint Change Proposal + backlog reorganization plan</action>
+</check>
+
+<check if="Major scope">
+  <action>Route to: Product Manager / Solution Architect</action>
+  <action>Deliverables: Complete Sprint Change Proposal + escalation notice</action>
+
+<action>Confirm handoff completion and next steps with user</action>
+<action>Document handoff in workflow execution log</action>
+</check>
+
+</step>
+
+<step n="6" goal="Workflow Completion">
+<action>Summarize workflow execution:</action>
+  - Issue addressed: {{change_trigger}}
+  - Change scope: {{scope_classification}}
+  - Artifacts modified: {{list_of_artifacts}}
+  - Routed to: {{handoff_recipients}}
+
+<action>Confirm all deliverables produced:</action>
+
+- Sprint Change Proposal document
+- Specific edit proposals with before/after
+- Implementation handoff plan
+
+<action>Report workflow completion to user with personalized message: "Correct Course workflow complete, {user_name}!"</action>
+<action>Remind user of success criteria and next steps for Developer agent</action>
+</step>
+
+</workflow>
diff --git a/.claude/skills/bmad-create-architecture/SKILL.md b/.claude/skills/bmad-create-architecture/SKILL.md
new file mode 100644
index 0000000..27d4c7e
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-create-architecture
+description: 'Create architecture solution design decisions for AI agent consistency. Use when the user says "lets create architecture" or "create technical architecture" or "create a solution design"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-create-architecture/architecture-decision-template.md b/.claude/skills/bmad-create-architecture/architecture-decision-template.md
new file mode 100644
index 0000000..51ac3d6
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/architecture-decision-template.md
@@ -0,0 +1,12 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'architecture'
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+---
+
+# Architecture Decision Document
+
+_This document builds collaboratively through step-by-step discovery. Sections are appended as we work through each architectural decision together._
diff --git a/.claude/skills/bmad-create-architecture/data/domain-complexity.csv b/.claude/skills/bmad-create-architecture/data/domain-complexity.csv
new file mode 100644
index 0000000..d619659
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/data/domain-complexity.csv
@@ -0,0 +1,13 @@
+domain,signals,complexity_level,suggested_workflow,web_searches
+e_commerce,"shopping,cart,checkout,payment,products,store",medium,standard,"ecommerce architecture patterns, payment processing, inventory management"
+fintech,"banking,payment,trading,finance,money,investment",high,enhanced,"financial security, PCI compliance, trading algorithms, fraud detection"
+healthcare,"medical,diagnostic,clinical,patient,hospital,health",high,enhanced,"HIPAA compliance, medical data security, FDA regulations, health tech"
+social,"social network,community,users,friends,posts,sharing",high,advanced,"social graph algorithms, feed ranking, notification systems, privacy"
+education,"learning,course,student,teacher,training,academic",medium,standard,"LMS architecture, progress tracking, assessment systems, video streaming"
+productivity,"productivity,workflow,tasks,management,business,tools",medium,standard,"collaboration patterns, real-time editing, notification systems, integration"
+media,"content,media,video,audio,streaming,broadcast",high,advanced,"CDN architecture, video encoding, streaming protocols, content delivery"
+iot,"IoT,sensors,devices,embedded,smart,connected",high,advanced,"device communication, real-time data processing, edge computing, security"
+government,"government,civic,public,admin,policy,regulation",high,enhanced,"accessibility standards, security clearance, data privacy, audit trails"
+process_control,"industrial automation,process control,PLC,SCADA,DCS,HMI,operational technology,control system,cyberphysical,MES,instrumentation,I&C,P&ID",high,advanced,"industrial process control architecture, SCADA system design, OT cybersecurity architecture, real-time control systems"
+building_automation,"building automation,BAS,BMS,HVAC,smart building,fire alarm,fire protection,fire suppression,life safety,elevator,DDC,access control,sequence of operations,commissioning",high,advanced,"building automation architecture, BACnet integration patterns, smart building design, building management system security"
+gaming,"game,gaming,multiplayer,real-time,interactive,entertainment",high,advanced,"real-time multiplayer, game engine architecture, matchmaking, leaderboards"
\ No newline at end of file
diff --git a/.claude/skills/bmad-create-architecture/data/project-types.csv b/.claude/skills/bmad-create-architecture/data/project-types.csv
new file mode 100644
index 0000000..3733748
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/data/project-types.csv
@@ -0,0 +1,7 @@
+project_type,detection_signals,description,typical_starters
+web_app,"website,web application,browser,frontend,UI,interface",Web-based applications running in browsers,Next.js, Vite, Remix
+mobile_app,"mobile,iOS,Android,app,smartphone,tablet",Native mobile applications,React Native, Expo, Flutter
+api_backend,"API,REST,GraphQL,backend,service,microservice",Backend services and APIs,NestJS, Express, Fastify
+full_stack,"full-stack,complete,web+mobile,frontend+backend",Applications with both frontend and backend,T3 App, RedwoodJS, Blitz
+cli_tool,"CLI,command line,terminal,console,tool",Command-line interface tools,oclif, Commander, Caporal
+desktop_app,"desktop,Electron,Tauri,native app,macOS,Windows",Desktop applications,Electron, Tauri, Flutter Desktop
\ No newline at end of file
diff --git a/.claude/skills/bmad-create-architecture/steps/step-01-init.md b/.claude/skills/bmad-create-architecture/steps/step-01-init.md
new file mode 100644
index 0000000..c2933df
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/steps/step-01-init.md
@@ -0,0 +1,153 @@
+# Step 1: Architecture Workflow Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on initialization and setup only - don't look ahead to future steps
+- 🚪 DETECT existing workflow state and handle continuation properly
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Input document discovery happens in this step
+
+## YOUR TASK:
+
+Initialize the Architecture workflow by detecting continuation state, discovering input documents, and setting up the document for collaborative architectural decision making.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for existing {planning_artifacts}/`*architecture*.md`
+- If exists, read the complete file(s) including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+Discover and load context documents using smart discovery. Documents can be in the following locations:
+- {planning_artifacts}/**
+- {output_folder}/**
+- {project_knowledge}/**
+- {project-root}/docs/**
+
+Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content)
+
+Try to discover the following:
+- Product Brief (`*brief*.md`)
+- Product Requirements Document (`*prd*.md`)
+- UX Design (`*ux-design*.md`) and other
+- Research Documents (`*research*.md`)
+- Project Documentation (generally multiple documents might be found for this in the `{project_knowledge}` or `{project-root}/docs` folder.)
+- Project Context (`**/project-context.md`)
+
+<critical>Confirm what you have found with the user, along with asking if the user wants to provide anything else. Only after this confirmation will you proceed to follow the loading rules</critical>
+
+**Loading Rules:**
+
+- Load ALL discovered files completely that the user confirmed or provided (no offset/limit)
+- If there is a project context, whatever is relevant should try to be biased in the remainder of this whole workflow process
+- For sharded folders, load ALL files to get complete picture, using the index first to potentially know the potential of each document
+- index.md is a guide to what's relevant whenever available
+- Track all successfully loaded files in frontmatter `inputDocuments` array
+
+#### B. Validate Required Inputs
+
+Before proceeding, verify we have the essential inputs:
+
+**PRD Validation:**
+
+- If no PRD found: "Architecture requires a PRD to work from. Please run the PRD workflow first or provide the PRD file path."
+- Do NOT proceed without PRD
+
+**Other Input that might exist:**
+
+- UX Spec: "Provides UI/UX architectural requirements"
+
+#### C. Create Initial Document
+
+Copy the template from `../architecture-decision-template.md` to `{planning_artifacts}/architecture.md`
+
+#### D. Complete Initialization and Report
+
+Complete setup and report to user:
+
+**Document Setup:**
+
+- Created: `{planning_artifacts}/architecture.md` from template
+- Initialized frontmatter with workflow state
+
+**Input Documents Discovered:**
+Report what was found:
+"Welcome {{user_name}}! I've set up your Architecture workspace for {{project_name}}.
+
+**Documents Found:**
+
+- PRD: {number of PRD files loaded or "None found - REQUIRED"}
+- UX Design: {number of UX files loaded or "None found"}
+- Research: {number of research files loaded or "None found"}
+- Project docs: {number of project files loaded or "None found"}
+- Project context: {project_context_rules count of rules for AI agents found}
+
+**Files loaded:** {list of specific file names or "No additional documents found"}
+
+Ready to begin architectural decision making. Do you have any other documents you'd like me to include?
+
+[C] Continue to project context analysis
+
+## SUCCESS METRICS:
+
+✅ Existing workflow detected and handed off to step-01b correctly
+✅ Fresh workflow initialized with template and frontmatter
+✅ Input documents discovered and loaded using sharded-first logic
+✅ All discovered files tracked in frontmatter `inputDocuments`
+✅ PRD requirement validated and communicated
+✅ User confirmed document setup and can proceed
+
+## FAILURE MODES:
+
+❌ Proceeding with fresh initialization when existing workflow exists
+❌ Not updating frontmatter with discovered input documents
+❌ Creating document without proper template
+❌ Not checking sharded folders first before whole files
+❌ Not reporting what documents were found to user
+❌ Proceeding without validating PRD requirement
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects [C] to continue, only after ensuring all the template output has been created, then load `./step-02-context.md` to analyze the project context and begin architectural decision making.
+
+Remember: Do NOT proceed to step-02 until user explicitly selects [C] from the menu and setup is confirmed!
diff --git a/.claude/skills/bmad-create-architecture/steps/step-01b-continue.md b/.claude/skills/bmad-create-architecture/steps/step-01b-continue.md
new file mode 100644
index 0000000..977896a
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/steps/step-01b-continue.md
@@ -0,0 +1,173 @@
+# Step 1b: Workflow Continuation Handler
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on understanding current state and getting user confirmation
+- 🚪 HANDLE workflow resumption smoothly and transparently
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 📖 Read existing document completely to understand current state
+- 💾 Update frontmatter to reflect continuation
+- 🚫 FORBIDDEN to proceed to next step without user confirmation
+
+## CONTEXT BOUNDARIES:
+
+- Existing document and frontmatter are available
+- Input documents already loaded should be in frontmatter `inputDocuments`
+- Steps already completed are in `stepsCompleted` array
+- Focus on understanding where we left off
+
+## YOUR TASK:
+
+Handle workflow continuation by analyzing existing work and guiding the user to resume at the appropriate step.
+
+## CONTINUATION SEQUENCE:
+
+### 1. Analyze Current Document State
+
+Read the existing architecture document completely and analyze:
+
+**Frontmatter Analysis:**
+
+- `stepsCompleted`: What steps have been done
+- `inputDocuments`: What documents were loaded
+- `lastStep`: Last step that was executed
+- `project_name`, `user_name`, `date`: Basic context
+
+**Content Analysis:**
+
+- What sections exist in the document
+- What architectural decisions have been made
+- What appears incomplete or in progress
+- Any TODOs or placeholders remaining
+
+### 2. Present Continuation Summary
+
+Show the user their current progress:
+
+"Welcome back {{user_name}}! I found your Architecture work for {{project_name}}.
+
+**Current Progress:**
+
+- Steps completed: {{stepsCompleted list}}
+- Last step worked on: Step {{lastStep}}
+- Input documents loaded: {{number of inputDocuments}} files
+
+**Document Sections Found:**
+{list all H2/H3 sections found in the document}
+
+{if_incomplete_sections}
+**Incomplete Areas:**
+
+- {areas that appear incomplete or have placeholders}
+  {/if_incomplete_sections}
+
+**What would you like to do?**
+[R] Resume from where we left off
+[C] Continue to next logical step
+[O] Overview of all remaining steps
+[X] Start over (will overwrite existing work)
+"
+
+### 3. Handle User Choice
+
+#### If 'R' (Resume from where we left off):
+
+- Identify the next step based on `stepsCompleted`
+- Load the appropriate step file to continue
+- Example: If `stepsCompleted: [1, 2, 3]`, load `./step-04-decisions.md`
+
+#### If 'C' (Continue to next logical step):
+
+- Analyze the document content to determine logical next step
+- May need to review content quality and completeness
+- If content seems complete for current step, advance to next
+- If content seems incomplete, suggest staying on current step
+
+#### If 'O' (Overview of all remaining steps):
+
+- Provide brief description of all remaining steps
+- Let user choose which step to work on
+- Don't assume sequential progression is always best
+
+#### If 'X' (Start over):
+
+- Confirm: "This will delete all existing architectural decisions. Are you sure? (y/n)"
+- If confirmed: Delete existing document and read fully and follow: `./step-01-init.md`
+- If not confirmed: Return to continuation menu
+
+### 4. Navigate to Selected Step
+
+After user makes choice:
+
+**Load the selected step file:**
+
+- Update frontmatter `lastStep` to reflect current navigation
+- Execute the selected step file
+- Let that step handle the detailed continuation logic
+
+**State Preservation:**
+
+- Maintain all existing content in the document
+- Keep `stepsCompleted` accurate
+- Track the resumption in workflow status
+
+### 5. Special Continuation Cases
+
+#### If `stepsCompleted` is empty but document has content:
+
+- This suggests an interrupted workflow
+- Ask user: "I see the document has content but no steps are marked as complete. Should I analyze what's here and set the appropriate step status?"
+
+#### If document appears corrupted or incomplete:
+
+- Ask user: "The document seems incomplete. Would you like me to try to recover what's here, or would you prefer to start fresh?"
+
+#### If document is complete but workflow not marked as done:
+
+- Ask user: "The architecture looks complete! Should I mark this workflow as finished, or is there more you'd like to work on?"
+
+## SUCCESS METRICS:
+
+✅ Existing document state properly analyzed and understood
+✅ User presented with clear continuation options
+✅ User choice handled appropriately and transparently
+✅ Workflow state preserved and updated correctly
+✅ Navigation to appropriate step handled smoothly
+
+## FAILURE MODES:
+
+❌ Not reading the complete existing document before making suggestions
+❌ Losing track of what steps were actually completed
+❌ Automatically proceeding without user confirmation of next steps
+❌ Not checking for incomplete or placeholder content
+❌ Losing existing document content during resumption
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects their continuation option, load the appropriate step file based on their choice. The step file will handle the detailed work from that point forward.
+
+Valid step files to load:
+- `./step-02-context.md`
+- `./step-03-starter.md`
+- `./step-04-decisions.md`
+- `./step-05-patterns.md`
+- `./step-06-structure.md`
+- `./step-07-validation.md`
+- `./step-08-complete.md`
+
+Remember: The goal is smooth, transparent resumption that respects the work already done while giving the user control over how to proceed.
diff --git a/.claude/skills/bmad-create-architecture/steps/step-02-context.md b/.claude/skills/bmad-create-architecture/steps/step-02-context.md
new file mode 100644
index 0000000..96cb5c4
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/steps/step-02-context.md
@@ -0,0 +1,224 @@
+# Step 2: Project Context Analysis
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on understanding project scope and requirements for architecture
+- 🎯 ANALYZE loaded documents, don't assume or generate requirements
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating project context analysis
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper insights about project context and architectural implications
+- **P (Party Mode)**: Bring multiple perspectives to analyze project requirements from different architectural angles
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from step 1 are available
+- Input documents already loaded are in memory (PRD, epics, UX spec, etc.)
+- Focus on architectural implications of requirements
+- No technology decisions yet - pure analysis phase
+
+## YOUR TASK:
+
+Fully read and Analyze the loaded project documents to understand architectural scope, requirements, and constraints before beginning decision making.
+
+## CONTEXT ANALYSIS SEQUENCE:
+
+### 1. Review Project Requirements
+
+**From PRD Analysis:**
+
+- Extract and analyze Functional Requirements (FRs)
+- Identify Non-Functional Requirements (NFRs) like performance, security, compliance
+- Note any technical constraints or dependencies mentioned
+- Count and categorize requirements to understand project scale
+
+**From Epics/Stories (if available):**
+
+- Map epic structure and user stories to architectural components
+- Extract acceptance criteria for technical implications
+- Identify cross-cutting concerns that span multiple epics
+- Estimate story complexity for architectural planning
+
+**From UX Design (if available):**
+
+- Extract architectural implications from UX requirements:
+  - Component complexity (simple forms vs rich interactions)
+  - Animation/transition requirements
+  - Real-time update needs (live data, collaborative features)
+  - Platform-specific UI requirements
+  - Accessibility standards (WCAG compliance level)
+  - Responsive design breakpoints
+  - Offline capability requirements
+  - Performance expectations (load times, interaction responsiveness)
+
+### 2. Project Scale Assessment
+
+Calculate and present project complexity:
+
+**Complexity Indicators:**
+
+- Real-time features requirements
+- Multi-tenancy needs
+- Regulatory compliance requirements
+- Integration complexity
+- User interaction complexity
+- Data complexity and volume
+
+### 3. Reflect Understanding
+
+Present your analysis back to user for validation:
+
+"I'm reviewing your project documentation for {{project_name}}.
+
+{if_epics_loaded}I see {{epic_count}} epics with {{story_count}} total stories.{/if_epics_loaded}
+{if_no_epics}I found {{fr_count}} functional requirements organized into {{fr_category_list}}.{/if_no_epics}
+{if_ux_loaded}I also found your UX specification which defines the user experience requirements.{/if_ux_loaded}
+
+**Key architectural aspects I notice:**
+
+- [Summarize core functionality from FRs]
+- [Note critical NFRs that will shape architecture]
+- {if_ux_loaded}[Note UX complexity and technical requirements]{/if_ux_loaded}
+- [Identify unique technical challenges or constraints]
+- [Highlight any regulatory or compliance requirements]
+
+**Scale indicators:**
+
+- Project complexity appears to be: [low/medium/high/enterprise]
+- Primary technical domain: [web/mobile/api/backend/full-stack/etc]
+- Cross-cutting concerns identified: [list major ones]
+
+This analysis will help me guide you through the architectural decisions needed to ensure AI agents implement this consistently.
+
+Does this match your understanding of the project scope and requirements?"
+
+### 4. Generate Project Context Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+```markdown
+## Project Context Analysis
+
+### Requirements Overview
+
+**Functional Requirements:**
+{{analysis of FRs and what they mean architecturally}}
+
+**Non-Functional Requirements:**
+{{NFRs that will drive architectural decisions}}
+
+**Scale & Complexity:**
+{{project_scale_assessment}}
+
+- Primary domain: {{technical_domain}}
+- Complexity level: {{complexity_level}}
+- Estimated architectural components: {{component_count}}
+
+### Technical Constraints & Dependencies
+
+{{known_constraints_dependencies}}
+
+### Cross-Cutting Concerns Identified
+
+{{concerns_that_will_affect_multiple_components}}
+```
+
+### 5. Present Content and Menu
+
+Show the generated content and present choices:
+
+"I've drafted the Project Context Analysis based on your requirements. This sets the foundation for our architectural decisions.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 4]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's dive deeper into architectural implications
+[P] Party Mode - Bring different perspectives to analyze requirements
+[C] Continue - Save this analysis and begin architectural decisions"
+
+### 6. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current context analysis
+- Process the enhanced architectural insights that come back
+- Ask user: "Accept these enhancements to the project context analysis? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current project context
+- Process the collaborative improvements to architectural understanding
+- Ask user: "Accept these changes to the project context analysis? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/architecture.md`
+- Update frontmatter: `stepsCompleted: [1, 2]`
+- Load `./step-03-starter.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 4.
+
+## SUCCESS METRICS:
+
+✅ All input documents thoroughly analyzed for architectural implications
+✅ Project scope and complexity clearly assessed and validated
+✅ Technical constraints and dependencies identified
+✅ Cross-cutting concerns mapped for architectural planning
+✅ User confirmation of project understanding
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Skimming documents without deep architectural analysis
+❌ Missing or misinterpreting critical NFRs
+❌ Not validating project understanding with user
+❌ Underestimating complexity indicators
+❌ Generating content without real analysis of loaded documents
+❌ Not presenting A/P/C menu after content generation
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-03-starter.md` to evaluate starter template options.
+
+Remember: Do NOT proceed to step-03 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-architecture/steps/step-03-starter.md b/.claude/skills/bmad-create-architecture/steps/step-03-starter.md
new file mode 100644
index 0000000..339092a
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/steps/step-03-starter.md
@@ -0,0 +1,329 @@
+# Step 3: Starter Template Evaluation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on evaluating starter template options with current versions
+- 🌐 ALWAYS search the web to verify current versions - NEVER trust hardcoded versions
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete architecture
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 🌐 Search the web to verify current versions and options
+- ⚠️ Present A/P/C menu after generating starter template analysis
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to explore unconventional starter options or custom approaches
+- **P (Party Mode)**: Bring multiple perspectives to evaluate starter trade-offs for different use cases
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Project context from step 2 is available and complete
+- Project context file from step-01 may contain technical preferences
+- No architectural decisions made yet - evaluating foundations
+- Focus on technical preferences discovery and starter evaluation
+- Consider project requirements and existing preferences when evaluating options
+
+## YOUR TASK:
+
+Discover technical preferences and evaluate starter template options, leveraging existing technical preferences and establishing solid architectural foundations.
+
+## STARTER EVALUATION SEQUENCE:
+
+### 0. Check Technical Preferences & Context
+
+**Check Project Context for Existing Technical Preferences:**
+"Before we dive into starter templates, let me check if you have any technical preferences already documented.
+
+{{if_project_context_exists}}
+I found some technical rules in your project context file:
+{{extracted_technical_preferences_from_project_context}}
+
+**Project Context Technical Rules Found:**
+
+- Languages/Frameworks: {{languages_frameworks_from_context}}
+- Tools & Libraries: {{tools_from_context}}
+- Development Patterns: {{patterns_from_context}}
+- Platform Preferences: {{platforms_from_context}}
+
+{{else}}
+No existing technical preferences found in project context file. We'll establish your technical preferences now.
+{{/if_project_context}}"
+
+**Discover User Technical Preferences:**
+"Based on your project context, let's discuss your technical preferences:
+
+{{primary_technology_category}} Preferences:
+
+- **Languages**: Do you have preferences between TypeScript/JavaScript, Python, Go, Rust, etc.?
+- **Frameworks**: Any existing familiarity or preferences (React, Vue, Angular, Next.js, etc.)?
+- **Databases**: Any preferences or existing infrastructure (PostgreSQL, MongoDB, MySQL, etc.)?
+
+**Development Experience:**
+
+- What's your team's experience level with different technologies?
+- Are there any technologies you want to learn vs. what you're comfortable with?
+
+**Platform/Deployment Preferences:**
+
+- Cloud provider preferences (AWS, Vercel, Railway, etc.)?
+- Container preferences (Docker, Serverless, Traditional)?
+
+**Integrations:**
+
+- Any existing systems or APIs you need to integrate with?
+- Third-party services you plan to use (payment, authentication, analytics, etc.)?
+
+These preferences will help me recommend the most suitable starter templates and guide our architectural decisions."
+
+### 1. Identify Primary Technology Domain
+
+Based on project context analysis and technical preferences, identify the primary technology stack:
+
+- **Web application** → Look for Next.js, Vite, Remix, SvelteKit starters
+- **Mobile app** → Look for React Native, Expo, Flutter starters
+- **API/Backend** → Look for NestJS, Express, Fastify, Supabase starters
+- **CLI tool** → Look for CLI framework starters (oclif, commander, etc.)
+- **Full-stack** → Look for T3, RedwoodJS, Blitz, Next.js starters
+- **Desktop** → Look for Electron, Tauri starters
+
+### 2. UX Requirements Consideration
+
+If UX specification was loaded, consider UX requirements when selecting starter:
+
+- **Rich animations** → Framer Motion compatible starter
+- **Complex forms** → React Hook Form included starter
+- **Real-time features** → Socket.io or WebSocket ready starter
+- **Design system** → Storybook-enabled starter
+- **Offline capability** → Service worker or PWA configured starter
+
+### 3. Research Current Starter Options
+
+Search the web to find current, maintained starter templates:
+
+```
+Search the web: "{{primary_technology}} starter template CLI create command latest"
+Search the web: "{{primary_technology}} boilerplate generator latest options"
+Search the web: "{{primary_technology}} production-ready starter best practices"
+```
+
+### 4. Investigate Top Starter Options
+
+For each promising starter found, investigate details:
+
+```
+Search the web: "{{starter_name}} default setup technologies included latest"
+Search the web: "{{starter_name}} project structure file organization"
+Search the web: "{{starter_name}} production deployment capabilities"
+Search the web: "{{starter_name}} recent updates maintenance status"
+```
+
+### 5. Analyze What Each Starter Provides
+
+For each viable starter option, document:
+
+**Technology Decisions Made:**
+
+- Language/TypeScript configuration
+- Styling solution (CSS, Tailwind, Styled Components, etc.)
+- Testing framework setup
+- Linting/Formatting configuration
+- Build tooling and optimization
+- Project structure and organization
+
+**Architectural Patterns Established:**
+
+- Code organization patterns
+- Component structure conventions
+- API layering approach
+- State management setup
+- Routing patterns
+- Environment configuration
+
+**Development Experience Features:**
+
+- Hot reloading and development server
+- TypeScript configuration
+- Debugging setup
+- Testing infrastructure
+- Documentation generation
+
+### 6. Present Starter Options
+
+Based on user skill level and project needs:
+
+**For Expert Users:**
+"Found {{starter_name}} which provides:
+{{quick_decision_list_of_key_decisions}}
+
+This would establish our base architecture with these technical decisions already made. Use it?"
+
+**For Intermediate Users:**
+"I found {{starter_name}}, which is a well-maintained starter for {{project_type}} projects.
+
+It makes these architectural decisions for us:
+{{decision_list_with_explanations}}
+
+This gives us a solid foundation following current best practices. Should we use it?"
+
+**For Beginner Users:**
+"I found {{starter_name}}, which is like a pre-built foundation for your project.
+
+Think of it like buying a prefab house frame instead of cutting each board yourself.
+
+It makes these decisions for us:
+{{friendly_explanation_of_decisions}}
+
+This is a great starting point that follows best practices and saves us from making dozens of small technical choices. Should we use it?"
+
+### 7. Get Current CLI Commands
+
+If user shows interest in a starter, get the exact current commands:
+
+```
+Search the web: "{{starter_name}} CLI command options flags latest"
+Search the web: "{{starter_name}} create new project command examples"
+```
+
+### 8. Generate Starter Template Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+````markdown
+## Starter Template Evaluation
+
+### Primary Technology Domain
+
+{{identified_domain}} based on project requirements analysis
+
+### Starter Options Considered
+
+{{analysis_of_evaluated_starters}}
+
+### Selected Starter: {{starter_name}}
+
+**Rationale for Selection:**
+{{why_this_starter_was_chosen}}
+
+**Initialization Command:**
+
+```bash
+{{full_starter_command_with_options}}
+```
+
+**Architectural Decisions Provided by Starter:**
+
+**Language & Runtime:**
+{{language_typescript_setup}}
+
+**Styling Solution:**
+{{styling_solution_configuration}}
+
+**Build Tooling:**
+{{build_tools_and_optimization}}
+
+**Testing Framework:**
+{{testing_setup_and_configuration}}
+
+**Code Organization:**
+{{project_structure_and_patterns}}
+
+**Development Experience:**
+{{development_tools_and_workflow}}
+
+**Note:** Project initialization using this command should be the first implementation story.
+
+````
+
+### 9. Present Content and Menu
+
+Show the generated content and present choices:
+
+"I've analyzed starter template options for {{project_type}} projects.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 8]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Explore custom approaches or unconventional starters
+[P] Party Mode - Evaluate trade-offs from different perspectives
+[C] Continue - Save this decision and move to architectural decisions"
+
+### 10. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with current starter analysis
+- Process enhanced insights about starter options or custom approaches
+- Ask user: "Accept these changes to the starter template evaluation? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with starter evaluation context
+- Process collaborative insights about starter trade-offs
+- Ask user: "Accept these changes to the starter template evaluation? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/architecture.md`
+- Update frontmatter: `stepsCompleted: [1, 2, 3]`
+- Load `./step-04-decisions.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 8.
+
+## SUCCESS METRICS:
+
+✅ Primary technology domain correctly identified from project context
+✅ Current, maintained starter templates researched and evaluated
+✅ All versions verified using web search, not hardcoded
+✅ Architectural implications of starter choice clearly documented
+✅ User provided with clear rationale for starter selection
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not verifying current versions with web search
+❌ Ignoring UX requirements when evaluating starters
+❌ Not documenting what architectural decisions the starter makes
+❌ Failing to consider maintenance status of starter templates
+❌ Not providing clear rationale for starter selection
+❌ Not presenting A/P/C menu after content generation
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-04-decisions.md` to begin making specific architectural decisions.
+
+Remember: Do NOT proceed to step-04 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-architecture/steps/step-04-decisions.md b/.claude/skills/bmad-create-architecture/steps/step-04-decisions.md
new file mode 100644
index 0000000..061b69a
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/steps/step-04-decisions.md
@@ -0,0 +1,318 @@
+# Step 4: Core Architectural Decisions
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on making critical architectural decisions collaboratively
+- 🌐 ALWAYS search the web to verify current technology versions
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 🌐 Search the web to verify technology versions and options
+- ⚠️ Present A/P/C menu after each major decision category
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices for each decision category:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to explore innovative approaches to specific decisions
+- **P (Party Mode)**: Bring multiple perspectives to evaluate decision trade-offs
+- **C (Continue)**: Save the current decisions and proceed to next decision category
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Project context from step 2 is available
+- Starter template choice from step 3 is available
+- Project context file may contain technical preferences and rules
+- Technical preferences discovered in step 3 are available
+- Focus on decisions not already made by starter template or existing preferences
+- Collaborative decision making, not recommendations
+
+## YOUR TASK:
+
+Facilitate collaborative architectural decision making, leveraging existing technical preferences and starter template decisions, focusing on remaining choices critical to the project's success.
+
+## DECISION MAKING SEQUENCE:
+
+### 1. Load Decision Framework & Check Existing Preferences
+
+**Review Technical Preferences from Step 3:**
+"Based on our technical preferences discussion in step 3, let's build on those foundations:
+
+**Your Technical Preferences:**
+{{user_technical_preferences_from_step_3}}
+
+**Starter Template Decisions:**
+{{starter_template_decisions}}
+
+**Project Context Technical Rules:**
+{{project_context_technical_rules}}"
+
+**Identify Remaining Decisions:**
+Based on technical preferences, starter template choice, and project context, identify remaining critical decisions:
+
+**Already Decided (Don't re-decide these):**
+
+- {{starter_template_decisions}}
+- {{user_technology_preferences}}
+- {{project_context_technical_rules}}
+
+**Critical Decisions:** Must be decided before implementation can proceed
+**Important Decisions:** Shape the architecture significantly
+**Nice-to-Have:** Can be deferred if needed
+
+### 2. Decision Categories by Priority
+
+#### Category 1: Data Architecture
+
+- Database choice (if not determined by starter)
+- Data modeling approach
+- Data validation strategy
+- Migration approach
+- Caching strategy
+
+#### Category 2: Authentication & Security
+
+- Authentication method
+- Authorization patterns
+- Security middleware
+- Data encryption approach
+- API security strategy
+
+#### Category 3: API & Communication
+
+- API design patterns (REST, GraphQL, etc.)
+- API documentation approach
+- Error handling standards
+- Rate limiting strategy
+- Communication between services
+
+#### Category 4: Frontend Architecture (if applicable)
+
+- State management approach
+- Component architecture
+- Routing strategy
+- Performance optimization
+- Bundle optimization
+
+#### Category 5: Infrastructure & Deployment
+
+- Hosting strategy
+- CI/CD pipeline approach
+- Environment configuration
+- Monitoring and logging
+- Scaling strategy
+
+### 3. Facilitate Each Decision Category
+
+For each category, facilitate collaborative decision making:
+
+**Present the Decision:**
+Based on user skill level and project context:
+
+**Expert Mode:**
+"{{Decision_Category}}: {{Specific_Decision}}
+
+Options: {{concise_option_list_with_tradeoffs}}
+
+What's your preference for this decision?"
+
+**Intermediate Mode:**
+"Next decision: {{Human_Friendly_Category}}
+
+We need to choose {{Specific_Decision}}.
+
+Common options:
+{{option_list_with_brief_explanations}}
+
+For your project, I'd lean toward {{recommendation}} because {{reason}}. What are your thoughts?"
+
+**Beginner Mode:**
+"Let's talk about {{Human_Friendly_Category}}.
+
+{{Educational_Context_About_Why_This_Matters}}
+
+Think of it like {{real_world_analogy}}.
+
+Your main options:
+{{friendly_options_with_pros_cons}}
+
+My suggestion: {{recommendation}}
+This is good for you because {{beginner_friendly_reason}}.
+
+What feels right to you?"
+
+**Verify Technology Versions:**
+If decision involves specific technology:
+
+```
+Search the web: "{{technology}} latest stable version"
+Search the web: "{{technology}} current LTS version"
+Search the web: "{{technology}} production readiness"
+```
+
+**Get User Input:**
+"What's your preference? (or 'explain more' for details)"
+
+**Handle User Response:**
+
+- If user wants more info: Provide deeper explanation
+- If user has preference: Discuss implications and record decision
+- If user wants alternatives: Explore other options
+
+**Record the Decision:**
+
+- Category: {{category}}
+- Decision: {{user_choice}}
+- Version: {{verified_version_if_applicable}}
+- Rationale: {{user_reasoning_or_default}}
+- Affects: {{components_or_epics}}
+- Provided by Starter: {{yes_if_from_starter}}
+
+### 4. Check for Cascading Implications
+
+After each major decision, identify related decisions:
+
+"This choice means we'll also need to decide:
+
+- {{related_decision_1}}
+- {{related_decision_2}}"
+
+### 5. Generate Decisions Content
+
+After facilitating all decision categories, prepare the content to append:
+
+#### Content Structure:
+
+```markdown
+## Core Architectural Decisions
+
+### Decision Priority Analysis
+
+**Critical Decisions (Block Implementation):**
+{{critical_decisions_made}}
+
+**Important Decisions (Shape Architecture):**
+{{important_decisions_made}}
+
+**Deferred Decisions (Post-MVP):**
+{{decisions_deferred_with_rationale}}
+
+### Data Architecture
+
+{{data_related_decisions_with_versions_and_rationale}}
+
+### Authentication & Security
+
+{{security_related_decisions_with_versions_and_rationale}}
+
+### API & Communication Patterns
+
+{{api_related_decisions_with_versions_and_rationale}}
+
+### Frontend Architecture
+
+{{frontend_related_decisions_with_versions_and_rationale}}
+
+### Infrastructure & Deployment
+
+{{infrastructure_related_decisions_with_versions_and_rationale}}
+
+### Decision Impact Analysis
+
+**Implementation Sequence:**
+{{ordered_list_of_decisions_for_implementation}}
+
+**Cross-Component Dependencies:**
+{{how_decisions_affect_each_other}}
+```
+
+### 6. Present Content and Menu
+
+Show the generated decisions content and present choices:
+
+"I've documented all the core architectural decisions we've made together.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 5]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Explore innovative approaches to any specific decisions
+[P] Party Mode - Review decisions from multiple perspectives
+[C] Continue - Save these decisions and move to implementation patterns"
+
+### 7. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with specific decision categories
+- Process enhanced insights about particular decisions
+- Ask user: "Accept these enhancements to the architectural decisions? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with architectural decisions context
+- Process collaborative insights about decision trade-offs
+- Ask user: "Accept these changes to the architectural decisions? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/architecture.md`
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
+- Load `./step-05-patterns.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 5.
+
+## SUCCESS METRICS:
+
+✅ All critical architectural decisions made collaboratively
+✅ Technology versions verified using web search
+✅ Decision rationale clearly documented
+✅ Cascading implications identified and addressed
+✅ User provided appropriate level of explanation for skill level
+✅ A/P/C menu presented and handled correctly for each category
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Making recommendations instead of facilitating decisions
+❌ Not verifying technology versions with web search
+❌ Missing cascading implications between decisions
+❌ Not adapting explanations to user skill level
+❌ Forgetting to document decisions made by starter template
+❌ Not presenting A/P/C menu after content generation
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-05-patterns.md` to define implementation patterns that ensure consistency across AI agents.
+
+Remember: Do NOT proceed to step-05 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-architecture/steps/step-05-patterns.md b/.claude/skills/bmad-create-architecture/steps/step-05-patterns.md
new file mode 100644
index 0000000..6fa446d
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/steps/step-05-patterns.md
@@ -0,0 +1,359 @@
+# Step 5: Implementation Patterns & Consistency Rules
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on patterns that prevent AI agent implementation conflicts
+- 🎯 EMPHASIZE what agents could decide DIFFERENTLY if not specified
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 🎯 Focus on consistency, not implementation details
+- ⚠️ Present A/P/C menu after generating patterns content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop comprehensive consistency patterns
+- **P (Party Mode)**: Bring multiple perspectives to identify potential conflict points
+- **C (Continue)**: Save the patterns and proceed to project structure
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Core architectural decisions from step 4 are complete
+- Technology stack is decided and versions are verified
+- Focus on HOW agents should implement, not WHAT they should implement
+- Consider what could vary between different AI agents
+
+## YOUR TASK:
+
+Define implementation patterns and consistency rules that ensure multiple AI agents write compatible, consistent code that works together seamlessly.
+
+## PATTERNS DEFINITION SEQUENCE:
+
+### 1. Identify Potential Conflict Points
+
+Based on the chosen technology stack and decisions, identify where AI agents could make different choices:
+
+**Naming Conflicts:**
+
+- Database table/column naming conventions
+- API endpoint naming patterns
+- File and directory naming
+- Component/function/variable naming
+- Route parameter formats
+
+**Structural Conflicts:**
+
+- Where tests are located
+- How components are organized
+- Where utilities and helpers go
+- Configuration file organization
+- Static asset organization
+
+**Format Conflicts:**
+
+- API response wrapper formats
+- Error response structures
+- Date/time formats in APIs and UI
+- JSON field naming conventions
+- API status code usage
+
+**Communication Conflicts:**
+
+- Event naming conventions
+- Event payload structures
+- State update patterns
+- Action naming conventions
+- Logging formats and levels
+
+**Process Conflicts:**
+
+- Loading state handling
+- Error recovery patterns
+- Retry implementation approaches
+- Authentication flow patterns
+- Validation timing and methods
+
+### 2. Facilitate Pattern Decisions
+
+For each conflict category, facilitate collaborative pattern definition:
+
+**Present the Conflict Point:**
+"Given that we're using {{tech_stack}}, different AI agents might handle {{conflict_area}} differently.
+
+For example, one agent might name database tables 'users' while another uses 'Users' - this would cause conflicts.
+
+We need to establish consistent patterns that all agents follow."
+
+**Show Options and Trade-offs:**
+"Common approaches for {{pattern_category}}:
+
+1. {{option_1}} - {{pros_and_cons}}
+2. {{option_2}} - {{pros_and_cons}}
+3. {{option_3}} - {{pros_and_cons}}
+
+Which approach makes the most sense for our project?"
+
+**Get User Decision:**
+"What's your preference for this pattern? (or discuss the trade-offs more)"
+
+### 3. Define Pattern Categories
+
+#### Naming Patterns
+
+**Database Naming:**
+
+- Table naming: users, Users, or user?
+- Column naming: user_id or userId?
+- Foreign key format: user_id or fk_user?
+- Index naming: idx_users_email or users_email_index?
+
+**API Naming:**
+
+- REST endpoint naming: /users or /user? Plural or singular?
+- Route parameter format: :id or {id}?
+- Query parameter naming: user_id or userId?
+- Header naming conventions: X-Custom-Header or Custom-Header?
+
+**Code Naming:**
+
+- Component naming: UserCard or user-card?
+- File naming: UserCard.tsx or user-card.tsx?
+- Function naming: getUserData or get_user_data?
+- Variable naming: userId or user_id?
+
+#### Structure Patterns
+
+**Project Organization:**
+
+- Where do tests live? **tests**/ or \*.test.ts co-located?
+- How are components organized? By feature or by type?
+- Where do shared utilities go?
+- How are services and repositories organized?
+
+**File Structure:**
+
+- Config file locations and naming
+- Static asset organization
+- Documentation placement
+- Environment file organization
+
+#### Format Patterns
+
+**API Formats:**
+
+- API response wrapper? {data: ..., error: ...} or direct response?
+- Error format? {message, code} or {error: {type, detail}}?
+- Date format in JSON? ISO strings or timestamps?
+- Success response structure?
+
+**Data Formats:**
+
+- JSON field naming: snake_case or camelCase?
+- Boolean representations: true/false or 1/0?
+- Null handling patterns
+- Array vs object for single items
+
+#### Communication Patterns
+
+**Event Systems:**
+
+- Event naming convention: user.created or UserCreated?
+- Event payload structure standards
+- Event versioning approach
+- Async event handling patterns
+
+**State Management:**
+
+- State update patterns: immutable updates or direct mutation?
+- Action naming conventions
+- Selector patterns
+- State organization principles
+
+#### Process Patterns
+
+**Error Handling:**
+
+- Global error handling approach
+- Error boundary patterns
+- User-facing error message format
+- Logging vs user error distinction
+
+**Loading States:**
+
+- Loading state naming conventions
+- Global vs local loading states
+- Loading state persistence
+- Loading UI patterns
+
+### 4. Generate Patterns Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+```markdown
+## Implementation Patterns & Consistency Rules
+
+### Pattern Categories Defined
+
+**Critical Conflict Points Identified:**
+{{number_of_potential_conflicts}} areas where AI agents could make different choices
+
+### Naming Patterns
+
+**Database Naming Conventions:**
+{{database_naming_rules_with_examples}}
+
+**API Naming Conventions:**
+{{api_naming_rules_with_examples}}
+
+**Code Naming Conventions:**
+{{code_naming_rules_with_examples}}
+
+### Structure Patterns
+
+**Project Organization:**
+{{project_structure_rules_with_examples}}
+
+**File Structure Patterns:**
+{{file_organization_rules_with_examples}}
+
+### Format Patterns
+
+**API Response Formats:**
+{{api_response_structure_rules}}
+
+**Data Exchange Formats:**
+{{data_format_rules_with_examples}}
+
+### Communication Patterns
+
+**Event System Patterns:**
+{{event_naming_and_structure_rules}}
+
+**State Management Patterns:**
+{{state_update_and_organization_rules}}
+
+### Process Patterns
+
+**Error Handling Patterns:**
+{{consistent_error_handling_approaches}}
+
+**Loading State Patterns:**
+{{loading_state_management_rules}}
+
+### Enforcement Guidelines
+
+**All AI Agents MUST:**
+
+- {{mandatory_pattern_1}}
+- {{mandatory_pattern_2}}
+- {{mandatory_pattern_3}}
+
+**Pattern Enforcement:**
+
+- How to verify patterns are followed
+- Where to document pattern violations
+- Process for updating patterns
+
+### Pattern Examples
+
+**Good Examples:**
+{{concrete_examples_of_correct_pattern_usage}}
+
+**Anti-Patterns:**
+{{examples_of_what_to_avoid}}
+```
+
+### 5. Present Content and Menu
+
+Show the generated patterns content and present choices:
+
+"I've documented implementation patterns that will prevent conflicts between AI agents working on this project.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 4]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Explore additional consistency patterns
+[P] Party Mode - Review patterns from different implementation perspectives
+[C] Continue - Save these patterns and move to project structure"
+
+### 6. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with current patterns
+- Process enhanced consistency rules that come back
+- Ask user: "Accept these additional pattern refinements? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with implementation patterns context
+- Process collaborative insights about potential conflicts
+- Ask user: "Accept these changes to the implementation patterns? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/architecture.md`
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
+- Load `./step-06-structure.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 4.
+
+## SUCCESS METRICS:
+
+✅ All potential AI agent conflict points identified and addressed
+✅ Comprehensive patterns defined for naming, structure, and communication
+✅ Concrete examples provided for each pattern
+✅ Enforcement guidelines clearly documented
+✅ User collaborated on pattern decisions rather than receiving recommendations
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Missing potential conflict points that could cause agent conflicts
+❌ Being too prescriptive about implementation details instead of focusing on consistency
+❌ Not providing concrete examples for each pattern
+❌ Failing to address cross-cutting concerns like error handling
+❌ Not considering the chosen technology stack when defining patterns
+❌ Not presenting A/P/C menu after content generation
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-06-structure.md` to define the complete project structure.
+
+Remember: Do NOT proceed to step-06 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-architecture/steps/step-06-structure.md b/.claude/skills/bmad-create-architecture/steps/step-06-structure.md
new file mode 100644
index 0000000..195abaf
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/steps/step-06-structure.md
@@ -0,0 +1,379 @@
+# Step 6: Project Structure & Boundaries
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on defining complete project structure and clear boundaries
+- 🗺️ MAP requirements/epics to architectural components
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 🗺️ Create complete project tree, not generic placeholders
+- ⚠️ Present A/P/C menu after generating project structure
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to explore innovative project organization approaches
+- **P (Party Mode)**: Bring multiple perspectives to evaluate project structure trade-offs
+- **C (Continue)**: Save the project structure and proceed to validation
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- All previous architectural decisions are complete
+- Implementation patterns and consistency rules are defined
+- Focus on physical project structure and component boundaries
+- Map requirements to specific files and directories
+
+## YOUR TASK:
+
+Define the complete project structure and architectural boundaries based on all decisions made, creating a concrete implementation guide for AI agents.
+
+## PROJECT STRUCTURE SEQUENCE:
+
+### 1. Analyze Requirements Mapping
+
+Map project requirements to architectural components:
+
+**From Epics (if available):**
+"Epic: {{epic_name}} → Lives in {{module/directory/service}}"
+
+- User stories within the epic
+- Cross-epic dependencies
+- Shared components needed
+
+**From FR Categories (if no epics):**
+"FR Category: {{fr_category_name}} → Lives in {{module/directory/service}}"
+
+- Related functional requirements
+- Shared functionality across categories
+- Integration points between categories
+
+### 2. Define Project Directory Structure
+
+Based on technology stack and patterns, create the complete project structure:
+
+**Root Configuration Files:**
+
+- Package management files (package.json, requirements.txt, etc.)
+- Build and development configuration
+- Environment configuration files
+- CI/CD pipeline files
+- Documentation files
+
+**Source Code Organization:**
+
+- Application entry points
+- Core application structure
+- Feature/module organization
+- Shared utilities and libraries
+- Configuration and environment files
+
+**Test Organization:**
+
+- Unit test locations and structure
+- Integration test organization
+- End-to-end test structure
+- Test utilities and fixtures
+
+**Build and Distribution:**
+
+- Build output directories
+- Distribution files
+- Static assets
+- Documentation build
+
+### 3. Define Integration Boundaries
+
+Map how components communicate and where boundaries exist:
+
+**API Boundaries:**
+
+- External API endpoints
+- Internal service boundaries
+- Authentication and authorization boundaries
+- Data access layer boundaries
+
+**Component Boundaries:**
+
+- Frontend component communication patterns
+- State management boundaries
+- Service communication patterns
+- Event-driven integration points
+
+**Data Boundaries:**
+
+- Database schema boundaries
+- Data access patterns
+- Caching boundaries
+- External data integration points
+
+### 4. Create Complete Project Tree
+
+Generate a comprehensive directory structure showing all files and directories:
+
+**Technology-Specific Structure Examples:**
+
+**Next.js Full-Stack:**
+
+```
+project-name/
+├── README.md
+├── package.json
+├── next.config.js
+├── tailwind.config.js
+├── tsconfig.json
+├── .env.local
+├── .env.example
+├── .gitignore
+├── .github/
+│   └── workflows/
+│       └── ci.yml
+├── src/
+│   ├── app/
+│   │   ├── globals.css
+│   │   ├── layout.tsx
+│   │   └── page.tsx
+│   ├── components/
+│   │   ├── ui/
+│   │   ├── forms/
+│   │   └── features/
+│   ├── lib/
+│   │   ├── db.ts
+│   │   ├── auth.ts
+│   │   └── utils.ts
+│   ├── types/
+│   └── middleware.ts
+├── prisma/
+│   ├── schema.prisma
+│   └── migrations/
+├── tests/
+│   ├── __mocks__/
+│   ├── components/
+│   └── e2e/
+└── public/
+    └── assets/
+```
+
+**API Backend (NestJS):**
+
+```
+project-name/
+├── package.json
+├── nest-cli.json
+├── tsconfig.json
+├── .env
+├── .env.example
+├── .gitignore
+├── README.md
+├── src/
+│   ├── main.ts
+│   ├── app.module.ts
+│   ├── config/
+│   ├── modules/
+│   │   ├── auth/
+│   │   ├── users/
+│   │   └── common/
+│   ├── services/
+│   ├── repositories/
+│   ├── decorators/
+│   ├── pipes/
+│   ├── guards/
+│   └── interceptors/
+├── test/
+│   ├── unit/
+│   ├── integration/
+│   └── e2e/
+├── prisma/
+│   ├── schema.prisma
+│   └── migrations/
+└── docker-compose.yml
+```
+
+### 5. Map Requirements to Structure
+
+Create explicit mapping from project requirements to specific files/directories:
+
+**Epic/Feature Mapping:**
+"Epic: User Management
+
+- Components: src/components/features/users/
+- Services: src/services/users/
+- API Routes: src/app/api/users/
+- Database: prisma/migrations/_*users*_
+- Tests: tests/features/users/"
+
+**Cross-Cutting Concerns:**
+"Authentication System
+
+- Components: src/components/auth/
+- Services: src/services/auth/
+- Middleware: src/middleware/auth.ts
+- Guards: src/guards/auth.guard.ts
+- Tests: tests/auth/"
+
+### 6. Generate Structure Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+```markdown
+## Project Structure & Boundaries
+
+### Complete Project Directory Structure
+```
+
+{{complete_project_tree_with_all_files_and_directories}}
+
+```
+
+### Architectural Boundaries
+
+**API Boundaries:**
+{{api_boundary_definitions_and_endpoints}}
+
+**Component Boundaries:**
+{{component_communication_patterns_and_boundaries}}
+
+**Service Boundaries:**
+{{service_integration_patterns_and_boundaries}}
+
+**Data Boundaries:**
+{{data_access_patterns_and_boundaries}}
+
+### Requirements to Structure Mapping
+
+**Feature/Epic Mapping:**
+{{mapping_of_epics_or_features_to_specific_directories}}
+
+**Cross-Cutting Concerns:**
+{{mapping_of_shared_functionality_to_locations}}
+
+### Integration Points
+
+**Internal Communication:**
+{{how_components_within_the_project_communicate}}
+
+**External Integrations:**
+{{third_party_service_integration_points}}
+
+**Data Flow:**
+{{how_data_flows_through_the_architecture}}
+
+### File Organization Patterns
+
+**Configuration Files:**
+{{where_and_how_config_files_are_organized}}
+
+**Source Organization:**
+{{how_source_code_is_structured_and_organized}}
+
+**Test Organization:**
+{{how_tests_are_structured_and_organized}}
+
+**Asset Organization:**
+{{how_static_and_dynamic_assets_are_organized}}
+
+### Development Workflow Integration
+
+**Development Server Structure:**
+{{how_the_project_is organized_for_development}}
+
+**Build Process Structure:**
+{{how_the_build_process_uses_the_project_structure}}
+
+**Deployment Structure:**
+{{how_the_project_structure_supports_deployment}}
+```
+
+### 7. Present Content and Menu
+
+Show the generated project structure content and present choices:
+
+"I've created a complete project structure based on all our architectural decisions.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Explore innovative project organization approaches
+[P] Party Mode - Review structure from different development perspectives
+[C] Continue - Save this structure and move to architecture validation"
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with current project structure
+- Process enhanced organizational insights that come back
+- Ask user: "Accept these changes to the project structure? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with project structure context
+- Process collaborative insights about organization trade-offs
+- Ask user: "Accept these changes to the project structure? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/architecture.md`
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6]`
+- Load `./step-07-validation.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Complete project tree defined with all files and directories
+✅ All architectural boundaries clearly documented
+✅ Requirements/epics mapped to specific locations
+✅ Integration points and communication patterns defined
+✅ Project structure aligned with chosen technology stack
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Creating generic placeholder structure instead of specific, complete tree
+❌ Not mapping requirements to specific files and directories
+❌ Missing important integration boundaries
+❌ Not considering the chosen technology stack in structure design
+❌ Not defining how components communicate across boundaries
+❌ Not presenting A/P/C menu after content generation
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-07-validation.md` to validate architectural coherence and completeness.
+
+Remember: Do NOT proceed to step-07 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-architecture/steps/step-07-validation.md b/.claude/skills/bmad-create-architecture/steps/step-07-validation.md
new file mode 100644
index 0000000..3275c5d
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/steps/step-07-validation.md
@@ -0,0 +1,359 @@
+# Step 7: Architecture Validation & Completion
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on validating architectural coherence and completeness
+- ✅ VALIDATE all requirements are covered by architectural decisions
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ✅ Run comprehensive validation checks on the complete architecture
+- ⚠️ Present A/P/C menu after generating validation results
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6, 7]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to address complex architectural issues found during validation
+- **P (Party Mode)**: Bring multiple perspectives to resolve validation concerns
+- **C (Continue)**: Save the validation results and complete the architecture
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Complete architecture document with all sections is available
+- All architectural decisions, patterns, and structure are defined
+- Focus on validation, gap analysis, and coherence checking
+- Prepare for handoff to implementation phase
+
+## YOUR TASK:
+
+Validate the complete architecture for coherence, completeness, and readiness to guide AI agents through consistent implementation.
+
+## VALIDATION SEQUENCE:
+
+### 1. Coherence Validation
+
+Check that all architectural decisions work together:
+
+**Decision Compatibility:**
+
+- Do all technology choices work together without conflicts?
+- Are all versions compatible with each other?
+- Do patterns align with technology choices?
+- Are there any contradictory decisions?
+
+**Pattern Consistency:**
+
+- Do implementation patterns support the architectural decisions?
+- Are naming conventions consistent across all areas?
+- Do structure patterns align with technology stack?
+- Are communication patterns coherent?
+
+**Structure Alignment:**
+
+- Does the project structure support all architectural decisions?
+- Are boundaries properly defined and respected?
+- Does the structure enable the chosen patterns?
+- Are integration points properly structured?
+
+### 2. Requirements Coverage Validation
+
+Verify all project requirements are architecturally supported:
+
+**From Epics (if available):**
+
+- Does every epic have architectural support?
+- Are all user stories implementable with these decisions?
+- Are cross-epic dependencies handled architecturally?
+- Are there any gaps in epic coverage?
+
+**From FR Categories (if no epics):**
+
+- Does every functional requirement have architectural support?
+- Are all FR categories fully covered by architectural decisions?
+- Are cross-cutting FRs properly addressed?
+- Are there any missing architectural capabilities?
+
+**Non-Functional Requirements:**
+
+- Are performance requirements addressed architecturally?
+- Are security requirements fully covered?
+- Are scalability considerations properly handled?
+- Are compliance requirements architecturally supported?
+
+### 3. Implementation Readiness Validation
+
+Assess if AI agents can implement consistently:
+
+**Decision Completeness:**
+
+- Are all critical decisions documented with versions?
+- Are implementation patterns comprehensive enough?
+- Are consistency rules clear and enforceable?
+- Are examples provided for all major patterns?
+
+**Structure Completeness:**
+
+- Is the project structure complete and specific?
+- Are all files and directories defined?
+- Are integration points clearly specified?
+- Are component boundaries well-defined?
+
+**Pattern Completeness:**
+
+- Are all potential conflict points addressed?
+- Are naming conventions comprehensive?
+- Are communication patterns fully specified?
+- Are process patterns (error handling, etc.) complete?
+
+### 4. Gap Analysis
+
+Identify and document any missing elements:
+
+**Critical Gaps:**
+
+- Missing architectural decisions that block implementation
+- Incomplete patterns that could cause conflicts
+- Missing structural elements needed for development
+- Undefined integration points
+
+**Important Gaps:**
+
+- Areas that need more detailed specification
+- Patterns that could be more comprehensive
+- Documentation that would help implementation
+- Examples that would clarify complex decisions
+
+**Nice-to-Have Gaps:**
+
+- Additional patterns that would be helpful
+- Supplementary documentation
+- Tooling recommendations
+- Development workflow optimizations
+
+### 5. Address Validation Issues
+
+For any issues found, facilitate resolution:
+
+**Critical Issues:**
+"I found some issues that need to be addressed before implementation:
+
+{{critical_issue_description}}
+
+These could cause implementation problems. How would you like to resolve this?"
+
+**Important Issues:**
+"I noticed a few areas that could be improved:
+
+{{important_issue_description}}
+
+These aren't blocking, but addressing them would make implementation smoother. Should we work on these?"
+
+**Minor Issues:**
+"Here are some minor suggestions for improvement:
+
+{{minor_issue_description}}
+
+These are optional refinements. Would you like to address any of these?"
+
+### 6. Generate Validation Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+```markdown
+## Architecture Validation Results
+
+### Coherence Validation ✅
+
+**Decision Compatibility:**
+{{assessment_of_how_all_decisions_work_together}}
+
+**Pattern Consistency:**
+{{verification_that_patterns_support_decisions}}
+
+**Structure Alignment:**
+{{confirmation_that_structure_supports_architecture}}
+
+### Requirements Coverage Validation ✅
+
+**Epic/Feature Coverage:**
+{{verification_that_all_epics_or_features_are_supported}}
+
+**Functional Requirements Coverage:**
+{{confirmation_that_all_FRs_are_architecturally_supported}}
+
+**Non-Functional Requirements Coverage:**
+{{verification_that_NFRs_are_addressed}}
+
+### Implementation Readiness Validation ✅
+
+**Decision Completeness:**
+{{assessment_of_decision_documentation_completeness}}
+
+**Structure Completeness:**
+{{evaluation_of_project_structure_completeness}}
+
+**Pattern Completeness:**
+{{verification_of_implementation_patterns_completeness}}
+
+### Gap Analysis Results
+
+{{gap_analysis_findings_with_priority_levels}}
+
+### Validation Issues Addressed
+
+{{description_of_any_issues_found_and_resolutions}}
+
+### Architecture Completeness Checklist
+
+**✅ Requirements Analysis**
+
+- [x] Project context thoroughly analyzed
+- [x] Scale and complexity assessed
+- [x] Technical constraints identified
+- [x] Cross-cutting concerns mapped
+
+**✅ Architectural Decisions**
+
+- [x] Critical decisions documented with versions
+- [x] Technology stack fully specified
+- [x] Integration patterns defined
+- [x] Performance considerations addressed
+
+**✅ Implementation Patterns**
+
+- [x] Naming conventions established
+- [x] Structure patterns defined
+- [x] Communication patterns specified
+- [x] Process patterns documented
+
+**✅ Project Structure**
+
+- [x] Complete directory structure defined
+- [x] Component boundaries established
+- [x] Integration points mapped
+- [x] Requirements to structure mapping complete
+
+### Architecture Readiness Assessment
+
+**Overall Status:** READY FOR IMPLEMENTATION
+
+**Confidence Level:** {{high/medium/low}} based on validation results
+
+**Key Strengths:**
+{{list_of_architecture_strengths}}
+
+**Areas for Future Enhancement:**
+{{areas_that_could_be_improved_later}}
+
+### Implementation Handoff
+
+**AI Agent Guidelines:**
+
+- Follow all architectural decisions exactly as documented
+- Use implementation patterns consistently across all components
+- Respect project structure and boundaries
+- Refer to this document for all architectural questions
+
+**First Implementation Priority:**
+{{starter_template_command_or_first_architectural_step}}
+```
+
+### 7. Present Content and Menu
+
+Show the validation results and present choices:
+
+"I've completed a comprehensive validation of your architecture.
+
+**Validation Summary:**
+
+- ✅ Coherence: All decisions work together
+- ✅ Coverage: All requirements are supported
+- ✅ Readiness: AI agents can implement consistently
+
+**Here's what I'll add to complete the architecture document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Address any complex architectural concerns
+[P] Party Mode - Review validation from different implementation perspectives
+[C] Continue - Complete the architecture and finish workflow
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with validation issues
+- Process enhanced solutions for complex concerns
+- Ask user: "Accept these architectural improvements? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with validation context
+- Process collaborative insights on implementation readiness
+- Ask user: "Accept these changes to the validation results? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/architecture.md`
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6, 7]`
+- Load `./step-08-complete.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ All architectural decisions validated for coherence
+✅ Complete requirements coverage verified
+✅ Implementation readiness confirmed
+✅ All gaps identified and addressed
+✅ Comprehensive validation checklist completed
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Skipping validation of decision compatibility
+❌ Not verifying all requirements are architecturally supported
+❌ Missing potential implementation conflicts
+❌ Not addressing gaps found during validation
+❌ Providing incomplete validation checklist
+❌ Not presenting A/P/C menu after content generation
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-08-complete.md` to complete the workflow and provide implementation guidance.
+
+Remember: Do NOT proceed to step-08 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-architecture/steps/step-08-complete.md b/.claude/skills/bmad-create-architecture/steps/step-08-complete.md
new file mode 100644
index 0000000..e378fc9
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/steps/step-08-complete.md
@@ -0,0 +1,76 @@
+# Step 8: Architecture Completion & Handoff
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- ✅ ALWAYS treat this as collaborative completion between architectural peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on successful workflow completion and implementation handoff
+- 🎯 PROVIDE clear next steps for implementation phase
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 🎯 Present completion summary and implementation guidance
+- 📖 Update frontmatter with final workflow state
+- 🚫 THIS IS THE FINAL STEP IN THIS WORKFLOW
+
+## YOUR TASK:
+
+Complete the architecture workflow, provide a comprehensive completion summary, and guide the user to the next phase of their project development.
+
+## COMPLETION SEQUENCE:
+
+### 1. Congratulate the User on Completion
+
+Both you and the User completed something amazing here - give a summary of what you achieved together and really congratulate the user on a job well done.
+
+### 2. Update the created document's frontmatter
+
+```yaml
+stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]
+workflowType: 'architecture'
+lastStep: 8
+status: 'complete'
+completedAt: '{{current_date}}'
+```
+
+### 3. Next Steps Guidance
+
+Architecture complete. Invoke the `bmad-help` skill.
+
+Upon Completion of task output: offer to answer any questions about the Architecture Document.
+
+
+## SUCCESS METRICS:
+
+✅ Complete architecture document delivered with all sections
+✅ All architectural decisions documented and validated
+✅ Implementation patterns and consistency rules finalized
+✅ Project structure complete with all files and directories
+✅ User provided with clear next steps and implementation guidance
+✅ Workflow status properly updated
+✅ User collaboration maintained throughout completion process
+
+## FAILURE MODES:
+
+❌ Not providing clear implementation guidance
+❌ Missing final validation of document completeness
+❌ Not updating workflow status appropriately
+❌ Failing to celebrate the successful completion
+❌ Not providing specific next steps for the user
+❌ Rushing completion without proper summary
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## WORKFLOW COMPLETE:
+
+This is the final step of the Architecture workflow. The user now has a complete, validated architecture document ready for AI agent implementation.
+
+The architecture will serve as the single source of truth for all technical decisions, ensuring consistent implementation across the entire project development lifecycle.
diff --git a/.claude/skills/bmad-create-architecture/workflow.md b/.claude/skills/bmad-create-architecture/workflow.md
new file mode 100644
index 0000000..3dd945b
--- /dev/null
+++ b/.claude/skills/bmad-create-architecture/workflow.md
@@ -0,0 +1,32 @@
+# Architecture Workflow
+
+**Goal:** Create comprehensive architecture decisions through collaborative step-by-step discovery that ensures AI agents implement consistently.
+
+**Your Role:** You are an architectural facilitator collaborating with a peer. This is a partnership, not a client-vendor relationship. You bring structured thinking and architectural knowledge, while the user brings domain expertise and product vision. Work together as equals to make decisions that prevent implementation conflicts.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- Document state tracked in frontmatter
+- Append-only document building through conversation
+- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. EXECUTION
+
+Read fully and follow: `./steps/step-01-init.md` to begin the workflow.
+
+**Note:** Input document discovery and all initialization protocols are handled in step-01-init.md.
diff --git a/.claude/skills/bmad-create-epics-and-stories/SKILL.md b/.claude/skills/bmad-create-epics-and-stories/SKILL.md
new file mode 100644
index 0000000..d092487
--- /dev/null
+++ b/.claude/skills/bmad-create-epics-and-stories/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-create-epics-and-stories
+description: 'Break requirements into epics and user stories. Use when the user says "create the epics and stories list"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.md b/.claude/skills/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.md
new file mode 100644
index 0000000..91ad17e
--- /dev/null
+++ b/.claude/skills/bmad-create-epics-and-stories/steps/step-01-validate-prerequisites.md
@@ -0,0 +1,255 @@
+# Step 1: Validate Prerequisites and Extract Requirements
+
+## STEP GOAL:
+
+To validate that all required input documents exist and extract all requirements (FRs, NFRs, and additional requirements from UX/Architecture) needed for epic and story creation.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring requirements extraction expertise
+- ✅ User brings their product vision and context
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on extracting and organizing requirements
+- 🚫 FORBIDDEN to start creating epics or stories in this step
+- 💬 Extract requirements from ALL available documents
+- 🚪 POPULATE the template sections exactly as needed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract requirements systematically from all documents
+- 💾 Populate {planning_artifacts}/epics.md with extracted requirements
+- 📖 Update frontmatter with extraction progress
+- 🚫 FORBIDDEN to load next step until user selects 'C' and requirements are extracted
+
+## REQUIREMENTS EXTRACTION PROCESS:
+
+### 1. Welcome and Overview
+
+Welcome {user_name} to comprehensive epic and story creation!
+
+**CRITICAL PREREQUISITE VALIDATION:**
+
+Verify required documents exist and are complete:
+
+1. **PRD.md** - Contains requirements (FRs and NFRs) and product scope
+2. **Architecture.md** - Contains technical decisions, API contracts, data models
+3. **UX Design.md** (if UI exists) - Contains interaction patterns, mockups, user flows
+
+### 2. Document Discovery and Validation
+
+Search for required documents using these patterns (sharded means a large document was split into multiple small files with an index.md into a folder) - if the whole document is found, use that instead of the sharded version:
+
+**PRD Document Search Priority:**
+
+1. `{planning_artifacts}/*prd*.md` (whole document)
+2. `{planning_artifacts}/*prd*/index.md` (sharded version)
+
+**Architecture Document Search Priority:**
+
+1. `{planning_artifacts}/*architecture*.md` (whole document)
+2. `{planning_artifacts}/*architecture*/index.md` (sharded version)
+
+**UX Design Document Search (Optional):**
+
+1. `{planning_artifacts}/*ux*.md` (whole document)
+2. `{planning_artifacts}/*ux*/index.md` (sharded version)
+
+Before proceeding, Ask the user if there are any other documents to include for analysis, and if anything found should be excluded. Wait for user confirmation. Once confirmed, create the {planning_artifacts}/epics.md from the ../templates/epics-template.md and in the front matter list the files in the array of `inputDocuments: []`.
+
+### 3. Extract Functional Requirements (FRs)
+
+From the PRD document (full or sharded), read then entire document and extract ALL functional requirements:
+
+**Extraction Method:**
+
+- Look for numbered items like "FR1:", "Functional Requirement 1:", or similar
+- Identify requirement statements that describe what the system must DO
+- Include user actions, system behaviors, and business rules
+
+**Format the FR list as:**
+
+```
+FR1: [Clear, testable requirement description]
+FR2: [Clear, testable requirement description]
+...
+```
+
+### 4. Extract Non-Functional Requirements (NFRs)
+
+From the PRD document, extract ALL non-functional requirements:
+
+**Extraction Method:**
+
+- Look for performance, security, usability, reliability requirements
+- Identify constraints and quality attributes
+- Include technical standards and compliance requirements
+
+**Format the NFR list as:**
+
+```
+NFR1: [Performance/Security/Usability requirement]
+NFR2: [Performance/Security/Usability requirement]
+...
+```
+
+### 5. Extract Additional Requirements from Architecture
+
+Review the Architecture document for technical requirements that impact epic and story creation:
+
+**Look for:**
+
+- **Starter Template**: Does Architecture specify a starter/greenfield template? If YES, document this for Epic 1 Story 1
+- Infrastructure and deployment requirements
+- Integration requirements with external systems
+- Data migration or setup requirements
+- Monitoring and logging requirements
+- API versioning or compatibility requirements
+- Security implementation requirements
+
+**IMPORTANT**: If a starter template is mentioned in Architecture, note it prominently. This will impact Epic 1 Story 1.
+
+**Format Additional Requirements as:**
+
+```
+- [Technical requirement from Architecture that affects implementation]
+- [Infrastructure setup requirement]
+- [Integration requirement]
+...
+```
+
+### 6. Extract UX Design Requirements (if UX document exists)
+
+**IMPORTANT**: The UX Design Specification is a first-class input document, not supplementary material. Requirements from the UX spec must be extracted with the same rigor as PRD functional requirements.
+
+Read the FULL UX Design document and extract ALL actionable work items:
+
+**Look for:**
+
+- **Design token work**: Color systems, spacing scales, typography tokens that need implementation or consolidation
+- **Component proposals**: Reusable UI components identified in the UX spec (e.g., ConfirmActions, StatusMessage, EmptyState, FocusIndicator)
+- **Visual standardization**: Semantic CSS classes, consistent color palette usage, design pattern consolidation
+- **Accessibility requirements**: Contrast audit fixes, ARIA patterns, keyboard navigation, screen reader support
+- **Responsive design requirements**: Breakpoints, layout adaptations, mobile-specific interactions
+- **Interaction patterns**: Animations, transitions, loading states, error handling UX
+- **Browser/device compatibility**: Target platforms, progressive enhancement requirements
+
+**Format UX Design Requirements as a SEPARATE section (not merged into Additional Requirements):**
+
+```
+UX-DR1: [Actionable UX design requirement with clear implementation scope]
+UX-DR2: [Actionable UX design requirement with clear implementation scope]
+...
+```
+
+**🚨 CRITICAL**: Do NOT reduce UX requirements to vague summaries. Each UX-DR must be specific enough to generate a story with testable acceptance criteria. If the UX spec identifies 6 reusable components, list all 6 — not "create reusable components."
+
+### 7. Load and Initialize Template
+
+Load ../templates/epics-template.md and initialize {planning_artifacts}/epics.md:
+
+1. Copy the entire template to {planning_artifacts}/epics.md
+2. Replace {{project_name}} with the actual project name
+3. Replace placeholder sections with extracted requirements:
+   - {{fr_list}} → extracted FRs
+   - {{nfr_list}} → extracted NFRs
+   - {{additional_requirements}} → extracted additional requirements (from Architecture)
+   - {{ux_design_requirements}} → extracted UX Design Requirements (if UX document exists)
+4. Leave {{requirements_coverage_map}} and {{epics_list}} as placeholders for now
+
+### 8. Present Extracted Requirements
+
+Display to user:
+
+**Functional Requirements Extracted:**
+
+- Show count of FRs found
+- Display the first few FRs as examples
+- Ask if any FRs are missing or incorrectly captured
+
+**Non-Functional Requirements Extracted:**
+
+- Show count of NFRs found
+- Display key NFRs
+- Ask if any constraints were missed
+
+**Additional Requirements (Architecture):**
+
+- Summarize technical requirements from Architecture
+- Verify completeness
+
+**UX Design Requirements (if applicable):**
+
+- Show count of UX-DRs found
+- Display key UX Design requirements (design tokens, components, accessibility)
+- Verify each UX-DR is specific enough for story creation
+
+### 9. Get User Confirmation
+
+Ask: "Do these extracted requirements accurately represent what needs to be built? Any additions or corrections?"
+
+Update the requirements based on user feedback until confirmation is received.
+
+## CONTENT TO SAVE TO DOCUMENT:
+
+After extraction and confirmation, update {planning_artifacts}/epics.md with:
+
+- Complete FR list in {{fr_list}} section
+- Complete NFR list in {{nfr_list}} section
+- All additional requirements in {{additional_requirements}} section
+- UX Design requirements in {{ux_design_requirements}} section (if UX document exists)
+
+### 10. Present MENU OPTIONS
+
+Display: `**Confirm the Requirements are complete and correct to [C] continue:**`
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then end with display again of the menu option
+
+#### Menu Handling Logic:
+
+- IF C: Save all to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-02-design-epics.md
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#10-present-menu-options)
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and all requirements are saved to document and frontmatter is updated, will you then read fully and follow: ./step-02-design-epics.md to begin epic design step.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All required documents found and validated
+- All FRs extracted and formatted correctly
+- All NFRs extracted and formatted correctly
+- Additional requirements from Architecture/UX identified
+- Template initialized with requirements
+- User confirms requirements are complete and accurate
+
+### ❌ SYSTEM FAILURE:
+
+- Missing required documents
+- Incomplete requirements extraction
+- Template not properly initialized
+- Not saving requirements to output file
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
diff --git a/.claude/skills/bmad-create-epics-and-stories/steps/step-02-design-epics.md b/.claude/skills/bmad-create-epics-and-stories/steps/step-02-design-epics.md
new file mode 100644
index 0000000..00dd285
--- /dev/null
+++ b/.claude/skills/bmad-create-epics-and-stories/steps/step-02-design-epics.md
@@ -0,0 +1,212 @@
+# Step 2: Design Epic List
+
+## STEP GOAL:
+
+To design and get approval for the epics_list that will organize all requirements into user-value-focused epics.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring product strategy and epic design expertise
+- ✅ User brings their product vision and priorities
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on creating the epics_list
+- 🚫 FORBIDDEN to create individual stories in this step
+- 💬 Organize epics around user value, not technical layers
+- 🚪 GET explicit approval for the epics_list
+- 🔗 **CRITICAL: Each epic must be standalone and enable future epics without requiring future epics to function**
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Design epics collaboratively based on extracted requirements
+- 💾 Update {{epics_list}} in {planning_artifacts}/epics.md
+- 📖 Document the FR coverage mapping
+- 🚫 FORBIDDEN to load next step until user approves epics_list
+
+## EPIC DESIGN PROCESS:
+
+### 1. Review Extracted Requirements
+
+Load {planning_artifacts}/epics.md and review:
+
+- **Functional Requirements:** Count and review FRs from Step 1
+- **Non-Functional Requirements:** Review NFRs that need to be addressed
+- **Additional Requirements:** Review technical and UX requirements
+
+### 2. Explain Epic Design Principles
+
+**EPIC DESIGN PRINCIPLES:**
+
+1. **User-Value First**: Each epic must enable users to accomplish something meaningful
+2. **Requirements Grouping**: Group related FRs that deliver cohesive user outcomes
+3. **Incremental Delivery**: Each epic should deliver value independently
+4. **Logical Flow**: Natural progression from user's perspective
+5. **🔗 Dependency-Free Within Epic**: Stories within an epic must NOT depend on future stories
+
+**⚠️ CRITICAL PRINCIPLE:**
+Organize by USER VALUE, not technical layers:
+
+**✅ CORRECT Epic Examples (Standalone & Enable Future Epics):**
+
+- Epic 1: User Authentication & Profiles (users can register, login, manage profiles) - **Standalone: Complete auth system**
+- Epic 2: Content Creation (users can create, edit, publish content) - **Standalone: Uses auth, creates content**
+- Epic 3: Social Interaction (users can follow, comment, like content) - **Standalone: Uses auth + content**
+- Epic 4: Search & Discovery (users can find content and other users) - **Standalone: Uses all previous**
+
+**❌ WRONG Epic Examples (Technical Layers or Dependencies):**
+
+- Epic 1: Database Setup (creates all tables upfront) - **No user value**
+- Epic 2: API Development (builds all endpoints) - **No user value**
+- Epic 3: Frontend Components (creates reusable components) - **No user value**
+- Epic 4: Deployment Pipeline (CI/CD setup) - **No user value**
+
+**🔗 DEPENDENCY RULES:**
+
+- Each epic must deliver COMPLETE functionality for its domain
+- Epic 2 must not require Epic 3 to function
+- Epic 3 can build upon Epic 1 & 2 but must stand alone
+
+### 3. Design Epic Structure Collaboratively
+
+**Step A: Identify User Value Themes**
+
+- Look for natural groupings in the FRs
+- Identify user journeys or workflows
+- Consider user types and their goals
+
+**Step B: Propose Epic Structure**
+For each proposed epic:
+
+1. **Epic Title**: User-centric, value-focused
+2. **User Outcome**: What users can accomplish after this epic
+3. **FR Coverage**: Which FR numbers this epic addresses
+4. **Implementation Notes**: Any technical or UX considerations
+
+**Step C: Create the epics_list**
+
+Format the epics_list as:
+
+```
+## Epic List
+
+### Epic 1: [Epic Title]
+[Epic goal statement - what users can accomplish]
+**FRs covered:** FR1, FR2, FR3, etc.
+
+### Epic 2: [Epic Title]
+[Epic goal statement - what users can accomplish]
+**FRs covered:** FR4, FR5, FR6, etc.
+
+[Continue for all epics]
+```
+
+### 4. Present Epic List for Review
+
+Display the complete epics_list to user with:
+
+- Total number of epics
+- FR coverage per epic
+- User value delivered by each epic
+- Any natural dependencies
+
+### 5. Create Requirements Coverage Map
+
+Create {{requirements_coverage_map}} showing how each FR maps to an epic:
+
+```
+### FR Coverage Map
+
+FR1: Epic 1 - [Brief description]
+FR2: Epic 1 - [Brief description]
+FR3: Epic 2 - [Brief description]
+...
+```
+
+This ensures no FRs are missed.
+
+### 6. Collaborative Refinement
+
+Ask user:
+
+- "Does this epic structure align with your product vision?"
+- "Are all user outcomes properly captured?"
+- "Should we adjust any epic groupings?"
+- "Are there natural dependencies we've missed?"
+
+### 7. Get Final Approval
+
+**CRITICAL:** Must get explicit user approval:
+"Do you approve this epic structure for proceeding to story creation?"
+
+If user wants changes:
+
+- Make the requested adjustments
+- Update the epics_list
+- Re-present for approval
+- Repeat until approval is received
+
+## CONTENT TO UPDATE IN DOCUMENT:
+
+After approval, update {planning_artifacts}/epics.md:
+
+1. Replace {{epics_list}} placeholder with the approved epic list
+2. Replace {{requirements_coverage_map}} with the coverage map
+3. Ensure all FRs are mapped to epics
+
+### 8. Present MENU OPTIONS
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Invoke the `bmad-advanced-elicitation` skill
+- IF P: Invoke the `bmad-party-mode` skill
+- IF C: Save approved epics_list to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-03-create-stories.md
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#8-present-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution completes, redisplay the menu
+- User can chat or ask questions - always respond when conversation ends, redisplay the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and the approved epics_list is saved to document, will you then read fully and follow: ./step-03-create-stories.md to begin story creation step.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Epics designed around user value
+- All FRs mapped to specific epics
+- epics_list created and formatted correctly
+- Requirements coverage map completed
+- User gives explicit approval for epic structure
+- Document updated with approved epics
+
+### ❌ SYSTEM FAILURE:
+
+- Epics organized by technical layers
+- Missing FRs in coverage map
+- No user approval obtained
+- epics_list not saved to document
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
diff --git a/.claude/skills/bmad-create-epics-and-stories/steps/step-03-create-stories.md b/.claude/skills/bmad-create-epics-and-stories/steps/step-03-create-stories.md
new file mode 100644
index 0000000..14caafe
--- /dev/null
+++ b/.claude/skills/bmad-create-epics-and-stories/steps/step-03-create-stories.md
@@ -0,0 +1,255 @@
+# Step 3: Generate Epics and Stories
+
+## STEP GOAL:
+
+To generate all epics with their stories based on the approved epics_list, following the template structure exactly.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Process epics sequentially
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring story creation and acceptance criteria expertise
+- ✅ User brings their implementation priorities and constraints
+
+### Step-Specific Rules:
+
+- 🎯 Generate stories for each epic following the template exactly
+- 🚫 FORBIDDEN to deviate from template structure
+- 💬 Each story must have clear acceptance criteria
+- 🚪 ENSURE each story is completable by a single dev agent
+- 🔗 **CRITICAL: Stories MUST NOT depend on future stories within the same epic**
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Generate stories collaboratively with user input
+- 💾 Append epics and stories to {planning_artifacts}/epics.md following template
+- 📖 Process epics one at a time in sequence
+- 🚫 FORBIDDEN to skip any epic or rush through stories
+
+## STORY GENERATION PROCESS:
+
+### 1. Load Approved Epic Structure
+
+Load {planning_artifacts}/epics.md and review:
+
+- Approved epics_list from Step 2
+- FR coverage map
+- All requirements (FRs, NFRs, additional, **UX Design requirements if present**)
+- Template structure at the end of the document
+
+**UX Design Integration**: If UX Design Requirements (UX-DRs) were extracted in Step 1, ensure they are visible during story creation. UX-DRs must be covered by stories — either within existing epics (e.g., accessibility fixes for a feature epic) or in a dedicated "Design System / UX Polish" epic.
+
+### 2. Explain Story Creation Approach
+
+**STORY CREATION GUIDELINES:**
+
+For each epic, create stories that:
+
+- Follow the exact template structure
+- Are sized for single dev agent completion
+- Have clear user value
+- Include specific acceptance criteria
+- Reference requirements being fulfilled
+
+**🚨 DATABASE/ENTITY CREATION PRINCIPLE:**
+Create tables/entities ONLY when needed by the story:
+
+- ❌ WRONG: Epic 1 Story 1 creates all 50 database tables
+- ✅ RIGHT: Each story creates/alters ONLY the tables it needs
+
+**🔗 STORY DEPENDENCY PRINCIPLE:**
+Stories must be independently completable in sequence:
+
+- ❌ WRONG: Story 1.2 requires Story 1.3 to be completed first
+- ✅ RIGHT: Each story can be completed based only on previous stories
+- ❌ WRONG: "Wait for Story 1.4 to be implemented before this works"
+- ✅ RIGHT: "This story works independently and enables future stories"
+
+**STORY FORMAT (from template):**
+
+```
+### Story {N}.{M}: {story_title}
+
+As a {user_type},
+I want {capability},
+So that {value_benefit}.
+
+**Acceptance Criteria:**
+
+**Given** {precondition}
+**When** {action}
+**Then** {expected_outcome}
+**And** {additional_criteria}
+```
+
+**✅ GOOD STORY EXAMPLES:**
+
+_Epic 1: User Authentication_
+
+- Story 1.1: User Registration with Email
+- Story 1.2: User Login with Password
+- Story 1.3: Password Reset via Email
+
+_Epic 2: Content Creation_
+
+- Story 2.1: Create New Blog Post
+- Story 2.2: Edit Existing Blog Post
+- Story 2.3: Publish Blog Post
+
+**❌ BAD STORY EXAMPLES:**
+
+- Story: "Set up database" (no user value)
+- Story: "Create all models" (too large, no user value)
+- Story: "Build authentication system" (too large)
+- Story: "Login UI (depends on Story 1.3 API endpoint)" (future dependency!)
+- Story: "Edit post (requires Story 1.4 to be implemented first)" (wrong order!)
+
+### 3. Process Epics Sequentially
+
+For each epic in the approved epics_list:
+
+#### A. Epic Overview
+
+Display:
+
+- Epic number and title
+- Epic goal statement
+- FRs covered by this epic
+- Any NFRs or additional requirements relevant
+- Any UX Design Requirements (UX-DRs) relevant to this epic
+
+#### B. Story Breakdown
+
+Work with user to break down the epic into stories:
+
+- Identify distinct user capabilities
+- Ensure logical flow within the epic
+- Size stories appropriately
+
+#### C. Generate Each Story
+
+For each story in the epic:
+
+1. **Story Title**: Clear, action-oriented
+2. **User Story**: Complete the As a/I want/So that format
+3. **Acceptance Criteria**: Write specific, testable criteria
+
+**AC Writing Guidelines:**
+
+- Use Given/When/Then format
+- Each AC should be independently testable
+- Include edge cases and error conditions
+- Reference specific requirements when applicable
+
+#### D. Collaborative Review
+
+After writing each story:
+
+- Present the story to user
+- Ask: "Does this story capture the requirement correctly?"
+- "Is the scope appropriate for a single dev session?"
+- "Are the acceptance criteria complete and testable?"
+
+#### E. Append to Document
+
+When story is approved:
+
+- Append it to {planning_artifacts}/epics.md following template structure
+- Use correct numbering (Epic N, Story M)
+- Maintain proper markdown formatting
+
+### 4. Epic Completion
+
+After all stories for an epic are complete:
+
+- Display epic summary
+- Show count of stories created
+- Verify all FRs for the epic are covered
+- Get user confirmation to proceed to next epic
+
+### 5. Repeat for All Epics
+
+Continue the process for each epic in the approved list, processing them in order (Epic 1, Epic 2, etc.).
+
+### 6. Final Document Completion
+
+After all epics and stories are generated:
+
+- Verify the document follows template structure exactly
+- Ensure all placeholders are replaced
+- Confirm all FRs are covered
+- **Confirm all UX Design Requirements (UX-DRs) are covered by at least one story** (if UX document was an input)
+- Check formatting consistency
+
+## TEMPLATE STRUCTURE COMPLIANCE:
+
+The final {planning_artifacts}/epics.md must follow this structure exactly:
+
+1. **Overview** section with project name
+2. **Requirements Inventory** with all three subsections populated
+3. **FR Coverage Map** showing requirement to epic mapping
+4. **Epic List** with approved epic structure
+5. **Epic sections** for each epic (N = 1, 2, 3...)
+   - Epic title and goal
+   - All stories for that epic (M = 1, 2, 3...)
+     - Story title and user story
+     - Acceptance Criteria using Given/When/Then format
+
+### 7. Present FINAL MENU OPTIONS
+
+After all epics and stories are complete:
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Invoke the `bmad-advanced-elicitation` skill
+- IF P: Invoke the `bmad-party-mode` skill
+- IF C: Save content to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-04-final-validation.md
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-final-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [all epics and stories saved to document following the template structure exactly], will you then read fully and follow: `./step-04-final-validation.md` to begin final validation phase.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All epics processed in sequence
+- Stories created for each epic
+- Template structure followed exactly
+- All FRs covered by stories
+- Stories appropriately sized
+- Acceptance criteria are specific and testable
+- Document is complete and ready for development
+
+### ❌ SYSTEM FAILURE:
+
+- Deviating from template structure
+- Missing epics or stories
+- Stories too large or unclear
+- Missing acceptance criteria
+- Not following proper formatting
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
diff --git a/.claude/skills/bmad-create-epics-and-stories/steps/step-04-final-validation.md b/.claude/skills/bmad-create-epics-and-stories/steps/step-04-final-validation.md
new file mode 100644
index 0000000..d115edc
--- /dev/null
+++ b/.claude/skills/bmad-create-epics-and-stories/steps/step-04-final-validation.md
@@ -0,0 +1,131 @@
+# Step 4: Final Validation
+
+## STEP GOAL:
+
+To validate complete coverage of all requirements and ensure stories are ready for development.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Process validation sequentially without skipping
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring validation expertise and quality assurance
+- ✅ User brings their implementation priorities and final review
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on validating complete requirements coverage
+- 🚫 FORBIDDEN to skip any validation checks
+- 💬 Validate FR coverage, story completeness, and dependencies
+- 🚪 ENSURE all stories are ready for development
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Validate every requirement has story coverage
+- 💾 Check story dependencies and flow
+- 📖 Verify architecture compliance
+- 🚫 FORBIDDEN to approve incomplete coverage
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete epic and story breakdown from previous steps
+- Focus: Final validation of requirements coverage and story readiness
+- Limits: Validation only, no new content creation
+- Dependencies: Completed story generation from Step 3
+
+## VALIDATION PROCESS:
+
+### 1. FR Coverage Validation
+
+Review the complete epic and story breakdown to ensure EVERY FR is covered:
+
+**CRITICAL CHECK:**
+
+- Go through each FR from the Requirements Inventory
+- Verify it appears in at least one story
+- Check that acceptance criteria fully address the FR
+- No FRs should be left uncovered
+
+### 2. Architecture Implementation Validation
+
+**Check for Starter Template Setup:**
+
+- Does Architecture document specify a starter template?
+- If YES: Epic 1 Story 1 must be "Set up initial project from starter template"
+- This includes cloning, installing dependencies, initial configuration
+
+**Database/Entity Creation Validation:**
+
+- Are database tables/entities created ONLY when needed by stories?
+- ❌ WRONG: Epic 1 creates all tables upfront
+- ✅ RIGHT: Tables created as part of the first story that needs them
+- Each story should create/modify ONLY what it needs
+
+### 3. Story Quality Validation
+
+**Each story must:**
+
+- Be completable by a single dev agent
+- Have clear acceptance criteria
+- Reference specific FRs it implements
+- Include necessary technical details
+- **Not have forward dependencies** (can only depend on PREVIOUS stories)
+- Be implementable without waiting for future stories
+
+### 4. Epic Structure Validation
+
+**Check that:**
+
+- Epics deliver user value, not technical milestones
+- Dependencies flow naturally
+- Foundation stories only setup what's needed
+- No big upfront technical work
+
+### 5. Dependency Validation (CRITICAL)
+
+**Epic Independence Check:**
+
+- Does each epic deliver COMPLETE functionality for its domain?
+- Can Epic 2 function without Epic 3 being implemented?
+- Can Epic 3 function standalone using Epic 1 & 2 outputs?
+- ❌ WRONG: Epic 2 requires Epic 3 features to work
+- ✅ RIGHT: Each epic is independently valuable
+
+**Within-Epic Story Dependency Check:**
+For each epic, review stories in order:
+
+- Can Story N.1 be completed without Stories N.2, N.3, etc.?
+- Can Story N.2 be completed using only Story N.1 output?
+- Can Story N.3 be completed using only Stories N.1 & N.2 outputs?
+- ❌ WRONG: "This story depends on a future story"
+- ❌ WRONG: Story references features not yet implemented
+- ✅ RIGHT: Each story builds only on previous stories
+
+### 6. Complete and Save
+
+If all validations pass:
+
+- Update any remaining placeholders in the document
+- Ensure proper formatting
+- Save the final epics.md
+
+**Present Final Menu:**
+**All validations complete!** [C] Complete Workflow
+
+HALT — wait for user input before proceeding.
+
+When C is selected, the workflow is complete and the epics.md is ready for development.
+
+Epics and Stories complete. Invoke the `bmad-help` skill.
+
+Upon Completion of task output: offer to answer any questions about the Epics and Stories.
diff --git a/.claude/skills/bmad-create-epics-and-stories/templates/epics-template.md b/.claude/skills/bmad-create-epics-and-stories/templates/epics-template.md
new file mode 100644
index 0000000..bf80c7f
--- /dev/null
+++ b/.claude/skills/bmad-create-epics-and-stories/templates/epics-template.md
@@ -0,0 +1,61 @@
+---
+stepsCompleted: []
+inputDocuments: []
+---
+
+# {{project_name}} - Epic Breakdown
+
+## Overview
+
+This document provides the complete epic and story breakdown for {{project_name}}, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.
+
+## Requirements Inventory
+
+### Functional Requirements
+
+{{fr_list}}
+
+### NonFunctional Requirements
+
+{{nfr_list}}
+
+### Additional Requirements
+
+{{additional_requirements}}
+
+### UX Design Requirements
+
+{{ux_design_requirements}}
+
+### FR Coverage Map
+
+{{requirements_coverage_map}}
+
+## Epic List
+
+{{epics_list}}
+
+<!-- Repeat for each epic in epics_list (N = 1, 2, 3...) -->
+
+## Epic {{N}}: {{epic_title_N}}
+
+{{epic_goal_N}}
+
+<!-- Repeat for each story (M = 1, 2, 3...) within epic N -->
+
+### Story {{N}}.{{M}}: {{story_title_N_M}}
+
+As a {{user_type}},
+I want {{capability}},
+So that {{value_benefit}}.
+
+**Acceptance Criteria:**
+
+<!-- for each AC on this story -->
+
+**Given** {{precondition}}
+**When** {{action}}
+**Then** {{expected_outcome}}
+**And** {{additional_criteria}}
+
+<!-- End story repeat -->
diff --git a/.claude/skills/bmad-create-epics-and-stories/workflow.md b/.claude/skills/bmad-create-epics-and-stories/workflow.md
new file mode 100644
index 0000000..510e273
--- /dev/null
+++ b/.claude/skills/bmad-create-epics-and-stories/workflow.md
@@ -0,0 +1,51 @@
+# Create Epics and Stories
+
+**Goal:** Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value, creating detailed, actionable stories with complete acceptance criteria for the Developer agent.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also a product strategist and technical specifications writer collaborating with a product owner. This is a partnership, not a client-vendor relationship. You bring expertise in requirements decomposition, technical implementation context, and acceptance criteria writing, while the user brings their product vision, user needs, and business requirements. Work together as equals.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time
+- **Just-In-Time Loading**: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+ 
+2. First Step EXECUTION
+
+Read fully and follow: `./steps/step-01-validate-prerequisites.md` to begin the workflow.
diff --git a/.claude/skills/bmad-create-prd/SKILL.md b/.claude/skills/bmad-create-prd/SKILL.md
new file mode 100644
index 0000000..54f7640
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-create-prd
+description: 'Create a PRD from scratch. Use when the user says "lets create a product requirements document" or "I want to create a new PRD"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-create-prd/data/domain-complexity.csv b/.claude/skills/bmad-create-prd/data/domain-complexity.csv
new file mode 100644
index 0000000..60a7b50
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/data/domain-complexity.csv
@@ -0,0 +1,15 @@
+domain,signals,complexity,key_concerns,required_knowledge,suggested_workflow,web_searches,special_sections
+healthcare,"medical,diagnostic,clinical,FDA,patient,treatment,HIPAA,therapy,pharma,drug",high,"FDA approval;Clinical validation;HIPAA compliance;Patient safety;Medical device classification;Liability","Regulatory pathways;Clinical trial design;Medical standards;Data privacy;Integration requirements","domain-research","FDA software medical device guidance {date};HIPAA compliance software requirements;Medical software standards {date};Clinical validation software","clinical_requirements;regulatory_pathway;validation_methodology;safety_measures"
+fintech,"payment,banking,trading,investment,crypto,wallet,transaction,KYC,AML,funds,fintech",high,"Regional compliance;Security standards;Audit requirements;Fraud prevention;Data protection","KYC/AML requirements;PCI DSS;Open banking;Regional laws (US/EU/APAC);Crypto regulations","domain-research","fintech regulations {date};payment processing compliance {date};open banking API standards;cryptocurrency regulations {date}","compliance_matrix;security_architecture;audit_requirements;fraud_prevention"
+govtech,"government,federal,civic,public sector,citizen,municipal,voting",high,"Procurement rules;Security clearance;Accessibility (508);FedRAMP;Privacy;Transparency","Government procurement;Security frameworks;Accessibility standards;Privacy laws;Open data requirements","domain-research","government software procurement {date};FedRAMP compliance requirements;section 508 accessibility;government security standards","procurement_compliance;security_clearance;accessibility_standards;transparency_requirements"
+edtech,"education,learning,student,teacher,curriculum,assessment,K-12,university,LMS",medium,"Student privacy (COPPA/FERPA);Accessibility;Content moderation;Age verification;Curriculum standards","Educational privacy laws;Learning standards;Accessibility requirements;Content guidelines;Assessment validity","domain-research","educational software privacy {date};COPPA FERPA compliance;WCAG education requirements;learning management standards","privacy_compliance;content_guidelines;accessibility_features;curriculum_alignment"
+aerospace,"aircraft,spacecraft,aviation,drone,satellite,propulsion,flight,radar,navigation",high,"Safety certification;DO-178C compliance;Performance validation;Simulation accuracy;Export controls","Aviation standards;Safety analysis;Simulation validation;ITAR/export controls;Performance requirements","domain-research + technical-model","DO-178C software certification;aerospace simulation standards {date};ITAR export controls software;aviation safety requirements","safety_certification;simulation_validation;performance_requirements;export_compliance"
+automotive,"vehicle,car,autonomous,ADAS,automotive,driving,EV,charging",high,"Safety standards;ISO 26262;V2X communication;Real-time requirements;Certification","Automotive standards;Functional safety;V2X protocols;Real-time systems;Testing requirements","domain-research","ISO 26262 automotive software;automotive safety standards {date};V2X communication protocols;EV charging standards","safety_standards;functional_safety;communication_protocols;certification_requirements"
+scientific,"research,algorithm,simulation,modeling,computational,analysis,data science,ML,AI",medium,"Reproducibility;Validation methodology;Peer review;Performance;Accuracy;Computational resources","Scientific method;Statistical validity;Computational requirements;Domain expertise;Publication standards","technical-model","scientific computing best practices {date};research reproducibility standards;computational modeling validation;peer review software","validation_methodology;accuracy_metrics;reproducibility_plan;computational_requirements"
+legaltech,"legal,law,contract,compliance,litigation,patent,attorney,court",high,"Legal ethics;Bar regulations;Data retention;Attorney-client privilege;Court system integration","Legal practice rules;Ethics requirements;Court filing systems;Document standards;Confidentiality","domain-research","legal technology ethics {date};law practice management software requirements;court filing system standards;attorney client privilege technology","ethics_compliance;data_retention;confidentiality_measures;court_integration"
+insuretech,"insurance,claims,underwriting,actuarial,policy,risk,premium",high,"Insurance regulations;Actuarial standards;Data privacy;Fraud detection;State compliance","Insurance regulations by state;Actuarial methods;Risk modeling;Claims processing;Regulatory reporting","domain-research","insurance software regulations {date};actuarial standards software;insurance fraud detection;state insurance compliance","regulatory_requirements;risk_modeling;fraud_detection;reporting_compliance"
+energy,"energy,utility,grid,solar,wind,power,electricity,oil,gas",high,"Grid compliance;NERC standards;Environmental regulations;Safety requirements;Real-time operations","Energy regulations;Grid standards;Environmental compliance;Safety protocols;SCADA systems","domain-research","energy sector software compliance {date};NERC CIP standards;smart grid requirements;renewable energy software standards","grid_compliance;safety_protocols;environmental_compliance;operational_requirements"
+process_control,"industrial automation,process control,PLC,SCADA,DCS,HMI,operational technology,OT,control system,cyberphysical,MES,historian,instrumentation,I&C,P&ID",high,"Functional safety;OT cybersecurity;Real-time control requirements;Legacy system integration;Process safety and hazard analysis;Environmental compliance and permitting;Engineering authority and PE requirements","Functional safety standards;OT security frameworks;Industrial protocols;Process control architecture;Plant reliability and maintainability","domain-research + technical-model","IEC 62443 OT cybersecurity requirements {date};functional safety software requirements {date};industrial process control architecture;ISA-95 manufacturing integration","functional_safety;ot_security;process_requirements;engineering_authority"
+building_automation,"building automation,BAS,BMS,HVAC,smart building,lighting control,fire alarm,fire protection,fire suppression,life safety,elevator,access control,DDC,energy management,sequence of operations,commissioning",high,"Life safety codes;Building energy standards;Multi-trade coordination and interoperability;Commissioning and ongoing operational performance;Indoor environmental quality and occupant comfort;Engineering authority and PE requirements","Building automation protocols;HVAC and mechanical controls;Fire alarm, fire protection, and life safety design;Commissioning process and sequence of operations;Building codes and energy standards","domain-research","smart building software architecture {date};BACnet integration best practices;building automation cybersecurity {date};ASHRAE building standards","life_safety;energy_compliance;commissioning_requirements;engineering_authority"
+gaming,"game,player,gameplay,level,character,multiplayer,quest",redirect,"REDIRECT TO GAME WORKFLOWS","Game design","game-brief","NA","NA"
+general,"",low,"Standard requirements;Basic security;User experience;Performance","General software practices","continue","software development best practices {date}","standard_requirements"
\ No newline at end of file
diff --git a/.claude/skills/bmad-create-prd/data/prd-purpose.md b/.claude/skills/bmad-create-prd/data/prd-purpose.md
new file mode 100644
index 0000000..755230b
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/data/prd-purpose.md
@@ -0,0 +1,197 @@
+# BMAD PRD Purpose
+
+**The PRD is the top of the required funnel that feeds all subsequent product development work in rhw BMad Method.**
+
+---
+
+## What is a BMAD PRD?
+
+A dual-audience document serving:
+1. **Human Product Managers and builders** - Vision, strategy, stakeholder communication
+2. **LLM Downstream Consumption** - UX Design → Architecture → Epics → Development AI Agents
+
+Each successive document becomes more AI-tailored and granular.
+
+---
+
+## Core Philosophy: Information Density
+
+**High Signal-to-Noise Ratio**
+
+Every sentence must carry information weight. LLMs consume precise, dense content efficiently.
+
+**Anti-Patterns (Eliminate These):**
+- ❌ "The system will allow users to..." → ✅ "Users can..."
+- ❌ "It is important to note that..." → ✅ State the fact directly
+- ❌ "In order to..." → ✅ "To..."
+- ❌ Conversational filler and padding → ✅ Direct, concise statements
+
+**Goal:** Maximum information per word. Zero fluff.
+
+---
+
+## The Traceability Chain
+
+**PRD starts the chain:**
+```
+Vision → Success Criteria → User Journeys → Functional Requirements → (future: User Stories)
+```
+
+**In the PRD, establish:**
+- Vision → Success Criteria alignment
+- Success Criteria → User Journey coverage
+- User Journey → Functional Requirement mapping
+- All requirements traceable to user needs
+
+**Why:** Each downstream artifact (UX, Architecture, Epics, Stories) must trace back to documented user needs and business objectives. This chain ensures we build the right thing.
+
+---
+
+## What Makes Great Functional Requirements?
+
+### FRs are Capabilities, Not Implementation
+
+**Good FR:** "Users can reset their password via email link"
+**Bad FR:** "System sends JWT via email and validates with database" (implementation leakage)
+
+**Good FR:** "Dashboard loads in under 2 seconds for 95th percentile"
+**Bad FR:** "Fast loading time" (subjective, unmeasurable)
+
+### SMART Quality Criteria
+
+**Specific:** Clear, precisely defined capability
+**Measurable:** Quantifiable with test criteria
+**Attainable:** Realistic within constraints
+**Relevant:** Aligns with business objectives
+**Traceable:** Links to source (executive summary or user journey)
+
+### FR Anti-Patterns
+
+**Subjective Adjectives:**
+- ❌ "easy to use", "intuitive", "user-friendly", "fast", "responsive"
+- ✅ Use metrics: "completes task in under 3 clicks", "loads in under 2 seconds"
+
+**Implementation Leakage:**
+- ❌ Technology names, specific libraries, implementation details
+- ✅ Focus on capability and measurable outcomes
+
+**Vague Quantifiers:**
+- ❌ "multiple users", "several options", "various formats"
+- ✅ "up to 100 concurrent users", "3-5 options", "PDF, DOCX, TXT formats"
+
+**Missing Test Criteria:**
+- ❌ "The system shall provide notifications"
+- ✅ "The system shall send email notifications within 30 seconds of trigger event"
+
+---
+
+## What Makes Great Non-Functional Requirements?
+
+### NFRs Must Be Measurable
+
+**Template:**
+```
+"The system shall [metric] [condition] [measurement method]"
+```
+
+**Examples:**
+- ✅ "The system shall respond to API requests in under 200ms for 95th percentile as measured by APM monitoring"
+- ✅ "The system shall maintain 99.9% uptime during business hours as measured by cloud provider SLA"
+- ✅ "The system shall support 10,000 concurrent users as measured by load testing"
+
+### NFR Anti-Patterns
+
+**Unmeasurable Claims:**
+- ❌ "The system shall be scalable" → ✅ "The system shall handle 10x load growth through horizontal scaling"
+- ❌ "High availability required" → ✅ "99.9% uptime as measured by cloud provider SLA"
+
+**Missing Context:**
+- ❌ "Response time under 1 second" → ✅ "API response time under 1 second for 95th percentile under normal load"
+
+---
+
+## Domain-Specific Requirements
+
+**Auto-Detect and Enforce Based on Project Context**
+
+Certain industries have mandatory requirements that must be present:
+
+- **Healthcare:** HIPAA Privacy & Security Rules, PHI encryption, audit logging, MFA
+- **Fintech:** PCI-DSS Level 1, AML/KYC compliance, SOX controls, financial audit trails
+- **GovTech:** NIST framework, Section 508 accessibility (WCAG 2.1 AA), FedRAMP, data residency
+- **E-Commerce:** PCI-DSS for payments, inventory accuracy, tax calculation by jurisdiction
+
+**Why:** Missing these requirements in the PRD means they'll be missed in architecture and implementation, creating expensive rework. During PRD creation there is a step to cover this - during validation we want to make sure it was covered. For this purpose steps will utilize a domain-complexity.csv and project-types.csv.
+
+---
+
+## Document Structure (Markdown, Human-Readable)
+
+### Required Sections
+1. **Executive Summary** - Vision, differentiator, target users
+2. **Success Criteria** - Measurable outcomes (SMART)
+3. **Product Scope** - MVP, Growth, Vision phases
+4. **User Journeys** - Comprehensive coverage
+5. **Domain Requirements** - Industry-specific compliance (if applicable)
+6. **Innovation Analysis** - Competitive differentiation (if applicable)
+7. **Project-Type Requirements** - Platform-specific needs
+8. **Functional Requirements** - Capability contract (FRs)
+9. **Non-Functional Requirements** - Quality attributes (NFRs)
+
+### Formatting for Dual Consumption
+
+**For Humans:**
+- Clear, professional language
+- Logical flow from vision to requirements
+- Easy for stakeholders to review and approve
+
+**For LLMs:**
+- ## Level 2 headers for all main sections (enables extraction)
+- Consistent structure and patterns
+- Precise, testable language
+- High information density
+
+---
+
+## Downstream Impact
+
+**How the PRD Feeds Next Artifacts:**
+
+**UX Design:**
+- User journeys → interaction flows
+- FRs → design requirements
+- Success criteria → UX metrics
+
+**Architecture:**
+- FRs → system capabilities
+- NFRs → architecture decisions
+- Domain requirements → compliance architecture
+- Project-type requirements → platform choices
+
+**Epics & Stories (created after architecture):**
+- FRs → user stories (1 FR could map to 1-3 stories potentially)
+- Acceptance criteria → story acceptance tests
+- Priority → sprint sequencing
+- Traceability → stories map back to vision
+
+**Development AI Agents:**
+- Precise requirements → implementation clarity
+- Test criteria → automated test generation
+- Domain requirements → compliance enforcement
+- Measurable NFRs → performance targets
+
+---
+
+## Summary: What Makes a Great BMAD PRD?
+
+✅ **High Information Density** - Every sentence carries weight, zero fluff
+✅ **Measurable Requirements** - All FRs and NFRs are testable with specific criteria
+✅ **Clear Traceability** - Each requirement links to user need and business objective
+✅ **Domain Awareness** - Industry-specific requirements auto-detected and included
+✅ **Zero Anti-Patterns** - No subjective adjectives, implementation leakage, or vague quantifiers
+✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable
+✅ **Markdown Format** - Professional, clean, accessible to all stakeholders
+
+---
+
+**Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective.
diff --git a/.claude/skills/bmad-create-prd/data/project-types.csv b/.claude/skills/bmad-create-prd/data/project-types.csv
new file mode 100644
index 0000000..6f71c51
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/data/project-types.csv
@@ -0,0 +1,11 @@
+project_type,detection_signals,key_questions,required_sections,skip_sections,web_search_triggers,innovation_signals
+api_backend,"API,REST,GraphQL,backend,service,endpoints","Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?","endpoint_specs;auth_model;data_schemas;error_codes;rate_limits;api_docs","ux_ui;visual_design;user_journeys","framework best practices;OpenAPI standards","API composition;New protocol"
+mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features"
+saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents"
+developer_tool,"SDK,library,package,npm,pip,framework","Language support?;Package managers?;IDE integration?;Documentation?;Examples?","language_matrix;installation_methods;api_surface;code_examples;migration_guide","visual_design;store_compliance","package manager best practices;API design patterns","New paradigm;DSL creation"
+cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands"
+web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO needed?;Real-time?;Accessibility?","browser_matrix;responsive_design;performance_targets;seo_strategy;accessibility_level","native_features;cli_commands","web standards;WCAG guidelines","New interaction;WebAssembly use"
+game,"game,player,gameplay,level,character","REDIRECT TO USE THE BMad Method Game Module Agent and Workflows - HALT","game-brief;GDD","most_sections","game design patterns","Novel mechanics;Genre mixing"
+desktop_app,"desktop,Windows,Mac,Linux,native","Cross-platform?;Auto-update?;System integration?;Offline?","platform_support;system_integration;update_strategy;offline_capabilities","web_seo;mobile_features","desktop guidelines;platform requirements","Desktop AI;System automation"
+iot_embedded,"IoT,embedded,device,sensor,hardware","Hardware specs?;Connectivity?;Power constraints?;Security?;OTA updates?","hardware_reqs;connectivity_protocol;power_profile;security_model;update_mechanism","visual_ui;browser_support","IoT standards;protocol specs","Edge AI;New sensors"
+blockchain_web3,"blockchain,crypto,DeFi,NFT,smart contract","Chain selection?;Wallet integration?;Gas optimization?;Security audit?","chain_specs;wallet_support;smart_contracts;security_audit;gas_optimization","traditional_auth;centralized_db","blockchain standards;security patterns","Novel tokenomics;DAO structure"
\ No newline at end of file
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-01-init.md b/.claude/skills/bmad-create-prd/steps-c/step-01-init.md
new file mode 100644
index 0000000..8268e6a
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-01-init.md
@@ -0,0 +1,178 @@
+# Step 1: Workflow Initialization
+
+**Progress: Step 1 of 11** - Next: Project Discovery
+
+## STEP GOAL:
+
+Initialize the PRD workflow by detecting continuation state, discovering input documents, and setting up the document structure for collaborative product requirement discovery.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on initialization and setup - no content generation yet
+- 🚫 FORBIDDEN to look ahead to future steps or assume knowledge from them
+- 💬 Approach: Systematic setup with clear reporting to user
+- 🚪 Detect existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking any action
+- 💾 Initialize document structure and update frontmatter appropriately
+- Update frontmatter: add this step name to the end of the steps completed array (it should be the first entry in the steps array since this is step 1)
+- 🚫 FORBIDDEN to load next step until user selects 'C' (Continue)
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Variables from workflow.md are available in memory
+- Focus: Workflow initialization and document setup only
+- Limits: Don't assume knowledge from other steps or create content yet
+- Dependencies: Configuration loaded from workflow.md initialization
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Check for Existing Workflow State
+
+First, check if the output document already exists:
+
+**Workflow State Detection:**
+
+- Look for file at `{outputFile}`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted` BUT `step-12-complete` is NOT in the list, follow the Continuation Protocol since the document is incomplete:
+
+**Continuation Protocol:**
+
+- **STOP immediately** and load `./step-01b-continue.md`
+- Do not proceed with any initialization tasks
+- Let step-01b handle all continuation logic
+- This is an auto-proceed situation - no user choice needed
+
+### 3. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+Discover and load context documents using smart discovery. Documents can be in the following locations:
+- {planning_artifacts}/**
+- {output_folder}/**
+- {project_knowledge}/**
+- docs/**
+
+Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content)
+
+Try to discover the following:
+- Product Brief (`*brief*.md`)
+- Research Documents (`/*research*.md`)
+- Project Documentation (generally multiple documents might be found for this in the `{project_knowledge}` or `docs` folder.)
+- Project Context (`**/project-context.md`)
+
+<critical>Confirm what you have found with the user, along with asking if the user wants to provide anything else. Only after this confirmation will you proceed to follow the loading rules</critical>
+
+**Loading Rules:**
+
+- Load ALL discovered files completely that the user confirmed or provided (no offset/limit)
+- If there is a project context, whatever is relevant should try to be biased in the remainder of this whole workflow process
+- For sharded folders, load ALL files to get complete picture, using the index first to potentially know the potential of each document
+- index.md is a guide to what's relevant whenever available
+- Track all successfully loaded files in frontmatter `inputDocuments` array
+
+#### B. Create Initial Document
+
+**Document Setup:**
+
+- Copy the template from `../templates/prd-template.md` to `{outputFile}`
+- Initialize frontmatter with proper structure including inputDocuments array.
+
+#### C. Present Initialization Results
+
+**Setup Report to User:**
+
+"Welcome {{user_name}}! I've set up your PRD workspace for {{project_name}}.
+
+**Document Setup:**
+
+- Created: `{outputFile}` from template
+- Initialized frontmatter with workflow state
+
+**Input Documents Discovered:**
+
+- Product briefs: {{briefCount}} files {if briefCount > 0}✓ loaded{else}(none found){/if}
+- Research: {{researchCount}} files {if researchCount > 0}✓ loaded{else}(none found){/if}
+- Brainstorming: {{brainstormingCount}} files {if brainstormingCount > 0}✓ loaded{else}(none found){/if}
+- Project docs: {{projectDocsCount}} files {if projectDocsCount > 0}✓ loaded (brownfield project){else}(none found - greenfield project){/if}
+
+**Files loaded:** {list of specific file names or "No additional documents found"}
+
+{if projectDocsCount > 0}
+📋 **Note:** This is a **brownfield project**. Your existing project documentation has been loaded. In the next step, I'll ask specifically about what new features or changes you want to add to your existing system.
+{/if}
+
+Do you have any other documents you'd like me to include, or shall we continue to the next step?"
+
+### 4. Present MENU OPTIONS
+
+Display menu after setup report:
+
+"[C] Continue - Save this and move to Project Discovery (Step 2 of 11)"
+
+#### Menu Handling Logic:
+
+- IF C: Update output file frontmatter, adding this step name to the end of the list of stepsCompleted, then read fully and follow: ./step-02-discovery.md
+- IF user provides additional files: Load them, update inputDocuments and documentCounts, redisplay report
+- IF user asks questions: Answer and redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [frontmatter properly updated with this step added to stepsCompleted and documentCounts], will you then read fully and follow: `./step-02-discovery.md` to begin project discovery.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Existing workflow detected and properly handed off to step-01b
+- Fresh workflow initialized with template and proper frontmatter
+- Input documents discovered and loaded using sharded-first logic
+- All discovered files tracked in frontmatter `inputDocuments`
+- User clearly informed of brownfield vs greenfield status
+- Menu presented and user input handled correctly
+- Frontmatter updated with this step name added to stepsCompleted before proceeding
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with fresh initialization when existing workflow exists
+- Not updating frontmatter with discovered input documents
+- **Not storing document counts in frontmatter**
+- Creating document without proper template structure
+- Not checking sharded folders first before whole files
+- Not reporting discovered documents to user clearly
+- Proceeding without user selecting 'C' (Continue)
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-01b-continue.md b/.claude/skills/bmad-create-prd/steps-c/step-01b-continue.md
new file mode 100644
index 0000000..4351cc1
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-01b-continue.md
@@ -0,0 +1,161 @@
+# Step 1B: Workflow Continuation
+
+## STEP GOAL:
+
+Resume the PRD workflow from where it was left off, ensuring smooth continuation with full context restoration.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ Resume workflow from exact point where it was interrupted
+
+### Step-Specific Rules:
+
+- 💬 FOCUS on understanding where we left off and continuing appropriately
+- 🚫 FORBIDDEN to modify content completed in previous steps
+- 📖 Only reload documents that were already tracked in `inputDocuments`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking action
+- Update frontmatter: add this step name to the end of the steps completed array
+- 📖 Only load documents that were already tracked in `inputDocuments`
+- 🚫 FORBIDDEN to discover new input documents during continuation
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Current document and frontmatter are already loaded
+- Focus: Workflow state analysis and continuation logic only
+- Limits: Don't assume knowledge beyond what's in the document
+- Dependencies: Existing workflow state from previous session
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Analyze Current State
+
+**State Assessment:**
+Review the frontmatter to understand:
+
+- `stepsCompleted`: Array of completed step filenames
+- Last element of `stepsCompleted` array: The most recently completed step
+- `inputDocuments`: What context was already loaded
+- All other frontmatter variables
+
+### 2. Restore Context Documents
+
+**Context Reloading:**
+
+- For each document in `inputDocuments`, load the complete file
+- This ensures you have full context for continuation
+- Don't discover new documents - only reload what was previously processed
+
+### 3. Determine Next Step
+
+**Step Sequence Lookup:**
+
+Use the following ordered sequence to determine the next step from the last completed step:
+
+| Last Completed | Next Step |
+|---|---|
+| step-01-init.md | step-02-discovery.md |
+| step-02-discovery.md | step-02b-vision.md |
+| step-02b-vision.md | step-02c-executive-summary.md |
+| step-02c-executive-summary.md | step-03-success.md |
+| step-03-success.md | step-04-journeys.md |
+| step-04-journeys.md | step-05-domain.md |
+| step-05-domain.md | step-06-innovation.md |
+| step-06-innovation.md | step-07-project-type.md |
+| step-07-project-type.md | step-08-scoping.md |
+| step-08-scoping.md | step-09-functional.md |
+| step-09-functional.md | step-10-nonfunctional.md |
+| step-10-nonfunctional.md | step-11-polish.md |
+| step-11-polish.md | step-12-complete.md |
+
+1. Get the last element from the `stepsCompleted` array
+2. Look it up in the table above to find the next step
+3. That's the next step to load!
+
+**Example:**
+- If `stepsCompleted = ["step-01-init.md", "step-02-discovery.md", "step-03-success.md"]`
+- Last element is `"step-03-success.md"`
+- Table lookup → next step is `./step-04-journeys.md`
+
+### 4. Handle Workflow Completion
+
+**If `stepsCompleted` array contains `"step-12-complete.md"`:**
+"Great news! It looks like we've already completed the PRD workflow for {{project_name}}.
+
+The final document is ready at `{outputFile}` with all sections completed.
+
+Would you like me to:
+
+- Review the completed PRD with you
+- Suggest next workflow steps (like architecture or epic creation)
+- Start a new PRD revision
+
+What would be most helpful?"
+
+### 5. Present Current Progress
+
+**If workflow not complete:**
+"Welcome back {{user_name}}! I'm resuming our PRD collaboration for {{project_name}}.
+
+**Current Progress:**
+- Last completed: {last step filename from stepsCompleted array}
+- Next up: {next step from lookup table}
+- Context documents available: {len(inputDocuments)} files
+
+**Document Status:**
+- Current PRD document is ready with all completed sections
+- Ready to continue from where we left off
+
+Does this look right, or do you want to make any adjustments before we proceed?"
+
+### 6. Present MENU OPTIONS
+
+Display: "**Select an Option:** [C] Continue to {next step name}"
+
+#### Menu Handling Logic:
+
+- IF C: Read fully and follow the next step determined from the lookup table in step 3
+- IF Any other comments or queries: respond and redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [current state confirmed], will you then read fully and follow the next step (from the lookup table) to resume the workflow.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All previous input documents successfully reloaded
+- Current workflow state accurately analyzed and presented
+- User confirms understanding of progress before continuation
+- Correct next step identified and prepared for loading
+
+### ❌ SYSTEM FAILURE:
+
+- Discovering new input documents instead of reloading existing ones
+- Modifying content from already completed steps
+- Failing to determine the next step from the lookup table
+- Proceeding without user confirmation of current state
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-02-discovery.md b/.claude/skills/bmad-create-prd/steps-c/step-02-discovery.md
new file mode 100644
index 0000000..3eeb524
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-02-discovery.md
@@ -0,0 +1,208 @@
+# Step 2: Project Discovery
+
+**Progress: Step 2 of 13** - Next: Product Vision
+
+## STEP GOAL:
+
+Discover and classify the project - understand what type of product this is, what domain it operates in, and the project context (greenfield vs brownfield).
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision
+
+### Step-Specific Rules:
+
+- 🎯 Focus on classification and understanding - no content generation yet
+- 🚫 FORBIDDEN to generate executive summary or vision statements (that's next steps)
+- 💬 APPROACH: Natural conversation to understand the project
+- 🎯 LOAD classification data BEFORE starting discovery conversation
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after classification complete
+- 💾 ONLY save classification to frontmatter when user chooses C (Continue)
+- 📖 Update frontmatter, adding this step to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from step 1 are available
+- Input documents already loaded are in memory (product briefs, research, brainstorming, project docs)
+- **Document counts available in frontmatter `documentCounts`**
+- Classification CSV data will be loaded in this step only
+- No executive summary or vision content yet (that's steps 2b and 2c)
+
+## YOUR TASK:
+
+Discover and classify the project through natural conversation:
+- What type of product is this? (web app, API, mobile, etc.)
+- What domain does it operate in? (healthcare, fintech, e-commerce, etc.)
+- What's the project context? (greenfield new product vs brownfield existing system)
+- How complex is this domain? (low, medium, high)
+
+## DISCOVERY SEQUENCE:
+
+### 1. Check Document State
+
+Read the frontmatter from `{outputFile}` to get document counts:
+- `briefCount` - Product briefs available
+- `researchCount` - Research documents available
+- `brainstormingCount` - Brainstorming docs available
+- `projectDocsCount` - Existing project documentation
+
+**Announce your understanding:**
+
+"From step 1, I have loaded:
+- Product briefs: {{briefCount}}
+- Research: {{researchCount}}
+- Brainstorming: {{brainstormingCount}}
+- Project docs: {{projectDocsCount}}
+
+{{if projectDocsCount > 0}}This is a brownfield project - I'll focus on understanding what you want to add or change.{{else}}This is a greenfield project - I'll help you define the full product vision.{{/if}}"
+
+### 2. Load Classification Data
+
+**Attempt subprocess data lookup:**
+
+**Project Type Lookup:**
+"Your task: Lookup data in ../data/project-types.csv
+
+**Search criteria:**
+- Find row where project_type matches {{detectedProjectType}}
+
+**Return format:**
+Return ONLY the matching row as a YAML-formatted object with these fields:
+project_type, detection_signals
+
+**Do NOT return the entire CSV - only the matching row.**"
+
+**Domain Complexity Lookup:**
+"Your task: Lookup data in ../data/domain-complexity.csv
+
+**Search criteria:**
+- Find row where domain matches {{detectedDomain}}
+
+**Return format:**
+Return ONLY the matching row as a YAML-formatted object with these fields:
+domain, complexity, typical_concerns, compliance_requirements
+
+**Do NOT return the entire CSV - only the matching row.**"
+
+**Graceful degradation (if Task tool unavailable):**
+- Load the CSV files directly
+- Find the matching rows manually
+- Extract required fields
+- Keep in memory for intelligent classification
+
+### 3. Begin Discovery Conversation
+
+**Start with what you know:**
+
+If the user has a product brief or project docs, acknowledge them and share your understanding. Then ask clarifying questions to deepen your understanding.
+
+If this is a greenfield project with no docs, start with open-ended discovery:
+- What problem does this solve?
+- Who's it for?
+- What excites you about building this?
+
+**Listen for classification signals:**
+
+As the user describes their product, match against:
+- **Project type signals** (API, mobile, SaaS, etc.)
+- **Domain signals** (healthcare, fintech, education, etc.)
+- **Complexity indicators** (regulated industries, novel technology, etc.)
+
+### 4. Confirm Classification
+
+Once you have enough understanding, share your classification:
+
+"I'm hearing this as:
+- **Project Type:** {{detectedType}}
+- **Domain:** {{detectedDomain}}
+- **Complexity:** {{complexityLevel}}
+
+Does this sound right to you?"
+
+Let the user confirm or refine your classification.
+
+### 5. Save Classification to Frontmatter
+
+When user selects 'C', update frontmatter with classification:
+```yaml
+classification:
+  projectType: {{projectType}}
+  domain: {{domain}}
+  complexity: {{complexityLevel}}
+  projectContext: {{greenfield|brownfield}}
+```
+
+### N. Present MENU OPTIONS
+
+Present the project classification for review, then display menu:
+
+"Based on our conversation, I've discovered and classified your project.
+
+**Here's the classification:**
+
+**Project Type:** {{detectedType}}
+**Domain:** {{detectedDomain}}
+**Complexity:** {{complexityLevel}}
+**Project Context:** {{greenfield|brownfield}}
+
+**What would you like to do?**"
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Product Vision (Step 2b of 13)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the current classification, process the enhanced insights that come back, ask user if they accept the improvements, if yes update classification then redisplay menu, if no keep original classification then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the current classification, process the collaborative insights, ask user if they accept the changes, if yes update classification then redisplay menu, if no keep original classification then redisplay menu
+- IF C: Save classification to {outputFile} frontmatter, add this step name to the end of stepsCompleted array, then read fully and follow: ./step-02b-vision.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [classification saved to frontmatter], will you then read fully and follow: `./step-02b-vision.md` to explore product vision.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Document state checked and announced to user
+- Classification data loaded and used intelligently
+- Natural conversation to understand project type, domain, complexity
+- Classification validated with user before saving
+- Frontmatter updated with classification when C selected
+- User's existing documents acknowledged and built upon
+
+### ❌ SYSTEM FAILURE:
+
+- Not reading documentCounts from frontmatter first
+- Skipping classification data loading
+- Generating executive summary or vision content (that's later steps!)
+- Not validating classification with user
+- Being prescriptive instead of having natural conversation
+- Proceeding without user selecting 'C'
+
+**Master Rule:** This is classification and understanding only. No content generation yet. Build on what the user already has. Have natural conversations, don't follow scripts.
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-02b-vision.md b/.claude/skills/bmad-create-prd/steps-c/step-02b-vision.md
new file mode 100644
index 0000000..37f91e6
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-02b-vision.md
@@ -0,0 +1,142 @@
+# Step 2b: Product Vision Discovery
+
+**Progress: Step 2b of 13** - Next: Executive Summary
+
+## STEP GOAL:
+
+Discover what makes this product special and understand the product vision through collaborative conversation. No content generation — facilitation only.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision
+
+### Step-Specific Rules:
+
+- 🎯 Focus on discovering vision and differentiator — no content generation yet
+- 🚫 FORBIDDEN to generate executive summary content (that's the next step)
+- 🚫 FORBIDDEN to append anything to the document in this step
+- 💬 APPROACH: Natural conversation to understand what makes this product special
+- 🎯 BUILD ON classification insights from step 2
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after vision discovery is complete
+- 📖 Update frontmatter, adding this step to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from steps 1 and 2 are available
+- Project classification exists from step 2 (project type, domain, complexity, context)
+- Input documents already loaded are in memory (product briefs, research, brainstorming, project docs)
+- No executive summary content yet (that's step 2c)
+- This step ONLY discovers — it does NOT write to the document
+
+## YOUR TASK:
+
+Discover the product vision and differentiator through natural conversation. Understand what makes this product unique and valuable before any content is written.
+
+## VISION DISCOVERY SEQUENCE:
+
+### 1. Acknowledge Classification Context
+
+Reference the classification from step 2 and use it to frame the vision conversation:
+
+"We've established this is a {{projectType}} in the {{domain}} domain with {{complexityLevel}} complexity. Now let's explore what makes this product special."
+
+### 2. Explore What Makes It Special
+
+Guide the conversation to uncover the product's unique value:
+
+- **User delight:** "What would make users say 'this is exactly what I needed'?"
+- **Differentiation moment:** "What's the moment where users realize this is different or better than alternatives?"
+- **Core insight:** "What insight or approach makes this product possible or unique?"
+- **Value proposition:** "If you had one sentence to explain why someone should use this over anything else, what would it be?"
+
+### 3. Understand the Vision
+
+Dig deeper into the product vision:
+
+- **Problem framing:** "What's the real problem you're solving — not the surface symptom, but the deeper need?"
+- **Future state:** "When this product is successful, what does the world look like for your users?"
+- **Why now:** "Why is this the right time to build this?"
+
+### 4. Validate Understanding
+
+Reflect back what you've heard and confirm:
+
+"Here's what I'm hearing about your vision and differentiator:
+
+**Vision:** {{summarized_vision}}
+**What Makes It Special:** {{summarized_differentiator}}
+**Core Insight:** {{summarized_insight}}
+
+Does this capture it? Anything I'm missing?"
+
+Let the user confirm or refine your understanding.
+
+### N. Present MENU OPTIONS
+
+Present your understanding of the product vision for review, then display menu:
+
+"Based on our conversation, I have a clear picture of your product vision and what makes it special. I'll use these insights to draft the Executive Summary in the next step.
+
+**What would you like to do?**"
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Executive Summary (Step 2c of 13)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the current vision insights, process the enhanced insights that come back, ask user if they accept the improvements, if yes update understanding then redisplay menu, if no keep original understanding then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the current vision insights, process the collaborative insights, ask user if they accept the changes, if yes update understanding then redisplay menu, if no keep original understanding then redisplay menu
+- IF C: Update {outputFile} frontmatter by adding this step name to the end of stepsCompleted array, then read fully and follow: ./step-02c-executive-summary.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [stepsCompleted updated], will you then read fully and follow: `./step-02c-executive-summary.md` to generate the Executive Summary.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Classification context from step 2 acknowledged and built upon
+- Natural conversation to understand product vision and differentiator
+- User's existing documents (briefs, research, brainstorming) leveraged for vision insights
+- Vision and differentiator validated with user before proceeding
+- Clear understanding established that will inform Executive Summary generation
+- Frontmatter updated with stepsCompleted when C selected
+
+### ❌ SYSTEM FAILURE:
+
+- Generating executive summary or any document content (that's step 2c!)
+- Appending anything to the PRD document
+- Not building on classification from step 2
+- Being prescriptive instead of having natural conversation
+- Proceeding without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+
+**Master Rule:** This step is vision discovery only. No content generation, no document writing. Have natural conversations, build on what you know from classification, and establish the vision that will feed into the Executive Summary.
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-02c-executive-summary.md b/.claude/skills/bmad-create-prd/steps-c/step-02c-executive-summary.md
new file mode 100644
index 0000000..93c2ac2
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-02c-executive-summary.md
@@ -0,0 +1,158 @@
+# Step 2c: Executive Summary Generation
+
+**Progress: Step 2c of 13** - Next: Success Criteria
+
+## STEP GOAL:
+
+Generate the Executive Summary content using insights from classification (step 2) and vision discovery (step 2b), then append it to the PRD document.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ Content is drafted collaboratively — present for review before saving
+
+### Step-Specific Rules:
+
+- 🎯 Generate Executive Summary content based on discovered insights
+- 💬 Present draft content for user review and refinement before appending
+- 🚫 FORBIDDEN to append content without user approval via 'C'
+- 🎯 Content must be dense, precise, and zero-fluff (PRD quality standards)
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating executive summary content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from steps 1, 2, and 2b are available
+- Project classification exists from step 2 (project type, domain, complexity, context)
+- Vision and differentiator insights exist from step 2b
+- Input documents from step 1 are available (product briefs, research, brainstorming, project docs)
+- This step generates and appends the first substantive content to the PRD
+
+## YOUR TASK:
+
+Draft the Executive Summary section using all discovered insights, present it for user review, and append it to the PRD document when approved.
+
+## EXECUTIVE SUMMARY GENERATION SEQUENCE:
+
+### 1. Synthesize Available Context
+
+Review all available context before drafting:
+- Classification from step 2: project type, domain, complexity, project context
+- Vision and differentiator from step 2b: what makes this special, core insight
+- Input documents: product briefs, research, brainstorming, project docs
+
+### 2. Draft Executive Summary Content
+
+Generate the Executive Summary section using the content structure below. Apply PRD quality standards:
+- High information density — every sentence carries weight
+- Zero fluff — no filler phrases or vague language
+- Precise and actionable — clear, specific statements
+- Dual-audience optimized — readable by humans, consumable by LLMs
+
+### 3. Present Draft for Review
+
+Present the drafted content to the user for review:
+
+"Here's the Executive Summary I've drafted based on our discovery work. Please review and let me know if you'd like any changes:"
+
+Show the full drafted content using the structure from the Content Structure section below.
+
+Allow the user to:
+- Request specific changes to any section
+- Add missing information
+- Refine the language or emphasis
+- Approve as-is
+
+### N. Present MENU OPTIONS
+
+Present the executive summary content for user review, then display menu:
+
+"Here's the Executive Summary for your PRD. Review the content above and let me know what you'd like to do."
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Success Criteria (Step 3 of 13)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the current executive summary content, process the enhanced content that comes back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the current executive summary content, process the collaborative improvements, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-03-success.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the following content structure directly to the document:
+
+```markdown
+## Executive Summary
+
+{vision_alignment_content}
+
+### What Makes This Special
+
+{product_differentiator_content}
+
+## Project Classification
+
+{project_classification_content}
+```
+
+Where:
+- `{vision_alignment_content}` — Product vision, target users, and the problem being solved. Dense, precise summary drawn from step 2b vision discovery.
+- `{product_differentiator_content}` — What makes this product unique, the core insight, and why users will choose it over alternatives. Drawn from step 2b differentiator discovery.
+- `{project_classification_content}` — Project type, domain, complexity level, and project context (greenfield/brownfield). Drawn from step 2 classification.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [content appended to document], will you then read fully and follow: `./step-03-success.md` to define success criteria.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Executive Summary drafted using insights from steps 2 and 2b
+- Content meets PRD quality standards (dense, precise, zero-fluff)
+- Draft presented to user for review before saving
+- User given opportunity to refine content
+- Content properly appended to document when C selected
+- A/P/C menu presented and handled correctly
+- Frontmatter updated with stepsCompleted when C selected
+
+### ❌ SYSTEM FAILURE:
+
+- Generating content without incorporating discovered vision and classification
+- Appending content without user selecting 'C'
+- Producing vague, fluffy, or low-density content
+- Not presenting draft for user review
+- Not presenting A/P/C menu after content generation
+- Skipping directly to next step without appending content
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+**Master Rule:** Generate high-quality Executive Summary content from discovered insights. Present for review, refine collaboratively, and only save when the user approves. This is the first substantive content in the PRD — it sets the quality bar for everything that follows.
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-03-success.md b/.claude/skills/bmad-create-prd/steps-c/step-03-success.md
new file mode 100644
index 0000000..2d57ffe
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-03-success.md
@@ -0,0 +1,214 @@
+# Step 3: Success Criteria Definition
+
+**Progress: Step 3 of 11** - Next: User Journey Mapping
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on defining what winning looks like for this product
+- 🎯 COLLABORATIVE discovery, not assumption-based goal setting
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating success criteria content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Executive Summary and Project Classification already exist in document
+- Input documents from step-01 are available (product briefs, research, brainstorming)
+- No additional data files needed for this step
+- Focus on measurable, specific success criteria
+- LEVERAGE existing input documents to inform success criteria
+
+## YOUR TASK:
+
+Define comprehensive success criteria that cover user success, business success, and technical success, using input documents as a foundation while allowing user refinement.
+
+## SUCCESS DISCOVERY SEQUENCE:
+
+### 1. Begin Success Definition Conversation
+
+**Check Input Documents for Success Indicators:**
+Analyze product brief, research, and brainstorming documents for success criteria already mentioned.
+
+**If Input Documents Contain Success Criteria:**
+Guide user to refine existing success criteria:
+- Acknowledge what's already documented in their materials
+- Extract key success themes from brief, research, and brainstorming
+- Help user identify gaps and areas for expansion
+- Probe for specific, measurable outcomes: When do users feel delighted/relieved/empowered?
+- Ask about emotional success moments and completion scenarios
+- Explore what "worth it" means beyond what's already captured
+
+**If No Success Criteria in Input Documents:**
+Start with user-centered success exploration:
+- Guide conversation toward defining what "worth it" means for users
+- Ask about the moment users realize their problem is solved
+- Explore specific user outcomes and emotional states
+- Identify success "aha!" moments and completion scenarios
+- Focus on user experience of success first
+
+### 2. Explore User Success Metrics
+
+Listen for specific user outcomes and help make them measurable:
+
+- Guide from vague to specific: NOT "users are happy" → "users complete [key action] within [timeframe]"
+- Ask about emotional success: "When do they feel delighted/relieved/empowered?"
+- Identify success moments: "What's the 'aha!' moment?"
+- Define completion scenarios: "What does 'done' look like for the user?"
+
+### 3. Define Business Success
+
+Transition to business metrics:
+- Guide conversation to business perspective on success
+- Explore timelines: What does 3-month success look like? 12-month success?
+- Identify key business metrics: revenue, user growth, engagement, or other measures?
+- Ask what specific metric would indicate "this is working"
+- Understand business success from their perspective
+
+### 4. Challenge Vague Metrics
+
+Push for specificity on business metrics:
+
+- "10,000 users" → "What kind of users? Doing what?"
+- "99.9% uptime" → "What's the real concern - data loss? Failed payments?"
+- "Fast" → "How fast, and what specifically needs to be fast?"
+- "Good adoption" → "What percentage adoption by when?"
+
+### 5. Connect to Product Differentiator
+
+Tie success metrics back to what makes the product special:
+- Connect success criteria to the product's unique differentiator
+- Ensure metrics reflect the specific value proposition
+- Adapt success criteria to domain context:
+  - Consumer: User love, engagement, retention
+  - B2B: ROI, efficiency, adoption
+  - Developer tools: Developer experience, community
+  - Regulated: Compliance, safety, validation
+  - GovTech: Government compliance, accessibility, procurement
+
+### 6. Smart Scope Negotiation
+
+Guide scope definition through success lens:
+- Help user distinguish MVP (must work to be useful) from growth (competitive) and vision (dream)
+- Guide conversation through three scope levels:
+  1. MVP: What's essential for proving the concept?
+  2. Growth: What makes it competitive?
+  3. Vision: What's the dream version?
+- Challenge scope creep conversationally: Could this wait until after launch? Is this essential for MVP?
+- For complex domains: Ensure compliance minimums are included in MVP
+
+### 7. Generate Success Criteria Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Success Criteria
+
+### User Success
+
+[Content about user success criteria based on conversation]
+
+### Business Success
+
+[Content about business success metrics based on conversation]
+
+### Technical Success
+
+[Content about technical success requirements based on conversation]
+
+### Measurable Outcomes
+
+[Content about specific measurable outcomes based on conversation]
+
+## Product Scope
+
+### MVP - Minimum Viable Product
+
+[Content about MVP scope based on conversation]
+
+### Growth Features (Post-MVP)
+
+[Content about growth features based on conversation]
+
+### Vision (Future)
+
+[Content about future vision based on conversation]
+```
+
+### 8. Present MENU OPTIONS
+
+Present the success criteria content for user review, then display menu:
+
+- Show the drafted success criteria and scope definition (using structure from section 7)
+- Ask if they'd like to refine further, get other perspectives, or proceed
+- Present menu options naturally as part of the conversation
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to User Journey Mapping (Step 4 of 11)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the current success criteria content, process the enhanced success metrics that come back, ask user "Accept these improvements to the success criteria? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the current success criteria, process the collaborative improvements to metrics and scope, ask user "Accept these changes to the success criteria? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-04-journeys.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 7.
+
+## SUCCESS METRICS:
+
+✅ User success criteria clearly identified and made measurable
+✅ Business success metrics defined with specific targets
+✅ Success criteria connected to product differentiator
+✅ Scope properly negotiated (MVP, Growth, Vision)
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Accepting vague success metrics without pushing for specificity
+❌ Not connecting success criteria back to product differentiator
+❌ Missing scope negotiation and leaving it undefined
+❌ Generating content without real user input on what success looks like
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## DOMAIN CONSIDERATIONS:
+
+If working in regulated domains (healthcare, fintech, govtech):
+
+- Include compliance milestones in success criteria
+- Add regulatory approval timelines to MVP scope
+- Consider audit requirements as technical success metrics
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-04-journeys.md` to map user journeys.
+
+Remember: Do NOT proceed to step-04 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-04-journeys.md b/.claude/skills/bmad-create-prd/steps-c/step-04-journeys.md
new file mode 100644
index 0000000..ba9d675
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-04-journeys.md
@@ -0,0 +1,201 @@
+# Step 4: User Journey Mapping
+
+**Progress: Step 4 of 11** - Next: Domain Requirements
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on mapping ALL user types that interact with the system
+- 🎯 CRITICAL: No journey = no functional requirements = product doesn't exist
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating journey content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Success criteria and scope already defined
+- Input documents from step-01 are available (product briefs with user personas)
+- Every human interaction with the system needs a journey
+
+## YOUR TASK:
+
+Create compelling narrative user journeys that leverage existing personas from product briefs and identify additional user types needed for comprehensive coverage.
+
+## JOURNEY MAPPING SEQUENCE:
+
+### 1. Leverage Existing Users & Identify Additional Types
+
+**Check Input Documents for Existing Personas:**
+Analyze product brief, research, and brainstorming documents for user personas already defined.
+
+**If User Personas Exist in Input Documents:**
+Guide user to build on existing personas:
+- Acknowledge personas found in their product brief
+- Extract key persona details and backstories
+- Leverage existing insights about their needs
+- Prompt to identify additional user types beyond those documented
+- Suggest additional user types based on product context (admins, moderators, support, API consumers, internal ops)
+- Ask what additional user types should be considered
+
+**If No Personas in Input Documents:**
+Start with comprehensive user type discovery:
+- Guide exploration of ALL people who interact with the system
+- Consider beyond primary users: admins, moderators, support staff, API consumers, internal ops
+- Ask what user types should be mapped for this specific product
+- Ensure comprehensive coverage of all system interactions
+
+### 2. Create Narrative Story-Based Journeys
+
+For each user type, create compelling narrative journeys that tell their story:
+
+#### Narrative Journey Creation Process:
+
+**If Using Existing Persona from Input Documents:**
+Guide narrative journey creation:
+- Use persona's existing backstory from brief
+- Explore how the product changes their life/situation
+- Craft journey narrative: where do we meet them, how does product help them write their next chapter?
+
+**If Creating New Persona:**
+Guide persona creation with story framework:
+- Name: realistic name and personality
+- Situation: What's happening in their life/work that creates need?
+- Goal: What do they desperately want to achieve?
+- Obstacle: What's standing in their way?
+- Solution: How does the product solve their story?
+
+**Story-Based Journey Mapping:**
+
+Guide narrative journey creation using story structure:
+- **Opening Scene**: Where/how do we meet them? What's their current pain?
+- **Rising Action**: What steps do they take? What do they discover?
+- **Climax**: Critical moment where product delivers real value
+- **Resolution**: How does their situation improve? What's their new reality?
+
+Encourage narrative format with specific user details, emotional journey, and clear before/after contrast
+
+### 3. Guide Journey Exploration
+
+For each journey, facilitate detailed exploration:
+- What happens at each step specifically?
+- What could go wrong? What's the recovery path?
+- What information do they need to see/hear?
+- What's their emotional state at each point?
+- Where does this journey succeed or fail?
+
+### 4. Connect Journeys to Requirements
+
+After each journey, explicitly state:
+- This journey reveals requirements for specific capability areas
+- Help user see how different journeys create different feature sets
+- Connect journey needs to concrete capabilities (onboarding, dashboards, notifications, etc.)
+
+### 5. Aim for Comprehensive Coverage
+
+Guide toward complete journey set:
+
+- **Primary user** - happy path (core experience)
+- **Primary user** - edge case (different goal, error recovery)
+- **Secondary user** (admin, moderator, support, etc.)
+- **API consumer** (if applicable)
+
+Ask if additional journeys are needed to cover uncovered user types
+
+### 6. Generate User Journey Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## User Journeys
+
+[All journey narratives based on conversation]
+
+### Journey Requirements Summary
+
+[Summary of capabilities revealed by journeys based on conversation]
+```
+
+### 7. Present MENU OPTIONS
+
+Present the user journey content for review, then display menu:
+- Show the mapped user journeys (using structure from section 6)
+- Highlight how each journey reveals different capabilities
+- Ask if they'd like to refine further, get other perspectives, or proceed
+- Present menu options naturally as part of conversation
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Domain Requirements (Step 5 of 11)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the current journey content, process the enhanced journey insights that come back, ask user "Accept these improvements to the user journeys? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the current journeys, process the collaborative journey improvements and additions, ask user "Accept these changes to the user journeys? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-05-domain.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Existing personas from product briefs leveraged when available
+✅ All user types identified (not just primary users)
+✅ Rich narrative storytelling for each persona and journey
+✅ Complete story-based journey mapping with emotional arc
+✅ Journey requirements clearly connected to capabilities needed
+✅ Minimum 3-4 compelling narrative journeys covering different user types
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Ignoring existing personas from product briefs
+❌ Only mapping primary user journeys and missing secondary users
+❌ Creating generic journeys without rich persona details and narrative
+❌ Missing emotional storytelling elements that make journeys compelling
+❌ Missing critical decision points and failure scenarios
+❌ Not connecting journeys to required capabilities
+❌ Not having enough journey diversity (admin, support, API, etc.)
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## JOURNEY TYPES TO ENSURE:
+
+**Minimum Coverage:**
+
+1. **Primary User - Success Path**: Core experience journey
+2. **Primary User - Edge Case**: Error recovery, alternative goals
+3. **Admin/Operations User**: Management, configuration, monitoring
+4. **Support/Troubleshooting**: Help, investigation, issue resolution
+5. **API/Integration** (if applicable): Developer/technical user journey
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-05-domain.md`.
+
+Remember: Do NOT proceed to step-05 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-05-domain.md b/.claude/skills/bmad-create-prd/steps-c/step-05-domain.md
new file mode 100644
index 0000000..07fe2a6
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-05-domain.md
@@ -0,0 +1,194 @@
+# Step 5: Domain-Specific Requirements (Optional)
+
+**Progress: Step 5 of 13** - Next: Innovation Focus
+
+## STEP GOAL:
+
+For complex domains only that have a mapping in ../data/domain-complexity.csv, explore domain-specific constraints, compliance requirements, and technical considerations that shape the product.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring structured thinking and facilitation skills, while the user brings domain expertise
+
+### Step-Specific Rules:
+
+- 🎯 This step is OPTIONAL - only needed for complex domains
+- 🚫 SKIP if domain complexity is "low" from step-02
+- 💬 APPROACH: Natural conversation to discover domain-specific needs
+- 🎯 Focus on constraints, compliance, and domain patterns
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check domain complexity from step-02 classification first
+- ⚠️ If complexity is "low", offer to skip this step
+- ⚠️ Present A/P/C menu after domain requirements defined (or skipped)
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Domain classification from step-02 is available
+- If complexity is low, this step may be skipped
+- Domain CSV data provides complexity reference
+- Focus on domain-specific constraints, not general requirements
+
+## YOUR TASK:
+
+For complex domains, explore what makes this domain special:
+- **Compliance requirements** - regulations, standards, certifications
+- **Technical constraints** - security, privacy, integration requirements
+- **Domain patterns** - common patterns, best practices, anti-patterns
+- **Risks and mitigations** - what could go wrong, how to prevent it
+
+## DOMAIN DISCOVERY SEQUENCE:
+
+### 1. Check Domain Complexity
+
+**Review classification from step-02:**
+
+- What's the domain complexity level? (low/medium/high)
+- What's the specific domain? (healthcare, fintech, education, etc.)
+
+**If complexity is LOW:**
+
+Offer to skip:
+"The domain complexity from our discovery is low. We may not need deep domain-specific requirements. Would you like to:
+- [C] Skip this step and move to Innovation
+- [D] Do domain exploration anyway"
+
+**If complexity is MEDIUM or HIGH:**
+
+Proceed with domain exploration.
+
+### 2. Load Domain Reference Data
+
+**Attempt subprocess data lookup:**
+
+"Your task: Lookup data in ../data/domain-complexity.csv
+
+**Search criteria:**
+- Find row where domain matches {{domainFromStep02}}
+
+**Return format:**
+Return ONLY the matching row as a YAML-formatted object with these fields:
+domain, complexity, typical_concerns, compliance_requirements
+
+**Do NOT return the entire CSV - only the matching row.**"
+
+**Graceful degradation (if Task tool unavailable):**
+- Load the CSV file directly
+- Find the matching row manually
+- Extract required fields
+- Understand typical concerns and compliance requirements
+
+### 3. Explore Domain-Specific Concerns
+
+**Start with what you know:**
+
+Acknowledge the domain and explore what makes it complex:
+- What regulations apply? (HIPAA, PCI-DSS, GDPR, SOX, etc.)
+- What standards matter? (ISO, NIST, domain-specific standards)
+- What certifications are needed? (security, privacy, domain-specific)
+- What integrations are required? (EMR systems, payment processors, etc.)
+
+**Explore technical constraints:**
+- Security requirements (encryption, audit logs, access control)
+- Privacy requirements (data handling, consent, retention)
+- Performance requirements (real-time, batch, latency)
+- Availability requirements (uptime, disaster recovery)
+
+### 4. Document Domain Requirements
+
+**Structure the requirements around key concerns:**
+
+```markdown
+### Compliance & Regulatory
+- [Specific requirements]
+
+### Technical Constraints
+- [Security, privacy, performance needs]
+
+### Integration Requirements
+- [Required systems and data flows]
+
+### Risk Mitigations
+- [Domain-specific risks and how to address them]
+```
+
+### 5. Validate Completeness
+
+**Check with the user:**
+
+"Are there other domain-specific concerns we should consider? For [this domain], what typically gets overlooked?"
+
+### N. Present MENU OPTIONS
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue - Save and Proceed to Innovation (Step 6 of 13)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill, and when finished redisplay the menu
+- IF P: Invoke the `bmad-party-mode` skill, and when finished redisplay the menu
+- IF C: Save content to {outputFile}, update frontmatter, then read fully and follow: ./step-06-innovation.md
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#n-present-menu-options)
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT
+
+When user selects 'C', append to `{outputFile}`:
+
+```markdown
+## Domain-Specific Requirements
+
+{{discovered domain requirements}}
+```
+
+If step was skipped, append nothing and proceed.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [content saved or skipped], will you then read fully and follow: `./step-06-innovation.md` to explore innovation.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Domain complexity checked before proceeding
+- Offered to skip if complexity is low
+- Natural conversation exploring domain concerns
+- Compliance, technical, and integration requirements identified
+- Domain-specific risks documented with mitigations
+- User validated completeness
+- Content properly saved (or step skipped) when C selected
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking domain complexity first
+- Not offering to skip for low-complexity domains
+- Missing critical compliance requirements
+- Not exploring technical constraints
+- Not asking about domain-specific risks
+- Being generic instead of domain-specific
+- Proceeding without user validation
+
+**Master Rule:** This step is OPTIONAL for simple domains. For complex domains, focus on compliance, constraints, and domain patterns. Natural conversation, not checklists.
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-06-innovation.md b/.claude/skills/bmad-create-prd/steps-c/step-06-innovation.md
new file mode 100644
index 0000000..b12d68b
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-06-innovation.md
@@ -0,0 +1,211 @@
+# Step 6: Innovation Discovery
+
+**Progress: Step 6 of 11** - Next: Project Type Analysis
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on detecting and exploring innovative aspects of the product
+- 🎯 OPTIONAL STEP: Only proceed if innovation signals are detected
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating innovation content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Project type from step-02 is available for innovation signal matching
+- Project-type CSV data will be loaded in this step
+- Focus on detecting genuine innovation, not forced creativity
+
+## OPTIONAL STEP CHECK:
+
+Before proceeding with this step, scan for innovation signals:
+
+- Listen for language like "nothing like this exists", "rethinking how X works"
+- Check for project-type innovation signals from CSV
+- Look for novel approaches or unique combinations
+- If no innovation detected, skip this step
+
+## YOUR TASK:
+
+Detect and explore innovation patterns in the product, focusing on what makes it truly novel and how to validate the innovative aspects.
+
+## INNOVATION DISCOVERY SEQUENCE:
+
+### 1. Load Project-Type Innovation Data
+
+Load innovation signals specific to this project type:
+
+- Load `../data/project-types.csv` completely
+- Find the row where `project_type` matches detected type from step-02
+- Extract `innovation_signals` (semicolon-separated list)
+- Extract `web_search_triggers` for potential innovation research
+
+### 2. Listen for Innovation Indicators
+
+Monitor conversation for both general and project-type-specific innovation signals:
+
+#### General Innovation Language:
+
+- "Nothing like this exists"
+- "We're rethinking how [X] works"
+- "Combining [A] with [B] for the first time"
+- "Novel approach to [problem]"
+- "No one has done [concept] before"
+
+#### Project-Type-Specific Signals (from CSV):
+
+Match user descriptions against innovation_signals for their project_type:
+
+- **api_backend**: "API composition;New protocol"
+- **mobile_app**: "Gesture innovation;AR/VR features"
+- **saas_b2b**: "Workflow automation;AI agents"
+- **developer_tool**: "New paradigm;DSL creation"
+
+### 3. Initial Innovation Screening
+
+Ask targeted innovation discovery questions:
+- Guide exploration of what makes the product innovative
+- Explore if they're challenging existing assumptions
+- Ask about novel combinations of technologies/approaches
+- Identify what hasn't been done before
+- Understand which aspects feel most innovative
+
+### 4. Deep Innovation Exploration (If Detected)
+
+If innovation signals are found, explore deeply:
+
+#### Innovation Discovery Questions:
+- What makes it unique compared to existing solutions?
+- What assumption are you challenging?
+- How do we validate it works?
+- What's the fallback if it doesn't?
+- Has anyone tried this before?
+
+#### Market Context Research:
+
+If relevant innovation detected, consider web search for context:
+Use `web_search_triggers` from project-type CSV:
+`[web_search_triggers] {concept} innovations {date}`
+
+### 5. Generate Innovation Content (If Innovation Detected)
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Innovation & Novel Patterns
+
+### Detected Innovation Areas
+
+[Innovation patterns identified based on conversation]
+
+### Market Context & Competitive Landscape
+
+[Market context and research based on conversation]
+
+### Validation Approach
+
+[Validation methodology based on conversation]
+
+### Risk Mitigation
+
+[Innovation risks and fallbacks based on conversation]
+```
+
+### 6. Present MENU OPTIONS (Only if Innovation Detected)
+
+Present the innovation content for review, then display menu:
+- Show identified innovative aspects (using structure from section 5)
+- Highlight differentiation from existing solutions
+- Ask if they'd like to refine further, get other perspectives, or proceed
+- Present menu options naturally as part of conversation
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Project Type Analysis (Step 7 of 11)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the current innovation content, process the enhanced innovation insights that come back, ask user "Accept these improvements to the innovation analysis? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the current innovation content, process the collaborative innovation exploration and ideation, ask user "Accept these changes to the innovation analysis? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-07-project-type.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## NO INNOVATION DETECTED:
+
+If no genuine innovation signals are found after exploration:
+- Acknowledge that no clear innovation signals were found
+- Note this is fine - many successful products are excellent executions of existing concepts
+- Ask if they'd like to try finding innovative angles or proceed
+
+Display: "**Select:** [A] Advanced Elicitation - Let's try to find innovative angles [C] Continue - Skip innovation section and move to Project Type Analysis (Step 7 of 11)"
+
+### Menu Handling Logic:
+- IF A: Proceed with content generation anyway, then return to menu
+- IF C: Skip this step, then read fully and follow: ./step-07-project-type.md
+
+### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 5.
+
+## SUCCESS METRICS:
+
+✅ Innovation signals properly detected from user conversation
+✅ Project-type innovation signals used to guide discovery
+✅ Genuine innovation explored (not forced creativity)
+✅ Validation approach clearly defined for innovative aspects
+✅ Risk mitigation strategies identified
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Forced innovation when none genuinely exists
+❌ Not using project-type innovation signals from CSV
+❌ Missing market context research for novel concepts
+❌ Not addressing validation approach for innovative features
+❌ Creating innovation theater without real innovative aspects
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## SKIP CONDITIONS:
+
+Skip this step and load `./step-07-project-type.md` if:
+
+- No innovation signals detected in conversation
+- Product is incremental improvement rather than breakthrough
+- User confirms innovation exploration is not needed
+- Project-type CSV has no innovation signals for this type
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document (or step is skipped), load `./step-07-project-type.md`.
+
+Remember: Do NOT proceed to step-07 until user explicitly selects 'C' from the A/P/C menu (or confirms step skip)!
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-07-project-type.md b/.claude/skills/bmad-create-prd/steps-c/step-07-project-type.md
new file mode 100644
index 0000000..ea2b9b3
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-07-project-type.md
@@ -0,0 +1,222 @@
+# Step 7: Project-Type Deep Dive
+
+**Progress: Step 7 of 11** - Next: Scoping
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on project-type specific requirements and technical considerations
+- 🎯 DATA-DRIVEN: Use CSV configuration to guide discovery
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating project-type content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Project type from step-02 is available for configuration loading
+- Project-type CSV data will be loaded in this step
+- Focus on technical and functional requirements specific to this project type
+
+## YOUR TASK:
+
+Conduct project-type specific discovery using CSV-driven guidance to define technical requirements.
+
+## PROJECT-TYPE DISCOVERY SEQUENCE:
+
+### 1. Load Project-Type Configuration Data
+
+**Attempt subprocess data lookup:**
+
+"Your task: Lookup data in ../data/project-types.csv
+
+**Search criteria:**
+- Find row where project_type matches {{projectTypeFromStep02}}
+
+**Return format:**
+Return ONLY the matching row as a YAML-formatted object with these fields:
+project_type, key_questions, required_sections, skip_sections, innovation_signals
+
+**Do NOT return the entire CSV - only the matching row.**"
+
+**Graceful degradation (if Task tool unavailable):**
+- Load the CSV file directly
+- Find the matching row manually
+- Extract required fields:
+  - `key_questions` (semicolon-separated list of discovery questions)
+  - `required_sections` (semicolon-separated list of sections to document)
+  - `skip_sections` (semicolon-separated list of sections to skip)
+  - `innovation_signals` (already explored in step-6)
+
+### 2. Conduct Guided Discovery Using Key Questions
+
+Parse `key_questions` from CSV and explore each:
+
+#### Question-Based Discovery:
+
+For each question in `key_questions` from CSV:
+
+- Ask the user naturally in conversational style
+- Listen for their response and ask clarifying follow-ups
+- Connect answers to product value proposition
+
+**Example Flow:**
+If key_questions = "Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?"
+
+Ask naturally:
+
+- "What are the main endpoints your API needs to expose?"
+- "How will you handle authentication and authorization?"
+- "What data formats will you support for requests and responses?"
+
+### 3. Document Project-Type Specific Requirements
+
+Based on user answers to key_questions, synthesize comprehensive requirements:
+
+#### Requirement Categories:
+
+Cover the areas indicated by `required_sections` from CSV:
+
+- Synthesize what was discovered for each required section
+- Document specific requirements, constraints, and decisions
+- Connect to product differentiator when relevant
+
+#### Skip Irrelevant Sections:
+
+Skip areas indicated by `skip_sections` from CSV to avoid wasting time on irrelevant aspects.
+
+### 4. Generate Dynamic Content Sections
+
+Parse `required_sections` list from the matched CSV row. For each section name, generate corresponding content:
+
+#### Common CSV Section Mappings:
+
+- "endpoint_specs" or "endpoint_specification" → API endpoints documentation
+- "auth_model" or "authentication_model" → Authentication approach
+- "platform_reqs" or "platform_requirements" → Platform support needs
+- "device_permissions" or "device_features" → Device capabilities
+- "tenant_model" → Multi-tenancy approach
+- "rbac_matrix" or "permission_matrix" → Permission structure
+
+#### Template Variable Strategy:
+
+- For sections matching common template variables: generate specific content
+- For sections without template matches: include in main project_type_requirements
+- Hybrid approach balances template structure with CSV-driven flexibility
+
+### 5. Generate Project-Type Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## [Project Type] Specific Requirements
+
+### Project-Type Overview
+
+[Project type summary based on conversation]
+
+### Technical Architecture Considerations
+
+[Technical architecture requirements based on conversation]
+
+[Dynamic sections based on CSV and conversation]
+
+### Implementation Considerations
+
+[Implementation specific requirements based on conversation]
+```
+
+### 6. Present MENU OPTIONS
+
+Present the project-type content for review, then display menu:
+
+"Based on our conversation and best practices for this product type, I've documented the {project_type}-specific requirements for {{project_name}}.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from section 5]
+
+**What would you like to do?**"
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Scoping (Step 8 of 11)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the current project-type content, process the enhanced technical insights that come back, ask user "Accept these improvements to the technical requirements? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the current project-type requirements, process the collaborative technical expertise and validation, ask user "Accept these changes to the technical requirements? (y/n)", if yes update content with improvements then redisplay menu, if no keep original content then redisplay menu
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-08-scoping.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from previous steps.
+
+## SUCCESS METRICS:
+
+✅ Project-type configuration loaded and used effectively
+✅ All key questions from CSV explored with user input
+✅ Required sections generated per CSV configuration
+✅ Skip sections properly avoided to save time
+✅ Technical requirements connected to product value
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not loading or using project-type CSV configuration
+❌ Missing key questions from CSV in discovery process
+❌ Not generating required sections per CSV configuration
+❌ Documenting sections that should be skipped per CSV
+❌ Creating generic content without project-type specificity
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## PROJECT-TYPE EXAMPLES:
+
+**For api_backend:**
+
+- Focus on endpoints, authentication, data schemas, rate limiting
+- Skip visual design and user journey sections
+- Generate API specification documentation
+
+**For mobile_app:**
+
+- Focus on platform requirements, device permissions, offline mode
+- Skip API endpoint documentation unless needed
+- Generate mobile-specific technical requirements
+
+**For saas_b2b:**
+
+- Focus on multi-tenancy, permissions, integrations
+- Skip mobile-first considerations unless relevant
+- Generate enterprise-specific requirements
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-08-scoping.md` to define project scope.
+
+Remember: Do NOT proceed to step-08 (Scoping) until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-08-scoping.md b/.claude/skills/bmad-create-prd/steps-c/step-08-scoping.md
new file mode 100644
index 0000000..b060dda
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-08-scoping.md
@@ -0,0 +1,216 @@
+# Step 8: Scoping Exercise - MVP & Future Features
+
+**Progress: Step 8 of 11** - Next: Functional Requirements
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on strategic scope decisions that keep projects viable
+- 🎯 EMPHASIZE lean MVP thinking while preserving long-term vision
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 📚 Review the complete PRD document built so far
+- ⚠️ Present A/P/C menu after generating scoping decisions
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+
+## CONTEXT BOUNDARIES:
+
+- Complete PRD document built so far is available for review
+- User journeys, success criteria, and domain requirements are documented
+- Focus on strategic scope decisions, not feature details
+- Balance between user value and implementation feasibility
+
+## YOUR TASK:
+
+Conduct comprehensive scoping exercise to define MVP boundaries and prioritize features across development phases.
+
+## SCOPING SEQUENCE:
+
+### 1. Review Current PRD State
+
+Analyze everything documented so far:
+- Present synthesis of established vision, success criteria, journeys
+- Assess domain and innovation focus
+- Evaluate scope implications: simple MVP, medium, or complex project
+- Ask if initial assessment feels right or if they see it differently
+
+### 2. Define MVP Strategy
+
+Facilitate strategic MVP decisions:
+- Explore MVP philosophy options: problem-solving, experience, platform, or revenue MVP
+- Ask critical questions:
+  - What's the minimum that would make users say 'this is useful'?
+  - What would make investors/partners say 'this has potential'?
+  - What's the fastest path to validated learning?
+- Guide toward appropriate MVP approach for their product
+
+### 3. Scoping Decision Framework
+
+Use structured decision-making for scope:
+
+**Must-Have Analysis:**
+- Guide identification of absolute MVP necessities
+- For each journey and success criterion, ask:
+  - Without this, does the product fail?
+  - Can this be manual initially?
+  - Is this a deal-breaker for early adopters?
+- Analyze journeys for MVP essentials
+
+**Nice-to-Have Analysis:**
+- Identify what could be added later:
+  - Features that enhance but aren't essential
+  - User types that can be added later
+  - Advanced functionality that builds on MVP
+- Ask what features could be added in versions 2, 3, etc.
+
+### 4. Progressive Feature Roadmap
+
+Create phased development approach:
+- Guide mapping of features across development phases
+- Structure as Phase 1 (MVP), Phase 2 (Growth), Phase 3 (Vision)
+- Ensure clear progression and dependencies
+
+- Core user value delivery
+- Essential user journeys
+- Basic functionality that works reliably
+
+**Phase 2: Growth**
+
+- Additional user types
+- Enhanced features
+- Scale improvements
+
+**Phase 3: Expansion**
+
+- Advanced capabilities
+- Platform features
+- New markets or use cases
+
+**Where does your current vision fit in this development sequence?**"
+
+### 5. Risk-Based Scoping
+
+Identify and mitigate scoping risks:
+
+**Technical Risks:**
+"Looking at your innovation and domain requirements:
+
+- What's the most technically challenging aspect?
+- Could we simplify the initial implementation?
+- What's the riskiest assumption about technology feasibility?"
+
+**Market Risks:**
+
+- What's the biggest market risk?
+- How does the MVP address this?
+- What learning do we need to de-risk this?"
+
+**Resource Risks:**
+
+- What if we have fewer resources than planned?
+- What's the absolute minimum team size needed?
+- Can we launch with a smaller feature set?"
+
+### 6. Generate Scoping Content
+
+Prepare comprehensive scoping section:
+
+#### Content Structure:
+
+```markdown
+## Project Scoping & Phased Development
+
+### MVP Strategy & Philosophy
+
+**MVP Approach:** {{chosen_mvp_approach}}
+**Resource Requirements:** {{mvp_team_size_and_skills}}
+
+### MVP Feature Set (Phase 1)
+
+**Core User Journeys Supported:**
+{{essential_journeys_for_mvp}}
+
+**Must-Have Capabilities:**
+{{list_of_essential_mvp_features}}
+
+### Post-MVP Features
+
+**Phase 2 (Post-MVP):**
+{{planned_growth_features}}
+
+**Phase 3 (Expansion):**
+{{planned_expansion_features}}
+
+### Risk Mitigation Strategy
+
+**Technical Risks:** {{mitigation_approach}}
+**Market Risks:** {{validation_approach}}
+**Resource Risks:** {{contingency_approach}}
+```
+
+### 7. Present MENU OPTIONS
+
+Present the scoping decisions for review, then display menu:
+- Show strategic scoping plan (using structure from step 6)
+- Highlight MVP boundaries and phased roadmap
+- Ask if they'd like to refine further, get other perspectives, or proceed
+- Present menu options naturally as part of conversation
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Functional Requirements (Step 9 of 11)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the current scoping analysis, process the enhanced insights that come back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the scoping context, process the collaborative insights on MVP and roadmap decisions, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-09-functional.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Complete PRD document analyzed for scope implications
+✅ Strategic MVP approach defined and justified
+✅ Clear MVP feature boundaries established
+✅ Phased development roadmap created
+✅ Key risks identified and mitigation strategies defined
+✅ User explicitly agrees to scope decisions
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not analyzing the complete PRD before making scoping decisions
+❌ Making scope decisions without strategic rationale
+❌ Not getting explicit user agreement on MVP boundaries
+❌ Missing critical risk analysis
+❌ Not creating clear phased development approach
+❌ Not presenting A/P/C menu after content generation
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load ./step-09-functional.md.
+
+Remember: Do NOT proceed to step-09 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-09-functional.md b/.claude/skills/bmad-create-prd/steps-c/step-09-functional.md
new file mode 100644
index 0000000..46f7a4a
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-09-functional.md
@@ -0,0 +1,219 @@
+# Step 9: Functional Requirements Synthesis
+
+**Progress: Step 9 of 11** - Next: Non-Functional Requirements
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on creating comprehensive capability inventory for the product
+- 🎯 CRITICAL: This is THE CAPABILITY CONTRACT for all downstream work
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating functional requirements
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- ALL previous content (executive summary, success criteria, journeys, domain, innovation, project-type) must be referenced
+- No additional data files needed for this step
+- Focus on capabilities, not implementation details
+
+## CRITICAL IMPORTANCE:
+
+**This section defines THE CAPABILITY CONTRACT for the entire product:**
+
+- UX designers will ONLY design what's listed here
+- Architects will ONLY support what's listed here
+- Epic breakdown will ONLY implement what's listed here
+- If a capability is missing from FRs, it will NOT exist in the final product
+
+## FUNCTIONAL REQUIREMENTS SYNTHESIS SEQUENCE:
+
+### 1. Understand FR Purpose and Usage
+
+Start by explaining the critical role of functional requirements:
+
+**Purpose:**
+FRs define WHAT capabilities the product must have. They are the complete inventory of user-facing and system capabilities that deliver the product vision.
+
+**Critical Properties:**
+✅ Each FR is a testable capability
+✅ Each FR is implementation-agnostic (could be built many ways)
+✅ Each FR specifies WHO and WHAT, not HOW
+✅ No UI details, no performance numbers, no technology choices
+✅ Comprehensive coverage of capability areas
+
+**How They Will Be Used:**
+
+1. UX Designer reads FRs → designs interactions for each capability
+2. Architect reads FRs → designs systems to support each capability
+3. PM reads FRs → creates epics and stories to implement each capability
+
+### 2. Review Existing Content for Capability Extraction
+
+Systematically review all previous sections to extract capabilities:
+
+**Extract From:**
+
+- Executive Summary → Core product differentiator capabilities
+- Success Criteria → Success-enabling capabilities
+- User Journeys → Journey-revealed capabilities
+- Domain Requirements → Compliance and regulatory capabilities
+- Innovation Patterns → Innovative feature capabilities
+- Project-Type Requirements → Technical capability needs
+
+### 3. Organize Requirements by Capability Area
+
+Group FRs by logical capability areas (NOT by technology or layer):
+
+**Good Grouping Examples:**
+
+- ✅ "User Management" (not "Authentication System")
+- ✅ "Content Discovery" (not "Search Algorithm")
+- ✅ "Team Collaboration" (not "WebSocket Infrastructure")
+
+**Target 5-8 Capability Areas** for typical projects.
+
+### 4. Generate Comprehensive FR List
+
+Create complete functional requirements using this format:
+
+**Format:**
+
+- FR#: [Actor] can [capability] [context/constraint if needed]
+- Number sequentially (FR1, FR2, FR3...)
+- Aim for 20-50 FRs for typical projects
+
+**Altitude Check:**
+Each FR should answer "WHAT capability exists?" NOT "HOW it's implemented?"
+
+**Examples:**
+
+- ✅ "Users can customize appearance settings"
+- ❌ "Users can toggle light/dark theme with 3 font size options stored in LocalStorage"
+
+### 5. Self-Validation Process
+
+Before presenting to user, validate the FR list:
+
+**Completeness Check:**
+
+1. "Did I cover EVERY capability mentioned in the MVP scope section?"
+2. "Did I include domain-specific requirements as FRs?"
+3. "Did I cover the project-type specific needs?"
+4. "Could a UX designer read ONLY the FRs and know what to design?"
+5. "Could an Architect read ONLY the FRs and know what to support?"
+6. "Are there any user actions or system behaviors we discussed that have no FR?"
+
+**Altitude Check:**
+
+1. "Am I stating capabilities (WHAT) or implementation (HOW)?"
+2. "Am I listing acceptance criteria or UI specifics?" (Remove if yes)
+3. "Could this FR be implemented 5 different ways?" (Good - means it's not prescriptive)
+
+**Quality Check:**
+
+1. "Is each FR clear enough that someone could test whether it exists?"
+2. "Is each FR independent (not dependent on reading other FRs to understand)?"
+3. "Did I avoid vague terms like 'good', 'fast', 'easy'?" (Use NFRs for quality attributes)
+
+### 6. Generate Functional Requirements Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Functional Requirements
+
+### [Capability Area Name]
+
+- FR1: [Specific Actor] can [specific capability]
+- FR2: [Specific Actor] can [specific capability]
+- FR3: [Specific Actor] can [specific capability]
+
+### [Another Capability Area]
+
+- FR4: [Specific Actor] can [specific capability]
+- FR5: [Specific Actor] can [specific capability]
+
+[Continue for all capability areas discovered in conversation]
+```
+
+### 7. Present MENU OPTIONS
+
+Present the functional requirements for review, then display menu:
+- Show synthesized functional requirements (using structure from step 6)
+- Emphasize this is the capability contract for all downstream work
+- Highlight that every feature must trace back to these requirements
+- Ask if they'd like to refine further, get other perspectives, or proceed
+- Present menu options naturally as part of conversation
+
+**What would you like to do?**"
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Non-Functional Requirements (Step 10 of 11)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the current FR list, process the enhanced capability coverage that comes back, ask user if they accept the additions, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the current FR list, process the collaborative capability validation and additions, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-10-nonfunctional.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ All previous discovery content synthesized into FRs
+✅ FRs organized by capability areas (not technology)
+✅ Each FR states WHAT capability exists, not HOW to implement
+✅ Comprehensive coverage with 20-50 FRs typical
+✅ Altitude validation ensures implementation-agnostic requirements
+✅ Completeness check validates coverage of all discussed capabilities
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Missing capabilities from previous discovery sections
+❌ Organizing FRs by technology instead of capability areas
+❌ Including implementation details or UI specifics in FRs
+❌ Not achieving comprehensive coverage of discussed capabilities
+❌ Using vague terms instead of testable capabilities
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## CAPABILITY CONTRACT REMINDER:
+
+Emphasize to user: "This FR list is now binding. Any feature not listed here will not exist in the final product unless we explicitly add it. This is why it's critical to ensure completeness now."
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load ./step-10-nonfunctional.md to define non-functional requirements.
+
+Remember: Do NOT proceed to step-10 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-10-nonfunctional.md b/.claude/skills/bmad-create-prd/steps-c/step-10-nonfunctional.md
new file mode 100644
index 0000000..b00730a
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-10-nonfunctional.md
@@ -0,0 +1,230 @@
+# Step 10: Non-Functional Requirements
+
+**Progress: Step 10 of 12** - Next: Polish Document
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on quality attributes that matter for THIS specific product
+- 🎯 SELECTIVE: Only document NFRs that actually apply to the product
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating NFR content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Functional requirements already defined and will inform NFRs
+- Domain and project-type context will guide which NFRs matter
+- Focus on specific, measurable quality criteria
+
+## YOUR TASK:
+
+Define non-functional requirements that specify quality attributes for the product, focusing only on what matters for THIS specific product.
+
+## NON-FUNCTIONAL REQUIREMENTS SEQUENCE:
+
+### 1. Explain NFR Purpose and Scope
+
+Start by clarifying what NFRs are and why we're selective:
+
+**NFR Purpose:**
+NFRs define HOW WELL the system must perform, not WHAT it must do. They specify quality attributes like performance, security, scalability, etc.
+
+**Selective Approach:**
+We only document NFRs that matter for THIS product. If a category doesn't apply, we skip it entirely. This prevents requirement bloat and focuses on what's actually important.
+
+### 2. Assess Product Context for NFR Relevance
+
+Evaluate which NFR categories matter based on product context:
+
+**Quick Assessment Questions:**
+
+- **Performance**: Is there user-facing impact of speed?
+- **Security**: Are we handling sensitive data or payments?
+- **Scalability**: Do we expect rapid user growth?
+- **Accessibility**: Are we serving broad public audiences?
+- **Integration**: Do we need to connect with other systems?
+- **Reliability**: Would downtime cause significant problems?
+
+### 3. Explore Relevant NFR Categories
+
+For each relevant category, conduct targeted discovery:
+
+#### Performance NFRs (If relevant):
+
+Explore performance requirements:
+- What parts of the system need to be fast for users to be successful?
+- Are there specific response time expectations?
+- What happens if performance is slower than expected?
+- Are there concurrent user scenarios we need to support?
+
+#### Security NFRs (If relevant):
+
+Explore security requirements:
+- What data needs to be protected?
+- Who should have access to what?
+- What are the security risks we need to mitigate?
+- Are there compliance requirements (GDPR, HIPAA, PCI-DSS)?
+
+#### Scalability NFRs (If relevant):
+
+Explore scalability requirements:
+- How many users do we expect initially? Long-term?
+- Are there seasonal or event-based traffic spikes?
+- What happens if we exceed our capacity?
+- What growth scenarios should we plan for?
+
+#### Accessibility NFRs (If relevant):
+
+Explore accessibility requirements:
+- Are we serving users with visual, hearing, or motor impairments?
+- Are there legal accessibility requirements (WCAG, Section 508)?
+- What accessibility features are most important for our users?
+
+#### Integration NFRs (If relevant):
+
+Explore integration requirements:
+- What external systems do we need to connect with?
+- Are there APIs or data formats we must support?
+- How reliable do these integrations need to be?
+
+### 4. Make NFRs Specific and Measurable
+
+For each relevant NFR category, ensure criteria are testable:
+
+**From Vague to Specific:**
+
+- NOT: "The system should be fast" → "User actions complete within 2 seconds"
+- NOT: "The system should be secure" → "All data is encrypted at rest and in transit"
+- NOT: "The system should scale" → "System supports 10x user growth with <10% performance degradation"
+
+### 5. Generate NFR Content (Only Relevant Categories)
+
+Prepare the content to append to the document:
+
+#### Content Structure (Dynamic based on relevance):
+
+When saving to document, append these Level 2 and Level 3 sections (only include sections that are relevant):
+
+```markdown
+## Non-Functional Requirements
+
+### Performance
+
+[Performance requirements based on conversation - only include if relevant]
+
+### Security
+
+[Security requirements based on conversation - only include if relevant]
+
+### Scalability
+
+[Scalability requirements based on conversation - only include if relevant]
+
+### Accessibility
+
+[Accessibility requirements based on conversation - only include if relevant]
+
+### Integration
+
+[Integration requirements based on conversation - only include if relevant]
+```
+
+### 6. Present MENU OPTIONS
+
+Present the non-functional requirements for review, then display menu:
+- Show defined NFRs (using structure from step 5)
+- Note that only relevant categories were included
+- Emphasize NFRs specify how well the system needs to perform
+- Ask if they'd like to refine further, get other perspectives, or proceed
+- Present menu options naturally as part of conversation
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Polish Document (Step 11 of 12)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the current NFR content, process the enhanced quality attribute insights that come back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the current NFR list, process the collaborative technical validation and additions, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-11-polish.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 5.
+
+## SUCCESS METRICS:
+
+✅ Only relevant NFR categories documented (no requirement bloat)
+✅ Each NFR is specific and measurable
+✅ NFRs connected to actual user needs and business context
+✅ Vague requirements converted to testable criteria
+✅ Domain-specific compliance requirements included if relevant
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Documenting NFR categories that don't apply to the product
+❌ Leaving requirements vague and unmeasurable
+❌ Not connecting NFRs to actual user or business needs
+❌ Missing domain-specific compliance requirements
+❌ Creating overly prescriptive technical requirements
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NFR CATEGORY GUIDANCE:
+
+**Include Performance When:**
+
+- User-facing response times impact success
+- Real-time interactions are critical
+- Performance is a competitive differentiator
+
+**Include Security When:**
+
+- Handling sensitive user data
+- Processing payments or financial information
+- Subject to compliance regulations
+- Protecting intellectual property
+
+**Include Scalability When:**
+
+- Expecting rapid user growth
+- Handling variable traffic patterns
+- Supporting enterprise-scale usage
+- Planning for market expansion
+
+**Include Accessibility When:**
+
+- Serving broad public audiences
+- Subject to accessibility regulations
+- Targeting users with disabilities
+- B2B customers with accessibility requirements
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load ./step-11-polish.md to finalize the PRD and complete the workflow.
+
+Remember: Do NOT proceed to step-11 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-11-polish.md b/.claude/skills/bmad-create-prd/steps-c/step-11-polish.md
new file mode 100644
index 0000000..c63ae5b
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-11-polish.md
@@ -0,0 +1,221 @@
+# Step 11: Document Polish
+
+**Progress: Step 11 of 12** - Next: Complete PRD
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 CRITICAL: Load the ENTIRE document before making changes
+- 📖 CRITICAL: Read complete step file before taking action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- ✅ This is a POLISH step - optimize existing content
+- 📋 IMPROVE flow, coherence, and readability
+- 💬 PRESERVE user's voice and intent
+- 🎯 MAINTAIN all essential information while improving presentation
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load complete document first
+- 📝 Review for flow and coherence issues
+- ✂️ Reduce duplication while preserving essential info
+- 📖 Ensure proper ## Level 2 headers throughout
+- 💾 Save optimized document
+- ⚠️ Present A/P/C menu after polish
+- 🚫 DO NOT skip review steps
+
+## CONTEXT BOUNDARIES:
+
+- Complete PRD document exists from all previous steps
+- Document may have duplication from progressive append
+- Sections may not flow smoothly together
+- Level 2 headers ensure document can be split if needed
+- Focus on readability and coherence
+
+## YOUR TASK:
+
+Optimize the complete PRD document for flow, coherence, and professional presentation while preserving all essential information.
+
+## DOCUMENT POLISH SEQUENCE:
+
+### 1. Load Context and Document
+
+**CRITICAL:** Load the PRD purpose document first:
+
+- Read `../data/prd-purpose.md` to understand what makes a great BMAD PRD
+- Internalize the philosophy: information density, traceability, measurable requirements
+- Keep the dual-audience nature (humans + LLMs) in mind
+
+**Then Load the PRD Document:**
+
+- Read `{outputFile}` completely from start to finish
+- Understand the full document structure and content
+- Identify all sections and their relationships
+- Note areas that need attention
+
+### 2. Document Quality Review
+
+Review the entire document with PRD purpose principles in mind:
+
+**Information Density:**
+- Are there wordy phrases that can be condensed?
+- Is conversational padding present?
+- Can sentences be more direct and concise?
+
+**Flow and Coherence:**
+- Do sections transition smoothly?
+- Are there jarring topic shifts?
+- Does the document tell a cohesive story?
+- Is the progression logical for readers?
+
+**Duplication Detection:**
+- Are ideas repeated across sections?
+- Is the same information stated multiple times?
+- Can redundant content be consolidated?
+- Are there contradictory statements?
+
+**Header Structure:**
+- Are all main sections using ## Level 2 headers?
+- Is the hierarchy consistent (##, ###, ####)?
+- Can sections be easily extracted or referenced?
+- Are headers descriptive and clear?
+
+**Readability:**
+- Are sentences clear and concise?
+- Is the language consistent throughout?
+- Are technical terms used appropriately?
+- Would stakeholders find this easy to understand?
+
+### 2b. Brainstorming Reconciliation (if brainstorming input exists)
+
+**Check the PRD frontmatter `inputDocuments` for any brainstorming document** (e.g., `brainstorming-session*.md`, `brainstorming-report.md`). If a brainstorming document was used as input:
+
+1. **Load the brainstorming document** and extract all distinct ideas, themes, and recommendations
+2. **Cross-reference against the PRD** — for each brainstorming idea, check if it landed in any PRD section (requirements, success criteria, user journeys, scope, etc.)
+3. **Identify dropped ideas** — ideas from brainstorming that do not appear anywhere in the PRD. Pay special attention to:
+   - Tone, personality, and interaction design ideas (these are most commonly lost)
+   - Design philosophy and coaching approach ideas
+   - "What should this feel like" ideas (UX feel, not just UX function)
+   - Qualitative/soft ideas that don't map cleanly to functional requirements
+4. **Present findings to user**: "These brainstorming ideas did not make it into the PRD: [list]. Should any be incorporated?"
+5. **If user wants to incorporate dropped ideas**: Add them to the most appropriate PRD section (success criteria, non-functional requirements, or a new section if needed)
+
+**Why this matters**: Brainstorming documents are often long, and the PRD's structured template has an implicit bias toward concrete/structural ideas. Soft ideas (tone, philosophy, interaction feel) frequently get silently dropped because they don't map cleanly to FR/NFR format.
+
+### 3. Optimization Actions
+
+Make targeted improvements:
+
+**Improve Flow:**
+- Add transition sentences between sections
+- Smooth out jarring topic shifts
+- Ensure logical progression
+- Connect related concepts across sections
+
+**Reduce Duplication:**
+- Consolidate repeated information
+- Keep content in the most appropriate section
+- Use cross-references instead of repetition
+- Remove redundant explanations
+
+**Enhance Coherence:**
+- Ensure consistent terminology throughout
+- Align all sections with product differentiator
+- Maintain consistent voice and tone
+- Verify scope consistency across sections
+
+**Optimize Headers:**
+- Ensure all main sections use ## Level 2
+- Make headers descriptive and action-oriented
+- Check that headers follow consistent patterns
+- Verify headers support document navigation
+
+### 4. Preserve Critical Information
+
+**While optimizing, ensure NOTHING essential is lost:**
+
+**Must Preserve:**
+- All user success criteria
+- All functional requirements (capability contract)
+- All user journey narratives
+- All scope decisions (MVP, Growth, Vision)
+- All non-functional requirements
+- Product differentiator and vision
+- Domain-specific requirements
+- Innovation analysis (if present)
+
+**Can Consolidate:**
+- Repeated explanations of the same concept
+- Redundant background information
+- Multiple versions of similar content
+- Overlapping examples
+
+### 5. Generate Optimized Document
+
+Create the polished version:
+
+**Polishing Process:**
+1. Start with original document
+2. Apply all optimization actions
+3. Review to ensure nothing essential was lost
+4. Verify improvements enhance readability
+5. Prepare optimized version for review
+
+### 6. Present MENU OPTIONS
+
+Present the polished document for review, then display menu:
+- Show what changed in the polish
+- Highlight improvements made (flow, duplication, headers)
+- Ask if they'd like to refine further, get other perspectives, or proceed
+- Present menu options naturally as part of conversation
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Complete PRD (Step 12 of 12)"
+
+#### Menu Handling Logic:
+- IF A: Invoke the `bmad-advanced-elicitation` skill with the polished document, process the enhanced refinements that come back, ask user "Accept these polish improvements? (y/n)", if yes update content with improvements then redisplay menu, if no keep original polish then redisplay menu
+- IF P: Invoke the `bmad-party-mode` skill with the polished document, process the collaborative refinements to flow and coherence, ask user "Accept these polish changes? (y/n)", if yes update content with improvements then redisplay menu, if no keep original polish then redisplay menu
+- IF C: Save the polished document to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: ./step-12-complete.md
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', replace the entire document content with the polished version.
+
+## SUCCESS METRICS:
+
+✅ Complete document loaded and reviewed
+✅ Flow and coherence improved
+✅ Duplication reduced while preserving essential information
+✅ All main sections use ## Level 2 headers
+✅ Transitions between sections are smooth
+✅ User's voice and intent preserved
+✅ Document is more readable and professional
+✅ A/P/C menu presented and handled correctly
+✅ Brainstorming reconciliation completed (if brainstorming input exists)
+✅ Polished document saved when C selected
+
+## FAILURE MODES:
+
+❌ Loading only partial document (leads to incomplete polish)
+❌ Removing essential information while reducing duplication
+❌ Not preserving user's voice and intent
+❌ Changing content instead of improving presentation
+❌ Not ensuring ## Level 2 headers for main sections
+❌ Making arbitrary style changes instead of coherence improvements
+❌ Not presenting A/P/C menu for user approval
+❌ Saving polished document without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making changes without complete understanding of document requirements
+
+## NEXT STEP:
+
+After user selects 'C' and polished document is saved, load `./step-12-complete.md` to complete the workflow.
+
+Remember: Do NOT proceed to step-12 until user explicitly selects 'C' from the A/P/C menu and polished document is saved!
diff --git a/.claude/skills/bmad-create-prd/steps-c/step-12-complete.md b/.claude/skills/bmad-create-prd/steps-c/step-12-complete.md
new file mode 100644
index 0000000..d7b6525
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/steps-c/step-12-complete.md
@@ -0,0 +1,115 @@
+# Step 12: Workflow Completion
+
+**Final Step - Complete the PRD**
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ THIS IS A FINAL STEP - Workflow completion required
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action
+- 🛑 NO content generation - this is a wrap-up step
+- 📋 FINALIZE document and update workflow status
+- 💬 FOCUS on completion, validation options, and next steps
+- 🎯 UPDATE workflow status files with completion information
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Update the main workflow status file with completion information (if exists)
+- 📖 Offer validation workflow options to user
+- 🚫 DO NOT load additional steps after this one
+
+## TERMINATION STEP PROTOCOLS:
+
+- This is a FINAL step - workflow completion required
+- Update workflow status file with finalized document
+- Suggest validation and next workflow steps
+- Mark workflow as complete in status tracking
+
+## CONTEXT BOUNDARIES:
+
+- Complete and polished PRD document is available from all previous steps
+- Workflow frontmatter shows all completed steps including polish
+- All collaborative content has been generated, saved, and optimized
+- Focus on completion, validation options, and next steps
+
+## YOUR TASK:
+
+Complete the PRD workflow, update status files, offer validation options, and suggest next steps for the project.
+
+## WORKFLOW COMPLETION SEQUENCE:
+
+### 1. Announce Workflow Completion
+
+Inform user that the PRD is complete and polished:
+- Celebrate successful completion of comprehensive PRD
+- Summarize all sections that were created
+- Highlight that document has been polished for flow and coherence
+- Emphasize document is ready for downstream work
+
+### 2. Workflow Status Update
+
+Update the main workflow status file if there is one:
+
+- Check workflow configuration for a status file (if one exists)
+- Update workflow_status["prd"] = "{outputFile}"
+- Save file, preserving all comments and structure
+- Mark current timestamp as completion time
+
+### 3. Validation Workflow Options
+
+Offer validation workflows to ensure PRD is ready for implementation:
+
+**Available Validation Workflows:**
+
+**Option 1: Check Implementation Readiness** (`skill:bmad-check-implementation-readiness`)
+- Validates PRD has all information needed for development
+- Checks epic coverage completeness
+- Reviews UX alignment with requirements
+- Assesses epic quality and readiness
+- Identifies gaps before architecture/design work begins
+
+**When to use:** Before starting technical architecture or epic breakdown
+
+**Option 2: Skip for Now**
+- Proceed directly to next workflows (architecture, UX, epics)
+- Validation can be done later if needed
+- Some teams prefer to validate during architecture reviews
+
+### 4. Suggest Next Workflows
+
+PRD complete. Invoke the `bmad-help` skill.
+
+### 5. Final Completion Confirmation
+
+- Confirm completion with user and summarize what has been accomplished
+- Document now contains: Executive Summary, Success Criteria, User Journeys, Domain Requirements (if applicable), Innovation Analysis (if applicable), Project-Type Requirements, Functional Requirements (capability contract), Non-Functional Requirements, and has been polished for flow and coherence
+- Ask if they'd like to run validation workflow or proceed to next workflows
+
+## SUCCESS METRICS:
+
+✅ PRD document contains all required sections and has been polished
+✅ All collaborative content properly saved and optimized
+✅ Workflow status file updated with completion information (if exists)
+✅ Validation workflow options clearly presented
+✅ Clear next step guidance provided to user
+✅ Document quality validation completed
+✅ User acknowledges completion and understands next options
+
+## FAILURE MODES:
+
+❌ Not updating workflow status file with completion information (if exists)
+❌ Not offering validation workflow options
+❌ Missing clear next step guidance for user
+❌ Not confirming document completeness with user
+❌ Workflow not properly marked as complete in status tracking (if applicable)
+❌ User unclear about what happens next or what validation options exist
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## FINAL REMINDER to give the user:
+
+The polished PRD serves as the foundation for all subsequent product development activities. All design, architecture, and development work should trace back to the requirements and vision documented in this PRD - update it also as needed as you continue planning.
+
+**Congratulations on completing the Product Requirements Document for {{project_name}}!** 🎉
diff --git a/.claude/skills/bmad-create-prd/templates/prd-template.md b/.claude/skills/bmad-create-prd/templates/prd-template.md
new file mode 100644
index 0000000..d82219d
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/templates/prd-template.md
@@ -0,0 +1,10 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'prd'
+---
+
+# Product Requirements Document - {{project_name}}
+
+**Author:** {{user_name}}
+**Date:** {{date}}
diff --git a/.claude/skills/bmad-create-prd/workflow.md b/.claude/skills/bmad-create-prd/workflow.md
new file mode 100644
index 0000000..70fbe7a
--- /dev/null
+++ b/.claude/skills/bmad-create-prd/workflow.md
@@ -0,0 +1,61 @@
+---
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+outputFile: '{planning_artifacts}/prd.md'
+---
+
+# PRD Create Workflow
+
+**Goal:** Create comprehensive PRDs through structured workflow facilitation.
+
+**Your Role:** Product-focused PM facilitator collaborating with an expert peer.
+
+You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
+✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`.
+
+2. Route to Create Workflow
+
+"**Create Mode: Creating a new PRD from scratch.**"
+
+Read fully and follow: `./steps-c/step-01-init.md`
diff --git a/.claude/skills/bmad-create-story/SKILL.md b/.claude/skills/bmad-create-story/SKILL.md
new file mode 100644
index 0000000..66119b0
--- /dev/null
+++ b/.claude/skills/bmad-create-story/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-create-story
+description: 'Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-create-story/checklist.md b/.claude/skills/bmad-create-story/checklist.md
new file mode 100644
index 0000000..e47cc0f
--- /dev/null
+++ b/.claude/skills/bmad-create-story/checklist.md
@@ -0,0 +1,357 @@
+# 🎯 Story Context Quality Competition Prompt
+
+## **🔥 CRITICAL MISSION: Outperform and Fix the Original Create-Story LLM**
+
+You are an independent quality validator in a **FRESH CONTEXT**. Your mission is to **thoroughly review** a story file that was generated by the create-story workflow and **systematically identify any mistakes, omissions, or disasters** that the original LLM missed.
+
+**Your purpose is NOT just to validate - it's to FIX and PREVENT LLM developer mistakes, omissions, or disasters!**
+
+### **🚨 CRITICAL MISTAKES TO PREVENT:**
+
+- **Reinventing wheels** - Creating duplicate functionality instead of reusing existing
+- **Wrong libraries** - Using incorrect frameworks, versions, or dependencies
+- **Wrong file locations** - Violating project structure and organization
+- **Breaking regressions** - Implementing changes that break existing functionality
+- **Ignoring UX** - Not following user experience design requirements
+- **Vague implementations** - Creating unclear, ambiguous implementations
+- **Lying about completion** - Implementing incorrectly or incompletely
+- **Not learning from past work** - Ignoring previous story learnings and patterns
+
+### **🚨 EXHAUSTIVE ANALYSIS REQUIRED:**
+
+You must thoroughly analyze **ALL artifacts** to extract critical context - do NOT be lazy or skim! This is the most important quality control function in the entire development process!
+
+### **🔬 UTILIZE SUBPROCESSES AND SUBAGENTS:**
+
+Use research subagents, subprocesses, or parallel processing if available to thoroughly analyze different artifacts **simultaneously and thoroughly**. Leave no stone unturned!
+
+### **🎯 COMPETITIVE EXCELLENCE:**
+
+This is a COMPETITION to create the **ULTIMATE story context** that makes LLM developer mistakes **IMPOSSIBLE**!
+
+## **🚀 HOW TO USE THIS CHECKLIST**
+
+### **When Running from Create-Story Workflow:**
+
+- The workflow framework will automatically:
+  - Load this checklist file
+  - Load the newly created story file (`{story_file_path}`)
+  - Load workflow variables from `./workflow.md`
+  - Execute the validation process
+
+### **When Running in Fresh Context:**
+
+- User should provide the story file path being reviewed
+- Load the story file directly
+- Load the corresponding workflow.md for variable context
+- Proceed with systematic analysis
+
+### **Required Inputs:**
+
+- **Story file**: The story file to review and improve
+- **Workflow variables**: From workflow.md (implementation_artifacts, epics_file, etc.)
+- **Source documents**: Epics, architecture, etc. (discovered or provided)
+- **Validation framework**: The workflow's checklist execution system
+
+---
+
+## **🔬 SYSTEMATIC RE-ANALYSIS APPROACH**
+
+You will systematically re-do the entire story creation process, but with a critical eye for what the original LLM might have missed:
+
+### **Step 1: Load and Understand the Target**
+
+1. **Load the workflow configuration**: `./workflow.md` for variable inclusion
+2. **Load the story file**: `{story_file_path}` (provided by user or discovered)
+3. **Extract metadata**: epic_num, story_num, story_key, story_title from story file
+4. **Resolve all workflow variables**: implementation_artifacts, epics_file, architecture_file, etc.
+5. **Understand current status**: What story implementation guidance is currently provided?
+
+**Note:** If running in fresh context, user should provide the story file path being reviewed. If running from create-story workflow, the validation framework will automatically discover the checklist and story file.
+
+### **Step 2: Exhaustive Source Document Analysis**
+
+**🔥 CRITICAL: Treat this like YOU are creating the story from scratch to PREVENT DISASTERS!**
+**Discover everything the original LLM missed that could cause developer mistakes, omissions, or disasters!**
+
+#### **2.1 Epics and Stories Analysis**
+
+- Load `{epics_file}` (or sharded equivalents)
+- Extract **COMPLETE Epic {{epic_num}} context**:
+  - Epic objectives and business value
+  - ALL stories in this epic (for cross-story context)
+  - Our specific story's requirements, acceptance criteria
+  - Technical requirements and constraints
+  - Cross-story dependencies and prerequisites
+
+#### **2.2 Architecture Deep-Dive**
+
+- Load `{architecture_file}` (single or sharded)
+- **Systematically scan for ANYTHING relevant to this story:**
+  - Technical stack with versions (languages, frameworks, libraries)
+  - Code structure and organization patterns
+  - API design patterns and contracts
+  - Database schemas and relationships
+  - Security requirements and patterns
+  - Performance requirements and optimization strategies
+  - Testing standards and frameworks
+  - Deployment and environment patterns
+  - Integration patterns and external services
+
+#### **2.3 Previous Story Intelligence (if applicable)**
+
+- If `story_num > 1`, load the previous story file
+- Extract **actionable intelligence**:
+  - Dev notes and learnings
+  - Review feedback and corrections needed
+  - Files created/modified and their patterns
+  - Testing approaches that worked/didn't work
+  - Problems encountered and solutions found
+  - Code patterns and conventions established
+
+#### **2.4 Git History Analysis (if available)**
+
+- Analyze recent commits for patterns:
+  - Files created/modified in previous work
+  - Code patterns and conventions used
+  - Library dependencies added/changed
+  - Architecture decisions implemented
+  - Testing approaches used
+
+#### **2.5 Latest Technical Research**
+
+- Identify any libraries/frameworks mentioned
+- Research latest versions and critical information:
+  - Breaking changes or security updates
+  - Performance improvements or deprecations
+  - Best practices for current versions
+
+### **Step 3: Disaster Prevention Gap Analysis**
+
+**🚨 CRITICAL: Identify every mistake the original LLM missed that could cause DISASTERS!**
+
+#### **3.1 Reinvention Prevention Gaps**
+
+- **Wheel reinvention:** Areas where developer might create duplicate functionality
+- **Code reuse opportunities** not identified that could prevent redundant work
+- **Existing solutions** not mentioned that developer should extend instead of replace
+
+#### **3.2 Technical Specification DISASTERS**
+
+- **Wrong libraries/frameworks:** Missing version requirements that could cause compatibility issues
+- **API contract violations:** Missing endpoint specifications that could break integrations
+- **Database schema conflicts:** Missing requirements that could corrupt data
+- **Security vulnerabilities:** Missing security requirements that could expose the system
+- **Performance disasters:** Missing requirements that could cause system failures
+
+#### **3.3 File Structure DISASTERS**
+
+- **Wrong file locations:** Missing organization requirements that could break build processes
+- **Coding standard violations:** Missing conventions that could create inconsistent codebase
+- **Integration pattern breaks:** Missing data flow requirements that could cause system failures
+- **Deployment failures:** Missing environment requirements that could prevent deployment
+
+#### **3.4 Regression DISASTERS**
+
+- **Breaking changes:** Missing requirements that could break existing functionality
+- **Test failures:** Missing test requirements that could allow bugs to reach production
+- **UX violations:** Missing user experience requirements that could ruin the product
+- **Learning failures:** Missing previous story context that could repeat same mistakes
+
+#### **3.5 Implementation DISASTERS**
+
+- **Vague implementations:** Missing details that could lead to incorrect or incomplete work
+- **Completion lies:** Missing acceptance criteria that could allow fake implementations
+- **Scope creep:** Missing boundaries that could cause unnecessary work
+- **Quality failures:** Missing quality requirements that could deliver broken features
+
+### **Step 4: LLM-Dev-Agent Optimization Analysis**
+
+**CRITICAL STEP: Optimize story context for LLM developer agent consumption**
+
+**Analyze current story for LLM optimization issues:**
+
+- **Verbosity problems:** Excessive detail that wastes tokens without adding value
+- **Ambiguity issues:** Vague instructions that could lead to multiple interpretations
+- **Context overload:** Too much information not directly relevant to implementation
+- **Missing critical signals:** Key requirements buried in verbose text
+- **Poor structure:** Information not organized for efficient LLM processing
+
+**Apply LLM Optimization Principles:**
+
+- **Clarity over verbosity:** Be precise and direct, eliminate fluff
+- **Actionable instructions:** Every sentence should guide implementation
+- **Scannable structure:** Use clear headings, bullet points, and emphasis
+- **Token efficiency:** Pack maximum information into minimum text
+- **Unambiguous language:** Clear requirements with no room for interpretation
+
+### **Step 5: Improvement Recommendations**
+
+**For each gap identified, provide specific, actionable improvements:**
+
+#### **5.1 Critical Misses (Must Fix)**
+
+- Missing essential technical requirements
+- Missing previous story context that could cause errors
+- Missing anti-pattern prevention that could lead to duplicate code
+- Missing security or performance requirements
+
+#### **5.2 Enhancement Opportunities (Should Add)**
+
+- Additional architectural guidance that would help developer
+- More detailed technical specifications
+- Better code reuse opportunities
+- Enhanced testing guidance
+
+#### **5.3 Optimization Suggestions (Nice to Have)**
+
+- Performance optimization hints
+- Additional context for complex scenarios
+- Enhanced debugging or development tips
+
+#### **5.4 LLM Optimization Improvements**
+
+- Token-efficient phrasing of existing content
+- Clearer structure for LLM processing
+- More actionable and direct instructions
+- Reduced verbosity while maintaining completeness
+
+---
+
+## **🎯 COMPETITION SUCCESS METRICS**
+
+**You WIN against the original LLM if you identify:**
+
+### **Category 1: Critical Misses (Blockers)**
+
+- Essential technical requirements the developer needs but aren't provided
+- Previous story learnings that would prevent errors if ignored
+- Anti-pattern prevention that would prevent code duplication
+- Security or performance requirements that must be followed
+
+### **Category 2: Enhancement Opportunities**
+
+- Architecture guidance that would significantly help implementation
+- Technical specifications that would prevent wrong approaches
+- Code reuse opportunities the developer should know about
+- Testing guidance that would improve quality
+
+### **Category 3: Optimization Insights**
+
+- Performance or efficiency improvements
+- Development workflow optimizations
+- Additional context for complex scenarios
+
+---
+
+## **📋 INTERACTIVE IMPROVEMENT PROCESS**
+
+After completing your systematic analysis, present your findings to the user interactively:
+
+### **Step 5: Present Improvement Suggestions**
+
+```
+🎯 **STORY CONTEXT QUALITY REVIEW COMPLETE**
+
+**Story:** {{story_key}} - {{story_title}}
+
+I found {{critical_count}} critical issues, {{enhancement_count}} enhancements, and {{optimization_count}} optimizations.
+
+## **🚨 CRITICAL ISSUES (Must Fix)**
+
+{{list each critical issue with clear, actionable description}}
+
+## **⚡ ENHANCEMENT OPPORTUNITIES (Should Add)**
+
+{{list each enhancement with clear benefit description}}
+
+## **✨ OPTIMIZATIONS (Nice to Have)**
+
+{{list each optimization with benefit description}}
+
+## **🤖 LLM OPTIMIZATION (Token Efficiency & Clarity)**
+
+{{list each LLM optimization that will improve dev agent performance:
+- Reduce verbosity while maintaining completeness
+- Improve structure for better LLM processing
+- Make instructions more actionable and direct
+- Enhance clarity and reduce ambiguity}}
+```
+
+### **Step 6: Interactive User Selection**
+
+After presenting the suggestions, ask the user:
+
+```
+**IMPROVEMENT OPTIONS:**
+
+Which improvements would you like me to apply to the story?
+
+**Select from the numbered list above, or choose:**
+- **all** - Apply all suggested improvements
+- **critical** - Apply only critical issues
+- **select** - I'll choose specific numbers
+- **none** - Keep story as-is
+- **details** - Show me more details about any suggestion
+
+Your choice:
+```
+
+### **Step 7: Apply Selected Improvements**
+
+When user accepts improvements:
+
+- **Load the story file**
+- **Apply accepted changes** (make them look natural, as if they were always there)
+- **DO NOT reference** the review process, original LLM, or that changes were "added" or "enhanced"
+- **Ensure clean, coherent final story** that reads as if it was created perfectly the first time
+
+### **Step 8: Confirmation**
+
+After applying changes:
+
+```
+✅ **STORY IMPROVEMENTS APPLIED**
+
+Updated {{count}} sections in the story file.
+
+The story now includes comprehensive developer guidance to prevent common implementation issues and ensure flawless execution.
+
+**Next Steps:**
+1. Review the updated story
+2. Run `dev-story` for implementation
+```
+
+---
+
+## **💪 COMPETITIVE EXCELLENCE MINDSET**
+
+**Your goal:** Improve the story file with dev agent needed context that makes flawless implementation inevitable while being optimized for LLM developer agent consumption. Remember the dev agent will ONLY have this file to use.
+
+**Success Criteria:** The LLM developer agent that processes your improved story will have:
+
+- ✅ Clear technical requirements they must follow
+- ✅ Previous work context they can build upon
+- ✅ Anti-pattern prevention to avoid common mistakes
+- ✅ Comprehensive guidance for efficient implementation
+- ✅ **Optimized content structure** for maximum clarity and minimum token waste
+- ✅ **Actionable instructions** with no ambiguity or verbosity
+- ✅ **Efficient information density** - maximum guidance in minimum text
+
+**Every improvement should make it IMPOSSIBLE for the developer to:**
+
+- Reinvent existing solutions
+- Use wrong approaches or libraries
+- Create duplicate functionality
+- Miss critical requirements
+- Make implementation errors
+
+**LLM Optimization Should Make it IMPOSSIBLE for the developer agent to:**
+
+- Misinterpret requirements due to ambiguity
+- Waste tokens on verbose, non-actionable content
+- Struggle to find critical information buried in text
+- Get confused by poor structure or organization
+- Miss key implementation signals due to inefficient communication
+
+**Go create the ultimate developer implementation guide! 🚀**
diff --git a/.claude/skills/bmad-create-story/discover-inputs.md b/.claude/skills/bmad-create-story/discover-inputs.md
new file mode 100644
index 0000000..2c313db
--- /dev/null
+++ b/.claude/skills/bmad-create-story/discover-inputs.md
@@ -0,0 +1,88 @@
+# Discover Inputs Protocol
+
+**Objective:** Intelligently load project files (whole or sharded) based on the workflow's Input Files configuration.
+
+**Prerequisite:** Only execute this protocol if the workflow defines an Input Files section. If no input file patterns are configured, skip this entirely.
+
+---
+
+## Step 1: Parse Input File Patterns
+
+- Read the Input Files table from the workflow configuration.
+- For each input group (prd, architecture, epics, ux, etc.), note the **load strategy** if specified.
+
+## Step 2: Load Files Using Smart Strategies
+
+For each pattern in the Input Files table, work through the following substeps in order:
+
+### 2a: Try Sharded Documents First
+
+If a sharded pattern exists for this input, determine the load strategy (defaults to **FULL_LOAD** if not specified), then apply the matching strategy:
+
+#### FULL_LOAD Strategy
+
+Load ALL files in the sharded directory. Use this for PRD, Architecture, UX, brownfield docs, or whenever the full picture is needed.
+
+1. Use the glob pattern to find ALL `.md` files (e.g., `{planning_artifacts}/*architecture*/*.md`).
+2. Load EVERY matching file completely.
+3. Concatenate content in logical order: `index.md` first if it exists, then alphabetical.
+4. Store the combined result in a variable named `{pattern_name_content}` (e.g., `{architecture_content}`).
+
+#### SELECTIVE_LOAD Strategy
+
+Load a specific shard using a template variable. Example: used for epics with `{{epic_num}}`.
+
+1. Check for template variables in the sharded pattern (e.g., `{{epic_num}}`).
+2. If the variable is undefined, ask the user for the value OR infer it from context.
+3. Resolve the template to a specific file path.
+4. Load that specific file.
+5. Store in variable: `{pattern_name_content}`.
+
+#### INDEX_GUIDED Strategy
+
+Load index.md, analyze the structure and description of each doc in the index, then intelligently load relevant docs.
+
+**DO NOT BE LAZY** -- use best judgment to load documents that might have relevant information, even if there is only a 5% chance of relevance.
+
+1. Load `index.md` from the sharded directory.
+2. Parse the table of contents, links, and section headers.
+3. Analyze the workflow's purpose and objective.
+4. Identify which linked/referenced documents are likely relevant.
+   - *Example:* If the workflow is about authentication and the index shows "Auth Overview", "Payment Setup", "Deployment" -- load the auth docs, consider deployment docs, skip payment.
+5. Load all identified relevant documents.
+6. Store combined content in variable: `{pattern_name_content}`.
+
+**When in doubt, LOAD IT** -- context is valuable, and being thorough is better than missing critical info.
+
+---
+
+After applying the matching strategy, mark the pattern as **RESOLVED** and move to the next pattern.
+
+### 2b: Try Whole Document if No Sharded Found
+
+If no sharded matches were found OR no sharded pattern exists for this input:
+
+1. Attempt a glob match on the "whole" pattern (e.g., `{planning_artifacts}/*prd*.md`).
+2. If matches are found, load ALL matching files completely (no offset/limit).
+3. Store content in variable: `{pattern_name_content}` (e.g., `{prd_content}`).
+4. Mark pattern as **RESOLVED** and move to the next pattern.
+
+### 2c: Handle Not Found
+
+If no matches were found for either sharded or whole patterns:
+
+1. Set `{pattern_name_content}` to empty string.
+2. Note in session: "No {pattern_name} files found" -- this is not an error, just unavailable. Offer the user a chance to provide the file.
+
+## Step 3: Report Discovery Results
+
+List all loaded content variables with file counts. Example:
+
+```
+OK Loaded {prd_content} from 5 sharded files: prd/index.md, prd/requirements.md, ...
+OK Loaded {architecture_content} from 1 file: Architecture.md
+OK Loaded {epics_content} from selective load: epics/epic-3.md
+-- No ux_design files found
+```
+
+This gives the workflow transparency into what context is available.
diff --git a/.claude/skills/bmad-create-story/template.md b/.claude/skills/bmad-create-story/template.md
new file mode 100644
index 0000000..c4e129f
--- /dev/null
+++ b/.claude/skills/bmad-create-story/template.md
@@ -0,0 +1,49 @@
+# Story {{epic_num}}.{{story_num}}: {{story_title}}
+
+Status: ready-for-dev
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a {{role}},
+I want {{action}},
+so that {{benefit}}.
+
+## Acceptance Criteria
+
+1. [Add acceptance criteria from epics/PRD]
+
+## Tasks / Subtasks
+
+- [ ] Task 1 (AC: #)
+  - [ ] Subtask 1.1
+- [ ] Task 2 (AC: #)
+  - [ ] Subtask 2.1
+
+## Dev Notes
+
+- Relevant architecture patterns and constraints
+- Source tree components to touch
+- Testing standards summary
+
+### Project Structure Notes
+
+- Alignment with unified project structure (paths, modules, naming)
+- Detected conflicts or variances (with rationale)
+
+### References
+
+- Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
+
+## Dev Agent Record
+
+### Agent Model Used
+
+{{agent_model_name_version}}
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List
diff --git a/.claude/skills/bmad-create-story/workflow.md b/.claude/skills/bmad-create-story/workflow.md
new file mode 100644
index 0000000..0acd866
--- /dev/null
+++ b/.claude/skills/bmad-create-story/workflow.md
@@ -0,0 +1,380 @@
+# Create Story Workflow
+
+**Goal:** Create a comprehensive story file that gives the dev agent everything needed for flawless implementation.
+
+**Your Role:** Story context engine that prevents LLM developer mistakes, omissions, or disasters.
+- Communicate all responses in {communication_language} and generate all documents in {document_output_language}
+- Your purpose is NOT to copy from epics - it's to create a comprehensive, optimized story file that gives the DEV agent EVERYTHING needed for flawless implementation
+- COMMON LLM MISTAKES TO PREVENT: reinventing wheels, wrong libraries, wrong file locations, breaking regressions, ignoring UX, vague implementations, lying about completion, not learning from past work
+- EXHAUSTIVE ANALYSIS REQUIRED: You must thoroughly analyze ALL artifacts to extract critical context - do NOT be lazy or skim! This is the most important function in the entire development process!
+- UTILIZE SUBPROCESSES AND SUBAGENTS: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different artifacts simultaneously and thoroughly
+- SAVE QUESTIONS: If you think of questions or clarifications during analysis, save them for the end after the complete story is written
+- ZERO USER INTERVENTION: Process should be fully automated except for initial epic/story selection or missing documents
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `planning_artifacts`, `implementation_artifacts`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `epics_file` = `{planning_artifacts}/epics.md`
+- `prd_file` = `{planning_artifacts}/prd.md`
+- `architecture_file` = `{planning_artifacts}/architecture.md`
+- `ux_file` = `{planning_artifacts}/*ux*.md`
+- `story_title` = "" (will be elicited if not derivable)
+- `project_context` = `**/project-context.md` (load if exists)
+- `default_output_file` = `{implementation_artifacts}/{{story_key}}.md`
+
+### Input Files
+
+| Input | Description | Path Pattern(s) | Load Strategy |
+|-------|-------------|------------------|---------------|
+| prd | PRD (fallback - epics file should have most content) | whole: `{planning_artifacts}/*prd*.md`, sharded: `{planning_artifacts}/*prd*/*.md` | SELECTIVE_LOAD |
+| architecture | Architecture (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | SELECTIVE_LOAD |
+| ux | UX design (fallback - epics file should have relevant sections) | whole: `{planning_artifacts}/*ux*.md`, sharded: `{planning_artifacts}/*ux*/*.md` | SELECTIVE_LOAD |
+| epics | Enhanced epics+stories file with BDD and source hints | whole: `{planning_artifacts}/*epic*.md`, sharded: `{planning_artifacts}/*epic*/*.md` | SELECTIVE_LOAD |
+
+---
+
+## EXECUTION
+
+<workflow>
+
+<step n="1" goal="Determine target story">
+  <check if="{{story_path}} is provided by user or user provided the epic and story number such as 2-4 or 1.6 or epic 1 story 5">
+    <action>Parse user-provided story path: extract epic_num, story_num, story_title from format like "1-2-user-auth"</action>
+    <action>Set {{epic_num}}, {{story_num}}, {{story_key}} from user input</action>
+    <action>GOTO step 2a</action>
+  </check>
+
+  <action>Check if {{sprint_status}} file exists for auto discover</action>
+  <check if="sprint status file does NOT exist">
+    <output>🚫 No sprint status file found and no story specified</output>
+    <output>
+      **Required Options:**
+      1. Run `sprint-planning` to initialize sprint tracking (recommended)
+      2. Provide specific epic-story number to create (e.g., "1-2-user-auth")
+      3. Provide path to story documents if sprint status doesn't exist yet
+    </output>
+    <ask>Choose option [1], provide epic-story number, path to story docs, or [q] to quit:</ask>
+
+    <check if="user chooses 'q'">
+      <action>HALT - No work needed</action>
+    </check>
+
+    <check if="user chooses '1'">
+      <output>Run sprint-planning workflow first to create sprint-status.yaml</output>
+      <action>HALT - User needs to run sprint-planning</action>
+    </check>
+
+    <check if="user provides epic-story number">
+      <action>Parse user input: extract epic_num, story_num, story_title</action>
+      <action>Set {{epic_num}}, {{story_num}}, {{story_key}} from user input</action>
+      <action>GOTO step 2a</action>
+    </check>
+
+    <check if="user provides story docs path">
+      <action>Use user-provided path for story documents</action>
+      <action>GOTO step 2a</action>
+    </check>
+  </check>
+
+  <!-- Auto-discover from sprint status only if no user input -->
+  <check if="no user input provided">
+    <critical>MUST read COMPLETE {sprint_status} file from start to end to preserve order</critical>
+    <action>Load the FULL file: {{sprint_status}}</action>
+    <action>Read ALL lines from beginning to end - do not skip any content</action>
+    <action>Parse the development_status section completely</action>
+
+    <action>Find the FIRST story (by reading in order from top to bottom) where:
+      - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+      - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+      - Status value equals "backlog"
+    </action>
+
+    <check if="no backlog story found">
+      <output>📋 No backlog stories found in sprint-status.yaml
+
+        All stories are either already created, in progress, or done.
+
+        **Options:**
+        1. Run sprint-planning to refresh story tracking
+        2. Load PM agent and run correct-course to add more stories
+        3. Check if current sprint is complete and run retrospective
+      </output>
+      <action>HALT</action>
+    </check>
+
+    <action>Extract from found story key (e.g., "1-2-user-authentication"):
+      - epic_num: first number before dash (e.g., "1")
+      - story_num: second number after first dash (e.g., "2")
+      - story_title: remainder after second dash (e.g., "user-authentication")
+    </action>
+    <action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
+    <action>Store story_key for later use (e.g., "1-2-user-authentication")</action>
+
+    <!-- Mark epic as in-progress if this is first story -->
+    <action>Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern</action>
+    <check if="this is first story in epic {{epic_num}}">
+      <action>Load {{sprint_status}} and check epic-{{epic_num}} status</action>
+      <action>If epic status is "backlog" → update to "in-progress"</action>
+      <action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action>
+      <action>If epic status is "in-progress" → no change needed</action>
+      <check if="epic status is 'done'">
+        <output>🚫 ERROR: Cannot create story in completed epic</output>
+        <output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output>
+        <output>If you need to add more work, either:</output>
+        <output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output>
+        <output>2. Create a new epic for additional work</output>
+        <action>HALT - Cannot proceed</action>
+      </check>
+      <check if="epic status is not one of: backlog, contexted, in-progress, done">
+        <output>🚫 ERROR: Invalid epic status '{{epic_status}}'</output>
+        <output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output>
+        <output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output>
+        <action>HALT - Cannot proceed</action>
+      </check>
+      <output>📊 Epic {{epic_num}} status updated to in-progress</output>
+    </check>
+
+    <action>GOTO step 2a</action>
+  </check>
+  <action>Load the FULL file: {{sprint_status}}</action>
+  <action>Read ALL lines from beginning to end - do not skip any content</action>
+  <action>Parse the development_status section completely</action>
+
+  <action>Find the FIRST story (by reading in order from top to bottom) where:
+    - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+    - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+    - Status value equals "backlog"
+  </action>
+
+  <check if="no backlog story found">
+    <output>No backlog stories found in sprint-status.yaml
+
+      All stories are either already created, in progress, or done.
+
+      **Options:**
+      1. Run sprint-planning to refresh story tracking
+      2. Load PM agent and run correct-course to add more stories
+      3. Check if current sprint is complete and run retrospective
+    </output>
+    <action>HALT</action>
+  </check>
+
+  <action>Extract from found story key (e.g., "1-2-user-authentication"):
+    - epic_num: first number before dash (e.g., "1")
+    - story_num: second number after first dash (e.g., "2")
+    - story_title: remainder after second dash (e.g., "user-authentication")
+  </action>
+  <action>Set {{story_id}} = "{{epic_num}}.{{story_num}}"</action>
+  <action>Store story_key for later use (e.g., "1-2-user-authentication")</action>
+
+  <!-- Mark epic as in-progress if this is first story -->
+  <action>Check if this is the first story in epic {{epic_num}} by looking for {{epic_num}}-1-* pattern</action>
+  <check if="this is first story in epic {{epic_num}}">
+    <action>Load {{sprint_status}} and check epic-{{epic_num}} status</action>
+    <action>If epic status is "backlog" → update to "in-progress"</action>
+    <action>If epic status is "contexted" (legacy status) → update to "in-progress" (backward compatibility)</action>
+    <action>If epic status is "in-progress" → no change needed</action>
+    <check if="epic status is 'done'">
+      <output>ERROR: Cannot create story in completed epic</output>
+      <output>Epic {{epic_num}} is marked as 'done'. All stories are complete.</output>
+      <output>If you need to add more work, either:</output>
+      <output>1. Manually change epic status back to 'in-progress' in sprint-status.yaml</output>
+      <output>2. Create a new epic for additional work</output>
+      <action>HALT - Cannot proceed</action>
+    </check>
+    <check if="epic status is not one of: backlog, contexted, in-progress, done">
+      <output>ERROR: Invalid epic status '{{epic_status}}'</output>
+      <output>Epic {{epic_num}} has invalid status. Expected: backlog, in-progress, or done</output>
+      <output>Please fix sprint-status.yaml manually or run sprint-planning to regenerate</output>
+      <action>HALT - Cannot proceed</action>
+    </check>
+    <output>Epic {{epic_num}} status updated to in-progress</output>
+  </check>
+
+  <action>GOTO step 2a</action>
+</step>
+
+<step n="2" goal="Load and analyze core artifacts">
+  <critical>🔬 EXHAUSTIVE ARTIFACT ANALYSIS - This is where you prevent future developer mistakes!</critical>
+
+  <!-- Load all available content through discovery protocol -->
+  <action>Read fully and follow `./discover-inputs.md` to load all input files</action>
+  <note>Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content},
+  {project_context}</note>
+
+  <!-- Analyze epics file for story foundation -->
+  <action>From {epics_content}, extract Epic {{epic_num}} complete context:</action> **EPIC ANALYSIS:** - Epic
+  objectives and business value - ALL stories in this epic for cross-story context - Our specific story's requirements, user story
+  statement, acceptance criteria - Technical requirements and constraints - Dependencies on other stories/epics - Source hints pointing to
+  original documents <!-- Extract specific story requirements -->
+  <action>Extract our story ({{epic_num}}-{{story_num}}) details:</action> **STORY FOUNDATION:** - User story statement
+  (As a, I want, so that) - Detailed acceptance criteria (already BDD formatted) - Technical requirements specific to this story -
+  Business context and value - Success criteria <!-- Previous story analysis for context continuity -->
+  <check if="story_num > 1">
+    <action>Find {{previous_story_num}}: scan {implementation_artifacts} for the story file in epic {{epic_num}} with the highest story number less than {{story_num}}</action>
+    <action>Load previous story file: {implementation_artifacts}/{{epic_num}}-{{previous_story_num}}-*.md</action> **PREVIOUS STORY INTELLIGENCE:** -
+  Dev notes and learnings from previous story - Review feedback and corrections needed - Files that were created/modified and their
+  patterns - Testing approaches that worked/didn't work - Problems encountered and solutions found - Code patterns established <action>Extract
+  all learnings that could impact current story implementation</action>
+  </check>
+
+  <!-- Git intelligence for previous work patterns -->
+  <check
+    if="previous story exists AND git repository detected">
+    <action>Get last 5 commit titles to understand recent work patterns</action>
+    <action>Analyze 1-5 most recent commits for relevance to current story:
+      - Files created/modified
+      - Code patterns and conventions used
+      - Library dependencies added/changed
+      - Architecture decisions implemented
+      - Testing approaches used
+    </action>
+    <action>Extract actionable insights for current story implementation</action>
+  </check>
+</step>
+
+<step n="3" goal="Architecture analysis for developer guardrails">
+  <critical>🏗️ ARCHITECTURE INTELLIGENCE - Extract everything the developer MUST follow!</critical> **ARCHITECTURE DOCUMENT ANALYSIS:** <action>Systematically
+  analyze architecture content for story-relevant requirements:</action>
+
+  <!-- Load architecture - single file or sharded -->
+  <check if="architecture file is single file">
+    <action>Load complete {architecture_content}</action>
+  </check>
+  <check if="architecture is sharded to folder">
+    <action>Load architecture index and scan all architecture files</action>
+  </check> **CRITICAL ARCHITECTURE EXTRACTION:** <action>For
+  each architecture section, determine if relevant to this story:</action> - **Technical Stack:** Languages, frameworks, libraries with
+  versions - **Code Structure:** Folder organization, naming conventions, file patterns - **API Patterns:** Service structure, endpoint
+  patterns, data contracts - **Database Schemas:** Tables, relationships, constraints relevant to story - **Security Requirements:**
+  Authentication patterns, authorization rules - **Performance Requirements:** Caching strategies, optimization patterns - **Testing
+  Standards:** Testing frameworks, coverage expectations, test patterns - **Deployment Patterns:** Environment configurations, build
+  processes - **Integration Patterns:** External service integrations, data flows <action>Extract any story-specific requirements that the
+  developer MUST follow</action>
+  <action>Identify any architectural decisions that override previous patterns</action>
+</step>
+
+<step n="4" goal="Web research for latest technical specifics">
+  <critical>🌐 ENSURE LATEST TECH KNOWLEDGE - Prevent outdated implementations!</critical> **WEB INTELLIGENCE:** <action>Identify specific
+  technical areas that require latest version knowledge:</action>
+
+  <!-- Check for libraries/frameworks mentioned in architecture -->
+  <action>From architecture analysis, identify specific libraries, APIs, or
+  frameworks</action>
+  <action>For each critical technology, research latest stable version and key changes:
+    - Latest API documentation and breaking changes
+    - Security vulnerabilities or updates
+    - Performance improvements or deprecations
+    - Best practices for current version
+  </action>
+  **EXTERNAL CONTEXT INCLUSION:** <action>Include in story any critical latest information the developer needs:
+    - Specific library versions and why chosen
+    - API endpoints with parameters and authentication
+    - Recent security patches or considerations
+    - Performance optimization techniques
+    - Migration considerations if upgrading
+  </action>
+</step>
+
+<step n="5" goal="Create comprehensive story file">
+  <critical>📝 CREATE ULTIMATE STORY FILE - The developer's master implementation guide!</critical>
+
+  <action>Initialize from template.md:
+  {default_output_file}</action>
+  <template-output file="{default_output_file}">story_header</template-output>
+
+  <!-- Story foundation from epics analysis -->
+  <template-output
+    file="{default_output_file}">story_requirements</template-output>
+
+  <!-- Developer context section - MOST IMPORTANT PART -->
+  <template-output file="{default_output_file}">
+  developer_context_section</template-output> **DEV AGENT GUARDRAILS:** <template-output file="{default_output_file}">
+  technical_requirements</template-output>
+  <template-output file="{default_output_file}">architecture_compliance</template-output>
+  <template-output
+    file="{default_output_file}">library_framework_requirements</template-output>
+  <template-output file="{default_output_file}">
+  file_structure_requirements</template-output>
+  <template-output file="{default_output_file}">testing_requirements</template-output>
+
+  <!-- Previous story intelligence -->
+  <check
+    if="previous story learnings available">
+    <template-output file="{default_output_file}">previous_story_intelligence</template-output>
+  </check>
+
+  <!-- Git intelligence -->
+  <check
+    if="git analysis completed">
+    <template-output file="{default_output_file}">git_intelligence_summary</template-output>
+  </check>
+
+  <!-- Latest technical specifics -->
+  <check if="web research completed">
+    <template-output file="{default_output_file}">latest_tech_information</template-output>
+  </check>
+
+  <!-- Project context reference -->
+  <template-output
+    file="{default_output_file}">project_context_reference</template-output>
+
+  <!-- Final status update -->
+  <template-output file="{default_output_file}">
+  story_completion_status</template-output>
+
+  <!-- CRITICAL: Set status to ready-for-dev -->
+  <action>Set story Status to: "ready-for-dev"</action>
+  <action>Add completion note: "Ultimate
+  context engine analysis completed - comprehensive developer guide created"</action>
+</step>
+
+<step n="6" goal="Update sprint status and finalize">
+  <action>Validate the newly created story file {default_output_file} against `./checklist.md` and apply any required fixes before finalizing</action>
+  <action>Save story document unconditionally</action>
+
+  <!-- Update sprint status -->
+  <check if="sprint status file exists">
+    <action>Update {{sprint_status}}</action>
+    <action>Load the FULL file and read all development_status entries</action>
+    <action>Find development_status key matching {{story_key}}</action>
+    <action>Verify current status is "backlog" (expected previous state)</action>
+    <action>Update development_status[{{story_key}}] = "ready-for-dev"</action>
+    <action>Update last_updated field to current date</action>
+    <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+  </check>
+
+  <action>Report completion</action>
+  <output>**🎯 ULTIMATE BMad Method STORY CONTEXT CREATED, {user_name}!**
+
+    **Story Details:**
+    - Story ID: {{story_id}}
+    - Story Key: {{story_key}}
+    - File: {{story_file}}
+    - Status: ready-for-dev
+
+    **Next Steps:**
+    1. Review the comprehensive story in {{story_file}}
+    2. Run dev agents `dev-story` for optimized implementation
+    3. Run `code-review` when complete (auto-marks done)
+    4. Optional: If Test Architect module installed, run `/bmad:tea:automate` after `dev-story` to generate guardrail tests
+
+    **The developer now has everything needed for flawless implementation!**
+  </output>
+</step>
+
+</workflow>
diff --git a/.claude/skills/bmad-create-ux-design/SKILL.md b/.claude/skills/bmad-create-ux-design/SKILL.md
new file mode 100644
index 0000000..9607957
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-create-ux-design
+description: 'Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-01-init.md b/.claude/skills/bmad-create-ux-design/steps/step-01-init.md
new file mode 100644
index 0000000..2ec7ecb
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-01-init.md
@@ -0,0 +1,135 @@
+# Step 1: UX Design Workflow Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on initialization and setup only - don't look ahead to future steps
+- 🚪 DETECT existing workflow state and handle continuation properly
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Input document discovery happens in this step
+
+## YOUR TASK:
+
+Initialize the UX design workflow by detecting continuation state and setting up the design specification document.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for file at `{planning_artifacts}/*ux-design-specification*.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+Discover and load context documents using smart discovery. Documents can be in the following locations:
+- {planning_artifacts}/**
+- {output_folder}/**
+- {product_knowledge}/**
+- {project-root}/docs/**
+
+Also - when searching - documents can be a single markdown file, or a folder with an index and multiple files. For Example, if searching for `*foo*.md` and not found, also search for a folder called *foo*/index.md (which indicates sharded content)
+
+Try to discover the following:
+- Product Brief (`*brief*.md`)
+- Research Documents (`*prd*.md`)
+- Project Documentation (generally multiple documents might be found for this in the `{product_knowledge}` or `docs` folder.)
+- Project Context (`**/project-context.md`)
+
+<critical>Confirm what you have found with the user, along with asking if the user wants to provide anything else. Only after this confirmation will you proceed to follow the loading rules</critical>
+
+**Loading Rules:**
+
+- Load ALL discovered files completely that the user confirmed or provided (no offset/limit)
+- If there is a project context, whatever is relevant should try to be biased in the remainder of this whole workflow process
+- For sharded folders, load ALL files to get complete picture, using the index first to potentially know the potential of each document
+- index.md is a guide to what's relevant whenever available
+- Track all successfully loaded files in frontmatter `inputDocuments` array
+
+#### B. Create Initial Document
+
+Copy the template from `../ux-design-template.md` to `{planning_artifacts}/ux-design-specification.md`
+Initialize frontmatter in the template.
+
+#### C. Complete Initialization and Report
+
+Complete setup and report to user:
+
+**Document Setup:**
+
+- Created: `{planning_artifacts}/ux-design-specification.md` from template
+- Initialized frontmatter with workflow state
+
+**Input Documents Discovered:**
+Report what was found:
+"Welcome {{user_name}}! I've set up your UX design workspace for {{project_name}}.
+
+**Documents Found:**
+
+- PRD: {number of PRD files loaded or "None found"}
+- Product brief: {number of brief files loaded or "None found"}
+- Other context: {number of other files loaded or "None found"}
+
+**Files loaded:** {list of specific file names or "No additional documents found"}
+
+Do you have any other documents you'd like me to include, or shall we continue to the next step?
+
+[C] Continue to UX discovery"
+
+## NEXT STEP:
+
+After user selects [C] to continue, ensure the file `{planning_artifacts}/ux-design-specification.md` has been created and saved, and then load `./step-02-discovery.md` to begin the UX discovery phase.
+
+Remember: Do NOT proceed to step-02 until output file has been updated and user explicitly selects [C] to continue!
+
+## SUCCESS METRICS:
+
+✅ Existing workflow detected and handed off to step-01b correctly
+✅ Fresh workflow initialized with template and frontmatter
+✅ Input documents discovered and loaded using sharded-first logic
+✅ All discovered files tracked in frontmatter `inputDocuments`
+✅ User confirmed document setup and can proceed
+
+## FAILURE MODES:
+
+❌ Proceeding with fresh initialization when existing workflow exists
+❌ Not updating frontmatter with discovered input documents
+❌ Creating document without proper template
+❌ Not checking sharded folders first before whole files
+❌ Not reporting what documents were found to user
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-01b-continue.md b/.claude/skills/bmad-create-ux-design/steps/step-01b-continue.md
new file mode 100644
index 0000000..cd1df25
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-01b-continue.md
@@ -0,0 +1,127 @@
+# Step 1B: UX Design Workflow Continuation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on understanding where we left off and continuing appropriately
+- 🚪 RESUME workflow from exact point where it was interrupted
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking action
+- 💾 Keep existing frontmatter `stepsCompleted` values
+- 📖 Only load documents that were already tracked in `inputDocuments`
+- 🚫 FORBIDDEN to modify content completed in previous steps
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter are already loaded
+- Previous context = complete document + existing frontmatter
+- Input documents listed in frontmatter were already processed
+- Last completed step = `lastStep` value from frontmatter
+
+## YOUR TASK:
+
+Resume the UX design workflow from where it was left off, ensuring smooth continuation.
+
+## CONTINUATION SEQUENCE:
+
+### 1. Analyze Current State
+
+Review the frontmatter to understand:
+
+- `stepsCompleted`: Which steps are already done
+- `lastStep`: The most recently completed step number
+- `inputDocuments`: What context was already loaded
+- All other frontmatter variables
+
+### 2. Load All Input Documents
+
+Reload the context documents listed in `inputDocuments`:
+
+- For each document in `inputDocuments`, load the complete file
+- This ensures you have full context for continuation
+- Don't discover new documents - only reload what was previously processed
+
+### 3. Summarize Current Progress
+
+Welcome the user back and provide context:
+"Welcome back {{user_name}}! I'm resuming our UX design collaboration for {{project_name}}.
+
+**Current Progress:**
+
+- Steps completed: {stepsCompleted}
+- Last worked on: Step {lastStep}
+- Context documents available: {len(inputDocuments)} files
+- Current UX design specification is ready with all completed sections
+
+**Document Status:**
+
+- Current UX design document is ready with all completed sections
+- Ready to continue from where we left off
+
+Does this look right, or do you want to make any adjustments before we proceed?"
+
+### 4. Determine Next Step
+
+Based on `lastStep` value, determine which step to load next:
+
+- If `lastStep = 1` → Load `./step-02-discovery.md`
+- If `lastStep = 2` → Load `./step-03-core-experience.md`
+- If `lastStep = 3` → Load `./step-04-emotional-response.md`
+- Continue this pattern for all steps
+- If `lastStep` indicates final step → Workflow already complete
+
+### 5. Present Continuation Options
+
+After presenting current progress, ask:
+"Ready to continue with Step {nextStepNumber}: {nextStepTitle}?
+
+[C] Continue to Step {nextStepNumber}"
+
+## SUCCESS METRICS:
+
+✅ All previous input documents successfully reloaded
+✅ Current workflow state accurately analyzed and presented
+✅ User confirms understanding of progress
+✅ Correct next step identified and prepared for loading
+
+## FAILURE MODES:
+
+❌ Discovering new input documents instead of reloading existing ones
+❌ Modifying content from already completed steps
+❌ Loading wrong next step based on `lastStep` value
+❌ Proceeding without user confirmation of current state
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## WORKFLOW ALREADY COMPLETE?
+
+If `lastStep` indicates the final step is completed:
+"Great news! It looks like we've already completed the UX design workflow for {{project_name}}.
+
+The final UX design specification is ready at {planning_artifacts}/ux-design-specification.md with all sections completed through step {finalStepNumber}.
+
+The complete UX design includes visual foundations, user flows, and design specifications ready for implementation.
+
+Would you like me to:
+
+- Review the completed UX design specification with you
+- Suggest next workflow steps (like wireframe generation or architecture)
+- Start a new UX design revision
+
+What would be most helpful?"
+
+## NEXT STEP:
+
+After user confirms they're ready to continue, load the appropriate next step file based on the `lastStep` value from frontmatter.
+
+Remember: Do NOT load the next step until user explicitly selects [C] to continue!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-02-discovery.md b/.claude/skills/bmad-create-ux-design/steps/step-02-discovery.md
new file mode 100644
index 0000000..e0a8f0b
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-02-discovery.md
@@ -0,0 +1,190 @@
+# Step 2: Project Understanding
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on understanding project context and user needs
+- 🎯 COLLABORATIVE discovery, not assumption-based design
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating project understanding content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper project insights
+- **P (Party Mode)**: Bring multiple perspectives to understand project context
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from step 1 are available
+- Input documents (PRD, briefs, epics) already loaded are in memory
+- No additional data files needed for this step
+- Focus on project and user understanding
+
+## YOUR TASK:
+
+Understand the project context, target users, and what makes this product special from a UX perspective.
+
+## PROJECT DISCOVERY SEQUENCE:
+
+### 1. Review Loaded Context
+
+Start by analyzing what we know from the loaded documents:
+"Based on the project documentation we have loaded, let me confirm what I'm understanding about {{project_name}}.
+
+**From the documents:**
+{summary of key insights from loaded PRD, briefs, and other context documents}
+
+**Target Users:**
+{summary of user information from loaded documents}
+
+**Key Features/Goals:**
+{summary of main features and goals from loaded documents}
+
+Does this match your understanding? Are there any corrections or additions you'd like to make?"
+
+### 2. Fill Context Gaps (If no documents or gaps exist)
+
+If no documents were loaded or key information is missing:
+"Since we don't have complete documentation, let's start with the essentials:
+
+**What are you building?** (Describe your product in 1-2 sentences)
+
+**Who is this for?** (Describe your ideal user or target audience)
+
+**What makes this special or different?** (What's the unique value proposition?)
+
+**What's the main thing users will do with this?** (Core user action or goal)"
+
+### 3. Explore User Context Deeper
+
+Dive into user understanding:
+"Let me understand your users better to inform the UX design:
+
+**User Context Questions:**
+
+- What problem are users trying to solve?
+- What frustrates them with current solutions?
+- What would make them say 'this is exactly what I needed'?
+- How tech-savvy are your target users?
+- What devices will they use most?
+- When/where will they use this product?"
+
+### 4. Identify UX Design Challenges
+
+Surface the key UX challenges to address:
+"From what we've discussed, I'm seeing some key UX design considerations:
+
+**Design Challenges:**
+
+- [Identify 2-3 key UX challenges based on project type and user needs]
+- [Note any platform-specific considerations]
+- [Highlight any complex user flows or interactions]
+
+**Design Opportunities:**
+
+- [Identify 2-3 areas where great UX could create competitive advantage]
+- [Note any opportunities for innovative UX patterns]
+
+Does this capture the key UX considerations we need to address?"
+
+### 5. Generate Project Understanding Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Executive Summary
+
+### Project Vision
+
+[Project vision summary based on conversation]
+
+### Target Users
+
+[Target user descriptions based on conversation]
+
+### Key Design Challenges
+
+[Key UX challenges identified based on conversation]
+
+### Design Opportunities
+
+[Design opportunities identified based on conversation]
+```
+
+### 6. Present Content and Menu
+
+Show the generated project understanding content and present choices:
+"I've documented our understanding of {{project_name}} from a UX perspective. This will guide all our design decisions moving forward.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 5]
+
+**What would you like to do?**
+[C] Continue - Save this to the document and move to core experience definition"
+
+### 7. Handle Menu Selection
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: `stepsCompleted: [1, 2]`
+- Load `./step-03-core-experience.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document. Only after the content is saved to document, read fully and follow: `./step-03-core-experience.md`.
+
+## SUCCESS METRICS:
+
+✅ All available context documents reviewed and synthesized
+✅ Project vision clearly articulated
+✅ Target users well understood
+✅ Key UX challenges identified
+✅ Design opportunities surfaced
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not reviewing loaded context documents thoroughly
+❌ Making assumptions about users without asking
+❌ Missing key UX challenges that will impact design
+❌ Not identifying design opportunities
+❌ Generating generic content without real project insight
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+Remember: Do NOT proceed to step-03 until user explicitly selects 'C' from the menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-03-core-experience.md b/.claude/skills/bmad-create-ux-design/steps/step-03-core-experience.md
new file mode 100644
index 0000000..e14d3fd
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-03-core-experience.md
@@ -0,0 +1,217 @@
+# Step 3: Core Experience Definition
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on defining the core user experience and platform
+- 🎯 COLLABORATIVE discovery, not assumption-based design
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating core experience content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper experience insights
+- **P (Party Mode)**: Bring multiple perspectives to define optimal user experience
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Project understanding from step 2 informs this step
+- No additional data files needed for this step
+- Focus on core experience and platform decisions
+
+## YOUR TASK:
+
+Define the core user experience, platform requirements, and what makes the interaction effortless.
+
+## CORE EXPERIENCE DISCOVERY SEQUENCE:
+
+### 1. Define Core User Action
+
+Start by identifying the most important user interaction:
+"Now let's dig into the heart of the user experience for {{project_name}}.
+
+**Core Experience Questions:**
+
+- What's the ONE thing users will do most frequently?
+- What user action is absolutely critical to get right?
+- What should be completely effortless for users?
+- If we nail one interaction, everything else follows - what is it?
+
+Think about the core loop or primary action that defines your product's value."
+
+### 2. Explore Platform Requirements
+
+Determine where and how users will interact:
+"Let's define the platform context for {{project_name}}:
+
+**Platform Questions:**
+
+- Web, mobile app, desktop, or multiple platforms?
+- Will this be primarily touch-based or mouse/keyboard?
+- Any specific platform requirements or constraints?
+- Do we need to consider offline functionality?
+- Any device-specific capabilities we should leverage?"
+
+### 3. Identify Effortless Interactions
+
+Surface what should feel magical or completely seamless:
+"**Effortless Experience Design:**
+
+- What user actions should feel completely natural and require zero thought?
+- Where do users currently struggle with similar products?
+- What interaction, if made effortless, would create delight?
+- What should happen automatically without user intervention?
+- Where can we eliminate steps that competitors require?"
+
+### 4. Define Critical Success Moments
+
+Identify the moments that determine success or failure:
+"**Critical Success Moments:**
+
+- What's the moment where users realize 'this is better'?
+- When does the user feel successful or accomplished?
+- What interaction, if failed, would ruin the experience?
+- What are the make-or-break user flows?
+- Where does first-time user success happen?"
+
+### 5. Synthesize Experience Principles
+
+Extract guiding principles from the conversation:
+"Based on our discussion, I'm hearing these core experience principles for {{project_name}}:
+
+**Experience Principles:**
+
+- [Principle 1 based on core action focus]
+- [Principle 2 based on effortless interactions]
+- [Principle 3 based on platform considerations]
+- [Principle 4 based on critical success moments]
+
+These principles will guide all our UX decisions. Do these capture what's most important?"
+
+### 6. Generate Core Experience Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Core User Experience
+
+### Defining Experience
+
+[Core experience definition based on conversation]
+
+### Platform Strategy
+
+[Platform requirements and decisions based on conversation]
+
+### Effortless Interactions
+
+[Effortless interaction areas identified based on conversation]
+
+### Critical Success Moments
+
+[Critical success moments defined based on conversation]
+
+### Experience Principles
+
+[Guiding principles for UX decisions based on conversation]
+```
+
+### 7. Present Content and Menu
+
+Show the generated core experience content and present choices:
+"I've defined the core user experience for {{project_name}} based on our conversation. This establishes the foundation for all our UX design decisions.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine the core experience definition
+[P] Party Mode - Bring different perspectives on the user experience
+[C] Continue - Save this to the document and move to emotional response definition"
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current core experience content
+- Process the enhanced experience insights that come back
+- Ask user: "Accept these improvements to the core experience definition? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current core experience definition
+- Process the collaborative experience improvements that come back
+- Ask user: "Accept these changes to the core experience definition? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `./step-04-emotional-response.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Core user action clearly identified and defined
+✅ Platform requirements thoroughly explored
+✅ Effortless interaction areas identified
+✅ Critical success moments mapped out
+✅ Experience principles established as guiding framework
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Missing the core user action that defines the product
+❌ Not properly considering platform requirements
+❌ Overlooking what should be effortless for users
+❌ Not identifying critical make-or-break interactions
+❌ Experience principles too generic or not actionable
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-04-emotional-response.md` to define desired emotional responses.
+
+Remember: Do NOT proceed to step-04 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-04-emotional-response.md b/.claude/skills/bmad-create-ux-design/steps/step-04-emotional-response.md
new file mode 100644
index 0000000..00edced
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-04-emotional-response.md
@@ -0,0 +1,220 @@
+# Step 4: Desired Emotional Response
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on defining desired emotional responses and user feelings
+- 🎯 COLLABORATIVE discovery, not assumption-based design
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating emotional response content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper emotional insights
+- **P (Party Mode)**: Bring multiple perspectives to define optimal emotional responses
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Core experience definition from step 3 informs emotional response
+- No additional data files needed for this step
+- Focus on user feelings and emotional design goals
+
+## YOUR TASK:
+
+Define the desired emotional responses users should feel when using the product.
+
+## EMOTIONAL RESPONSE DISCOVERY SEQUENCE:
+
+### 1. Explore Core Emotional Goals
+
+Start by understanding the emotional objectives:
+"Now let's think about how {{project_name}} should make users feel.
+
+**Emotional Response Questions:**
+
+- What should users FEEL when using this product?
+- What emotion would make them tell a friend about this?
+- How should users feel after accomplishing their primary goal?
+- What feeling differentiates this from competitors?
+
+Common emotional goals: Empowered and in control? Delighted and surprised? Efficient and productive? Creative and inspired? Calm and focused? Connected and engaged?"
+
+### 2. Identify Emotional Journey Mapping
+
+Explore feelings at different stages:
+"**Emotional Journey Considerations:**
+
+- How should users feel when they first discover the product?
+- What emotion during the core experience/action?
+- How should they feel after completing their task?
+- What if something goes wrong - what emotional response do we want?
+- How should they feel when returning to use it again?"
+
+### 3. Define Micro-Emotions
+
+Surface subtle but important emotional states:
+"**Micro-Emotions to Consider:**
+
+- Confidence vs. Confusion
+- Trust vs. Skepticism
+- Excitement vs. Anxiety
+- Accomplishment vs. Frustration
+- Delight vs. Satisfaction
+- Belonging vs. Isolation
+
+Which of these emotional states are most critical for your product's success?"
+
+### 4. Connect Emotions to UX Decisions
+
+Link feelings to design implications:
+"**Design Implications:**
+
+- If we want users to feel [emotional state], what UX choices support this?
+- What interactions might create negative emotions we want to avoid?
+- Where can we add moments of delight or surprise?
+- How do we build trust and confidence through design?
+
+**Emotion-Design Connections:**
+
+- [Emotion 1] → [UX design approach]
+- [Emotion 2] → [UX design approach]
+- [Emotion 3] → [UX design approach]"
+
+### 5. Validate Emotional Goals
+
+Check if emotional goals align with product vision:
+"Let me make sure I understand the emotional vision for {{project_name}}:
+
+**Primary Emotional Goal:** [Summarize main emotional response]
+**Secondary Feelings:** [List supporting emotional states]
+**Emotions to Avoid:** [List negative emotions to prevent]
+
+Does this capture the emotional experience you want to create? Any adjustments needed?"
+
+### 6. Generate Emotional Response Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Desired Emotional Response
+
+### Primary Emotional Goals
+
+[Primary emotional goals based on conversation]
+
+### Emotional Journey Mapping
+
+[Emotional journey mapping based on conversation]
+
+### Micro-Emotions
+
+[Micro-emotions identified based on conversation]
+
+### Design Implications
+
+[UX design implications for emotional responses based on conversation]
+
+### Emotional Design Principles
+
+[Guiding principles for emotional design based on conversation]
+```
+
+### 7. Present Content and Menu
+
+Show the generated emotional response content and present choices:
+"I've defined the desired emotional responses for {{project_name}}. These emotional goals will guide our design decisions to create the right user experience.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine the emotional response definition
+[P] Party Mode - Bring different perspectives on user emotional needs
+[C] Continue - Save this to the document and move to inspiration analysis"
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current emotional response content
+- Process the enhanced emotional insights that come back
+- Ask user: "Accept these improvements to the emotional response definition? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current emotional response definition
+- Process the collaborative emotional insights that come back
+- Ask user: "Accept these changes to the emotional response definition? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `./step-05-inspiration.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Primary emotional goals clearly defined
+✅ Emotional journey mapped across user experience
+✅ Micro-emotions identified and addressed
+✅ Design implications connected to emotional responses
+✅ Emotional design principles established
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Missing core emotional goals or being too generic
+❌ Not considering emotional journey across different stages
+❌ Overlooking micro-emotions that impact user satisfaction
+❌ Not connecting emotional goals to specific UX design choices
+❌ Emotional principles too vague or not actionable
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-05-inspiration.md` to analyze UX patterns from inspiring products.
+
+Remember: Do NOT proceed to step-05 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-05-inspiration.md b/.claude/skills/bmad-create-ux-design/steps/step-05-inspiration.md
new file mode 100644
index 0000000..f6b06a6
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-05-inspiration.md
@@ -0,0 +1,235 @@
+# Step 5: UX Pattern Analysis & Inspiration
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on analyzing existing UX patterns and extracting inspiration
+- 🎯 COLLABORATIVE discovery, not assumption-based design
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating inspiration analysis content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper pattern insights
+- **P ( Party Mode)**: Bring multiple perspectives to analyze UX patterns
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Emotional response goals from step 4 inform pattern analysis
+- No additional data files needed for this step
+- Focus on analyzing existing UX patterns and extracting lessons
+
+## YOUR TASK:
+
+Analyze inspiring products and UX patterns to inform design decisions for the current project.
+
+## INSPIRATION ANALYSIS SEQUENCE:
+
+### 1. Identify User's Favorite Apps
+
+Start by gathering inspiration sources:
+"Let's learn from products your users already love and use regularly.
+
+**Inspiration Questions:**
+
+- Name 2-3 apps your target users already love and USE frequently
+- For each one, what do they do well from a UX perspective?
+- What makes the experience compelling or delightful?
+- What keeps users coming back to these apps?
+
+Think about apps in your category or even unrelated products that have great UX."
+
+### 2. Analyze UX Patterns and Principles
+
+Break down what makes these apps successful:
+"For each inspiring app, let's analyze their UX success:
+
+**For [App Name]:**
+
+- What core problem does it solve elegantly?
+- What makes the onboarding experience effective?
+- How do they handle navigation and information hierarchy?
+- What are their most innovative or delightful interactions?
+- What visual design choices support the user experience?
+- How do they handle errors or edge cases?"
+
+### 3. Extract Transferable Patterns
+
+Identify patterns that could apply to your project:
+"**Transferable UX Patterns:**
+Looking across these inspiring apps, I see patterns we could adapt:
+
+**Navigation Patterns:**
+
+- [Pattern 1] - could work for your [specific use case]
+- [Pattern 2] - might solve your [specific challenge]
+
+**Interaction Patterns:**
+
+- [Pattern 1] - excellent for [your user goal]
+- [Pattern 2] - addresses [your user pain point]
+
+**Visual Patterns:**
+
+- [Pattern 1] - supports your [emotional goal]
+- [Pattern 2] - aligns with your [platform requirements]
+
+Which of these patterns resonate most for your product?"
+
+### 4. Identify Anti-Patterns to Avoid
+
+Surface what not to do based on analysis:
+"**UX Anti-Patterns to Avoid:**
+From analyzing both successes and failures in your space, here are patterns to avoid:
+
+- [Anti-pattern 1] - users find this confusing/frustrating
+- [Anti-pattern 2] - this creates unnecessary friction
+- [Anti-pattern 3] - doesn't align with your [emotional goals]
+
+Learning from others' mistakes is as important as learning from their successes."
+
+### 5. Define Design Inspiration Strategy
+
+Create a clear strategy for using this inspiration:
+"**Design Inspiration Strategy:**
+
+**What to Adopt:**
+
+- [Specific pattern] - because it supports [your core experience]
+- [Specific pattern] - because it aligns with [user needs]
+
+**What to Adapt:**
+
+- [Specific pattern] - modify for [your unique requirements]
+- [Specific pattern] - simplify for [your user skill level]
+
+**What to Avoid:**
+
+- [Specific anti-pattern] - conflicts with [your goals]
+- [Specific anti-pattern] - doesn't fit [your platform]
+
+This strategy will guide our design decisions while keeping {{project_name}} unique."
+
+### 6. Generate Inspiration Analysis Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## UX Pattern Analysis & Inspiration
+
+### Inspiring Products Analysis
+
+[Analysis of inspiring products based on conversation]
+
+### Transferable UX Patterns
+
+[Transferable patterns identified based on conversation]
+
+### Anti-Patterns to Avoid
+
+[Anti-patterns to avoid based on conversation]
+
+### Design Inspiration Strategy
+
+[Strategy for using inspiration based on conversation]
+```
+
+### 7. Present Content and Menu
+
+Show the generated inspiration analysis content and present choices:
+"I've analyzed inspiring UX patterns and products to inform our design strategy for {{project_name}}. This gives us a solid foundation of proven patterns to build upon.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's deepen our UX pattern analysis
+[P] Party Mode - Bring different perspectives on inspiration sources
+[C] Continue - Save this to the document and move to design system choice"
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current inspiration analysis content
+- Process the enhanced pattern insights that come back
+- Ask user: "Accept these improvements to the inspiration analysis? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current inspiration analysis
+- Process the collaborative pattern insights that come back
+- Ask user: "Accept these changes to the inspiration analysis? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Read fully and follow: `./step-06-design-system.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Inspiring products identified and analyzed thoroughly
+✅ UX patterns extracted and categorized effectively
+✅ Transferable patterns identified for current project
+✅ Anti-patterns identified to avoid common mistakes
+✅ Clear design inspiration strategy established
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not getting specific examples of inspiring products
+❌ Surface-level analysis without deep pattern extraction
+❌ Missing opportunities for pattern adaptation
+❌ Not identifying relevant anti-patterns to avoid
+❌ Strategy too generic or not actionable
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-06-design-system.md` to choose the appropriate design system approach.
+
+Remember: Do NOT proceed to step-06 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-06-design-system.md b/.claude/skills/bmad-create-ux-design/steps/step-06-design-system.md
new file mode 100644
index 0000000..d0b3ba6
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-06-design-system.md
@@ -0,0 +1,253 @@
+# Step 6: Design System Choice
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on choosing appropriate design system approach
+- 🎯 COLLABORATIVE decision-making, not recommendation-only
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating design system decision content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper design system insights
+- **P (Party Mode)**: Bring multiple perspectives to evaluate design system options
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Platform requirements from step 3 inform design system choice
+- Inspiration patterns from step 5 guide design system selection
+- Focus on choosing foundation for consistent design
+
+## YOUR TASK:
+
+Choose appropriate design system approach based on project requirements and constraints.
+
+## DESIGN SYSTEM CHOICE SEQUENCE:
+
+### 1. Present Design System Options
+
+Educate about design system approaches:
+"For {{project_name}}, we need to choose a design system foundation. Think of design systems like LEGO blocks for UI - they provide proven components and patterns, ensuring consistency and speeding development.
+
+**Design System Approaches:**
+
+**1. Custom Design System**
+
+- Complete visual uniqueness
+- Full control over every component
+- Higher initial investment
+- Perfect for established brands with unique needs
+
+**2. Established System (Material Design, Ant Design, etc.)**
+
+- Fast development with proven patterns
+- Great defaults and accessibility built-in
+- Less visual differentiation
+- Ideal for startups or internal tools
+
+**3. Themeable System (MUI, Chakra UI, Tailwind UI)**
+
+- Customizable with strong foundation
+- Brand flexibility with proven components
+- Moderate learning curve
+- Good balance of speed and uniqueness
+
+Which direction feels right for your project?"
+
+### 2. Analyze Project Requirements
+
+Guide decision based on project context:
+"**Let's consider your specific needs:**
+
+**Based on our previous conversations:**
+
+- Platform: [platform from step 3]
+- Timeline: [inferred from user conversation]
+- Team Size: [inferred from user conversation]
+- Brand Requirements: [inferred from user conversation]
+- Technical Constraints: [inferred from user conversation]
+
+**Decision Factors:**
+
+- Need for speed vs. need for uniqueness
+- Brand guidelines or existing visual identity
+- Team's design expertise
+- Long-term maintenance considerations
+- Integration requirements with existing systems"
+
+### 3. Explore Specific Design System Options
+
+Dive deeper into relevant options:
+"**Recommended Options Based on Your Needs:**
+
+**For [Your Platform Type]:**
+
+- [Option 1] - [Key benefit] - [Best for scenario]
+- [Option 2] - [Key benefit] - [Best for scenario]
+- [Option 3] - [Key benefit] - [Best for scenario]
+
+**Considerations:**
+
+- Component library size and quality
+- Documentation and community support
+- Customization capabilities
+- Accessibility compliance
+- Performance characteristics
+- Learning curve for your team"
+
+### 4. Facilitate Decision Process
+
+Help user make informed choice:
+"**Decision Framework:**
+
+1. What's most important: Speed, uniqueness, or balance?
+2. How much design expertise does your team have?
+3. Are there existing brand guidelines to follow?
+4. What's your timeline and budget?
+5. Long-term maintenance needs?
+
+Let's evaluate options based on your answers to these questions."
+
+### 5. Finalize Design System Choice
+
+Confirm and document the decision:
+"Based on our analysis, I recommend [Design System Choice] for {{project_name}}.
+
+**Rationale:**
+
+- [Reason 1 based on project needs]
+- [Reason 2 based on constraints]
+- [Reason 3 based on team considerations]
+
+**Next Steps:**
+
+- We'll customize this system to match your brand and needs
+- Define component strategy for custom components needed
+- Establish design tokens and patterns
+
+Does this design system choice feel right to you?"
+
+### 6. Generate Design System Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Design System Foundation
+
+### 1.1 Design System Choice
+
+[Design system choice based on conversation]
+
+### Rationale for Selection
+
+[Rationale for design system selection based on conversation]
+
+### Implementation Approach
+
+[Implementation approach based on chosen system]
+
+### Customization Strategy
+
+[Customization strategy based on project needs]
+```
+
+### 7. Present Content and Menu
+
+Show the generated design system content and present choices:
+"I've documented our design system choice for {{project_name}}. This foundation will ensure consistency and speed up development.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine our design system decision
+[P] Party Mode - Bring technical perspectives on design systems
+[C] Continue - Save this to the document and move to defining experience
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current design system content
+- Process the enhanced design system insights that come back
+- Ask user: "Accept these improvements to the design system decision? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current design system choice
+- Process the collaborative design system insights that come back
+- Ask user: "Accept these changes to the design system decision? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `./step-07-defining-experience.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Design system options clearly presented and explained
+✅ Decision framework applied to project requirements
+✅ Specific design system chosen with clear rationale
+✅ Implementation approach planned
+✅ Customization strategy defined
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not explaining design system concepts clearly
+❌ Rushing to recommendation without understanding requirements
+❌ Not considering technical constraints or team capabilities
+❌ Choosing design system without clear rationale
+❌ Not planning implementation approach
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-07-defining-experience.md` to define the core user interaction.
+
+Remember: Do NOT proceed to step-07 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-07-defining-experience.md b/.claude/skills/bmad-create-ux-design/steps/step-07-defining-experience.md
new file mode 100644
index 0000000..279a359
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-07-defining-experience.md
@@ -0,0 +1,255 @@
+# Step 7: Defining Core Experience
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on defining the core interaction that defines the product
+- 🎯 COLLABORATIVE discovery, not assumption-based design
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating defining experience content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper experience insights
+- **P (Party Mode)**: Bring multiple perspectives to define optimal core experience
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Core experience from step 3 provides foundation
+- Design system choice from step 6 informs implementation
+- Focus on the defining interaction that makes the product special
+
+## YOUR TASK:
+
+Define the core interaction that, if nailed, makes everything else follow in the user experience.
+
+## DEFINING EXPERIENCE SEQUENCE:
+
+### 1. Identify the Defining Experience
+
+Focus on the core interaction:
+"Every successful product has a defining experience - the core interaction that, if we nail it, everything else follows.
+
+**Think about these famous examples:**
+
+- Tinder: "Swipe to match with people"
+- Snapchat: "Share photos that disappear"
+- Instagram: "Share perfect moments with filters"
+- Spotify: "Discover and play any song instantly"
+
+**For {{project_name}}:**
+What's the core action that users will describe to their friends?
+What's the interaction that makes users feel successful?
+If we get ONE thing perfectly right, what should it be?"
+
+### 2. Explore the User's Mental Model
+
+Understand how users think about the core task:
+"**User Mental Model Questions:**
+
+- How do users currently solve this problem?
+- What mental model do they bring to this task?
+- What's their expectation for how this should work?
+- Where are they likely to get confused or frustrated?
+
+**Current Solutions:**
+
+- What do users love/hate about existing approaches?
+- What shortcuts or workarounds do they use?
+- What makes existing solutions feel magical or terrible?"
+
+### 3. Define Success Criteria for Core Experience
+
+Establish what makes the core interaction successful:
+"**Core Experience Success Criteria:**
+
+- What makes users say 'this just works'?
+- When do they feel smart or accomplished?
+- What feedback tells them they're doing it right?
+- How fast should it feel?
+- What should happen automatically?
+
+**Success Indicators:**
+
+- [Success indicator 1]
+- [Success indicator 2]
+- [Success indicator 3]"
+
+### 4. Identify Novel vs. Established Patterns
+
+Determine if we need to innovate or can use proven patterns:
+"**Pattern Analysis:**
+Looking at your core experience, does this:
+
+- Use established UX patterns that users already understand?
+- Require novel interaction design that needs user education?
+- Combine familiar patterns in innovative ways?
+
+**If Novel:**
+
+- What makes this different from existing approaches?
+- How will we teach users this new pattern?
+- What familiar metaphors can we use?
+
+**If Established:**
+
+- Which proven patterns should we adopt?
+- How can we innovate within familiar patterns?
+- What's our unique twist on established interactions?"
+
+### 5. Define Experience Mechanics
+
+Break down the core interaction into details:
+"**Core Experience Mechanics:**
+Let's design the step-by-step flow for [defining experience]:
+
+**1. Initiation:**
+
+- How does the user start this action?
+- What triggers or invites them to begin?
+
+**2. Interaction:**
+
+- What does the user actually do?
+- What controls or inputs do they use?
+- How does the system respond?
+
+**3. Feedback:**
+
+- What tells users they're succeeding?
+- How do they know when it's working?
+- What happens if they make a mistake?
+
+**4. Completion:**
+
+- How do users know they're done?
+- What's the successful outcome?
+- What's next?"
+
+### 6. Generate Defining Experience Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## 2. Core User Experience
+
+### 2.1 Defining Experience
+
+[Defining experience description based on conversation]
+
+### 2.2 User Mental Model
+
+[User mental model analysis based on conversation]
+
+### 2.3 Success Criteria
+
+[Success criteria for core experience based on conversation]
+
+### 2.4 Novel UX Patterns
+
+[Novel UX patterns analysis based on conversation]
+
+### 2.5 Experience Mechanics
+
+[Detailed mechanics for core experience based on conversation]
+```
+
+### 7. Present Content and Menu
+
+Show the generated defining experience content and present choices:
+"I've defined the core experience for {{project_name}} - the interaction that will make users love this product.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine the core experience definition
+[P] Party Mode - Bring different perspectives on the defining interaction
+[C] Continue - Save this to the document and move to visual foundation
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current defining experience content
+- Process the enhanced experience insights that come back
+- Ask user: "Accept these improvements to the defining experience? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current defining experience
+- Process the collaborative experience insights that come back
+- Ask user: "Accept these changes to the defining experience? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `./step-08-visual-foundation.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Defining experience clearly articulated
+✅ User mental model thoroughly analyzed
+✅ Success criteria established for core interaction
+✅ Novel vs. established patterns properly evaluated
+✅ Experience mechanics designed in detail
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not identifying the true core interaction
+❌ Missing user's mental model and expectations
+❌ Not establishing clear success criteria
+❌ Not properly evaluating novel vs. established patterns
+❌ Experience mechanics too vague or incomplete
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-08-visual-foundation.md` to establish visual design foundation.
+
+Remember: Do NOT proceed to step-08 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-08-visual-foundation.md b/.claude/skills/bmad-create-ux-design/steps/step-08-visual-foundation.md
new file mode 100644
index 0000000..0cd3908
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-08-visual-foundation.md
@@ -0,0 +1,225 @@
+# Step 8: Visual Foundation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on establishing visual design foundation (colors, typography, spacing)
+- 🎯 COLLABORATIVE discovery, not assumption-based design
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating visual foundation content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper visual insights
+- **P (Party Mode)**: Bring multiple perspectives to define visual foundation
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Design system choice from step 6 provides component foundation
+- Emotional response goals from step 4 inform visual decisions
+- Focus on colors, typography, spacing, and layout foundation
+
+## YOUR TASK:
+
+Establish the visual design foundation including color themes, typography, and spacing systems.
+
+## VISUAL FOUNDATION SEQUENCE:
+
+### 1. Brand Guidelines Assessment
+
+Check for existing brand requirements:
+"Do you have existing brand guidelines or a specific color palette I should follow? (y/n)
+
+If yes, I'll extract and document your brand colors and create semantic color mappings.
+If no, I'll generate theme options based on your project's personality and emotional goals from our earlier discussion."
+
+### 2. Generate Color Theme Options (If no brand guidelines)
+
+Create visual exploration opportunities:
+"If no existing brand guidelines, I'll create a color theme visualizer to help you explore options.
+
+🎨 I can generate comprehensive HTML color theme visualizers with multiple theme options, complete UI examples, and the ability to see how colors work in real interface contexts.
+
+This will help you make an informed decision about the visual direction for {{project_name}}."
+
+### 3. Define Typography System
+
+Establish the typographic foundation:
+"**Typography Questions:**
+
+- What should the overall tone feel like? (Professional, friendly, modern, classic?)
+- How much text content will users read? (Headings only? Long-form content?)
+- Any accessibility requirements for font sizes or contrast?
+- Any brand fonts we must use?
+
+**Typography Strategy:**
+
+- Choose primary and secondary typefaces
+- Establish type scale (h1, h2, h3, body, etc.)
+- Define line heights and spacing relationships
+- Consider readability and accessibility"
+
+### 4. Establish Spacing and Layout Foundation
+
+Define the structural foundation:
+"**Spacing and Layout Foundation:**
+
+- How should the overall layout feel? (Dense and efficient? Airy and spacious?)
+- What spacing unit should we use? (4px, 8px, 12px base?)
+- How much white space should be between elements?
+- Should we use a grid system? If so, what column structure?
+
+**Layout Principles:**
+
+- [Layout principle 1 based on product type]
+- [Layout principle 2 based on user needs]
+- [Layout principle 3 based on platform requirements]"
+
+### 5. Create Visual Foundation Strategy
+
+Synthesize all visual decisions:
+"**Visual Foundation Strategy:**
+
+**Color System:**
+
+- [Color strategy based on brand guidelines or generated themes]
+- Semantic color mapping (primary, secondary, success, warning, error, etc.)
+- Accessibility compliance (contrast ratios)
+
+**Typography System:**
+
+- [Typography strategy based on content needs and tone]
+- Type scale and hierarchy
+- Font pairing rationale
+
+**Spacing & Layout:**
+
+- [Spacing strategy based on content density and platform]
+- Grid system approach
+- Component spacing relationships
+
+This foundation will ensure consistency across all our design decisions."
+
+### 6. Generate Visual Foundation Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Visual Design Foundation
+
+### Color System
+
+[Color system strategy based on conversation]
+
+### Typography System
+
+[Typography system strategy based on conversation]
+
+### Spacing & Layout Foundation
+
+[Spacing and layout foundation based on conversation]
+
+### Accessibility Considerations
+
+[Accessibility considerations based on conversation]
+```
+
+### 7. Present Content and Menu
+
+Show the generated visual foundation content and present choices:
+"I've established the visual design foundation for {{project_name}}. This provides the building blocks for consistent, beautiful design.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine our visual foundation
+[P] Party Mode - Bring design perspectives on visual choices
+[C] Continue - Save this to the document and move to design directions
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current visual foundation content
+- Process the enhanced visual insights that come back
+- Ask user: "Accept these improvements to the visual foundation? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current visual foundation
+- Process the collaborative visual insights that come back
+- Ask user: "Accept these changes to the visual foundation? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `./step-09-design-directions.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Brand guidelines assessed and incorporated if available
+✅ Color system established with accessibility consideration
+✅ Typography system defined with appropriate hierarchy
+✅ Spacing and layout foundation created
+✅ Visual foundation strategy documented
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not checking for existing brand guidelines first
+❌ Color palette not aligned with emotional goals
+❌ Typography not suitable for content type or readability needs
+❌ Spacing system not appropriate for content density
+❌ Missing accessibility considerations
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-09-design-directions.md` to generate design direction mockups.
+
+Remember: Do NOT proceed to step-09 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-09-design-directions.md b/.claude/skills/bmad-create-ux-design/steps/step-09-design-directions.md
new file mode 100644
index 0000000..a07d9ec
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-09-design-directions.md
@@ -0,0 +1,225 @@
+# Step 9: Design Direction Mockups
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on generating and evaluating design direction variations
+- 🎯 COLLABORATIVE exploration, not assumption-based design
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating design direction content
+- 💾 Generate HTML visualizer for design directions
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper design insights
+- **P (Party Mode)**: Bring multiple perspectives to evaluate design directions
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Visual foundation from step 8 provides design tokens
+- Core experience from step 7 informs layout and interaction design
+- Focus on exploring different visual design directions
+
+## YOUR TASK:
+
+Generate comprehensive design direction mockups showing different visual approaches for the product.
+
+## DESIGN DIRECTIONS SEQUENCE:
+
+### 1. Generate Design Direction Variations
+
+Create diverse visual explorations:
+"I'll generate 6-8 different design direction variations exploring:
+
+- Different layout approaches and information hierarchy
+- Various interaction patterns and visual weights
+- Alternative color applications from our foundation
+- Different density and spacing approaches
+- Various navigation and component arrangements
+
+Each mockup will show a complete vision for {{project_name}} with all our design decisions applied."
+
+### 2. Create HTML Design Direction Showcase
+
+Generate interactive visual exploration:
+"🎨 Design Direction Mockups Generated!
+
+I'm creating a comprehensive HTML design direction showcase at `{planning_artifacts}/ux-design-directions.html`
+
+**What you'll see:**
+
+- 6-8 full-screen mockup variations
+- Interactive states and hover effects
+- Side-by-side comparison tools
+- Complete UI examples with real content
+- Responsive behavior demonstrations
+
+Each mockup represents a complete visual direction for your app's look and feel."
+
+### 3. Present Design Exploration Framework
+
+Guide evaluation criteria:
+"As you explore the design directions, look for:
+
+✅ **Layout Intuitiveness** - Which information hierarchy matches your priorities?
+✅ **Interaction Style** - Which interaction style fits your core experience?
+✅ **Visual Weight** - Which visual density feels right for your brand?
+✅ **Navigation Approach** - Which navigation pattern matches user expectations?
+✅ **Component Usage** - How well do the components support your user journeys?
+✅ **Brand Alignment** - Which direction best supports your emotional goals?
+
+Take your time exploring - this is a crucial decision that will guide all our design work!"
+
+### 4. Facilitate Design Direction Selection
+
+Help user choose or combine elements:
+"After exploring all the design directions:
+
+**Which approach resonates most with you?**
+
+- Pick a favorite direction as-is
+- Combine elements from multiple directions
+- Request modifications to any direction
+- Use one direction as a base and iterate
+
+**Tell me:**
+
+- Which layout feels most intuitive for your users?
+- Which visual weight matches your brand personality?
+- Which interaction style supports your core experience?
+- Are there elements from different directions you'd like to combine?"
+
+### 5. Document Design Direction Decision
+
+Capture the chosen approach:
+"Based on your exploration, I'm understanding your design direction preference:
+
+**Chosen Direction:** [Direction number or combination]
+**Key Elements:** [Specific elements you liked]
+**Modifications Needed:** [Any changes requested]
+**Rationale:** [Why this direction works for your product]
+
+This will become our design foundation moving forward. Are we ready to lock this in, or do you want to explore variations?"
+
+### 6. Generate Design Direction Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Design Direction Decision
+
+### Design Directions Explored
+
+[Summary of design directions explored based on conversation]
+
+### Chosen Direction
+
+[Chosen design direction based on conversation]
+
+### Design Rationale
+
+[Rationale for design direction choice based on conversation]
+
+### Implementation Approach
+
+[Implementation approach based on chosen direction]
+```
+
+### 7. Present Content and Menu
+
+Show the generated design direction content and present choices:
+"I've documented our design direction decision for {{project_name}}. This visual approach will guide all our detailed design work.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine our design direction
+[P] Party Mode - Bring different perspectives on visual choices
+[C] Continue - Save this to the document and move to user journey flows
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current design direction content
+- Process the enhanced design insights that come back
+- Ask user: "Accept these improvements to the design direction? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current design direction
+- Process the collaborative design insights that come back
+- Ask user: "Accept these changes to the design direction? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `./step-10-user-journeys.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Multiple design direction variations generated
+✅ HTML showcase created with interactive elements
+✅ Design evaluation criteria clearly established
+✅ User able to explore and compare directions effectively
+✅ Design direction decision made with clear rationale
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not creating enough variation in design directions
+❌ Design directions not aligned with established foundation
+❌ Missing interactive elements in HTML showcase
+❌ Not providing clear evaluation criteria
+❌ Rushing decision without thorough exploration
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-10-user-journeys.md` to design user journey flows.
+
+Remember: Do NOT proceed to step-10 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-10-user-journeys.md b/.claude/skills/bmad-create-ux-design/steps/step-10-user-journeys.md
new file mode 100644
index 0000000..1b9c06e
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-10-user-journeys.md
@@ -0,0 +1,242 @@
+# Step 10: User Journey Flows
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on designing user flows and journey interactions
+- 🎯 COLLABORATIVE flow design, not assumption-based layouts
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating user journey content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper journey insights
+- **P (Party Mode)**: Bring multiple perspectives to design user flows
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Design direction from step 9 informs flow layout and visual design
+- Core experience from step 7 defines key journey interactions
+- Focus on designing detailed user flows with Mermaid diagrams
+
+## YOUR TASK:
+
+Design detailed user journey flows for critical user interactions.
+
+## USER JOURNEY FLOWS SEQUENCE:
+
+### 1. Load PRD User Journeys as Foundation
+
+Start with user journeys already defined in the PRD:
+"Great! Since we have the PRD available, let's build on the user journeys already documented there.
+
+**Existing User Journeys from PRD:**
+I've already loaded these user journeys from your PRD:
+[Journey narratives from PRD input documents]
+
+These journeys tell us **who** users are and **why** they take certain actions. Now we need to design **how** those journeys work in detail.
+
+**Critical Journeys to Design Flows For:**
+Looking at the PRD journeys, I need to design detailed interaction flows for:
+
+- [Critical journey 1 identified from PRD narratives]
+- [Critical journey 2 identified from PRD narratives]
+- [Critical journey 3 identified from PRD narratives]
+
+The PRD gave us the stories - now we design the mechanics!"
+
+### 2. Design Each Journey Flow
+
+For each critical journey, design detailed flow:
+
+**For [Journey Name]:**
+"Let's design the flow for users accomplishing [journey goal].
+
+**Flow Design Questions:**
+
+- How do users start this journey? (entry point)
+- What information do they need at each step?
+- What decisions do they need to make?
+- How do they know they're progressing successfully?
+- What does success look like for this journey?
+- Where might they get confused or stuck?
+- How do they recover from errors?"
+
+### 3. Create Flow Diagrams
+
+Visualize each journey with Mermaid diagrams:
+"I'll create detailed flow diagrams for each journey showing:
+
+**[Journey Name] Flow:**
+
+- Entry points and triggers
+- Decision points and branches
+- Success and failure paths
+- Error recovery mechanisms
+- Progressive disclosure of information
+
+Each diagram will map the complete user experience from start to finish."
+
+### 4. Optimize for Efficiency and Delight
+
+Refine flows for optimal user experience:
+"**Flow Optimization:**
+For each journey, let's ensure we're:
+
+- Minimizing steps to value (getting users to success quickly)
+- Reducing cognitive load at each decision point
+- Providing clear feedback and progress indicators
+- Creating moments of delight or accomplishment
+- Handling edge cases and error recovery gracefully
+
+**Specific Optimizations:**
+
+- [Optimization 1 for journey efficiency]
+- [Optimization 2 for user delight]
+- [Optimization 3 for error handling]"
+
+### 5. Document Journey Patterns
+
+Extract reusable patterns across journeys:
+"**Journey Patterns:**
+Across these flows, I'm seeing some common patterns we can standardize:
+
+**Navigation Patterns:**
+
+- [Navigation pattern 1]
+- [Navigation pattern 2]
+
+**Decision Patterns:**
+
+- [Decision pattern 1]
+- [Decision pattern 2]
+
+**Feedback Patterns:**
+
+- [Feedback pattern 1]
+- [Feedback pattern 2]
+
+These patterns will ensure consistency across all user experiences."
+
+### 6. Generate User Journey Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## User Journey Flows
+
+### [Journey 1 Name]
+
+[Journey 1 description and Mermaid diagram]
+
+### [Journey 2 Name]
+
+[Journey 2 description and Mermaid diagram]
+
+### Journey Patterns
+
+[Journey patterns identified based on conversation]
+
+### Flow Optimization Principles
+
+[Flow optimization principles based on conversation]
+```
+
+### 7. Present Content and Menu
+
+Show the generated user journey content and present choices:
+"I've designed detailed user journey flows for {{project_name}}. These flows will guide the detailed design of each user interaction.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine our user journey designs
+[P] Party Mode - Bring different perspectives on user flows
+[C] Continue - Save this to the document and move to component strategy
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current user journey content
+- Process the enhanced journey insights that come back
+- Ask user: "Accept these improvements to the user journeys? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current user journeys
+- Process the collaborative journey insights that come back
+- Ask user: "Accept these changes to the user journeys? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `./step-11-component-strategy.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Critical user journeys identified and designed
+✅ Detailed flow diagrams created for each journey
+✅ Flows optimized for efficiency and user delight
+✅ Common journey patterns extracted and documented
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not identifying all critical user journeys
+❌ Flows too complex or not optimized for user success
+❌ Missing error recovery paths
+❌ Not extracting reusable patterns across journeys
+❌ Flow diagrams unclear or incomplete
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-11-component-strategy.md` to define component library strategy.
+
+Remember: Do NOT proceed to step-11 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-11-component-strategy.md b/.claude/skills/bmad-create-ux-design/steps/step-11-component-strategy.md
new file mode 100644
index 0000000..7692656
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-11-component-strategy.md
@@ -0,0 +1,249 @@
+# Step 11: Component Strategy
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on defining component library strategy and custom components
+- 🎯 COLLABORATIVE component planning, not assumption-based design
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating component strategy content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper component insights
+- **P (Party Mode)**: Bring multiple perspectives to define component strategy
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Design system choice from step 6 determines available components
+- User journeys from step 10 identify component needs
+- Focus on defining custom components and implementation strategy
+
+## YOUR TASK:
+
+Define component library strategy and design custom components not covered by the design system.
+
+## COMPONENT STRATEGY SEQUENCE:
+
+### 1. Analyze Design System Coverage
+
+Review what components are available vs. needed:
+"Based on our chosen design system [design system from step 6], let's identify what components are already available and what we need to create custom.
+
+**Available from Design System:**
+[List of components available in chosen design system]
+
+**Components Needed for {{project_name}}:**
+Looking at our user journeys and design direction, we need:
+
+- [Component need 1 from journey analysis]
+- [Component need 2 from design requirements]
+- [Component need 3 from core experience]
+
+**Gap Analysis:**
+
+- [Gap 1 - needed but not available]
+- [Gap 2 - needed but not available]"
+
+### 2. Design Custom Components
+
+For each custom component needed, design thoroughly:
+
+**For each custom component:**
+"**[Component Name] Design:**
+
+**Purpose:** What does this component do for users?
+**Content:** What information or data does it display?
+**Actions:** What can users do with this component?
+**States:** What different states does it have? (default, hover, active, disabled, error, etc.)
+**Variants:** Are there different sizes or styles needed?
+**Accessibility:** What ARIA labels and keyboard support needed?
+
+Let's walk through each custom component systematically."
+
+### 3. Document Component Specifications
+
+Create detailed specifications for each component:
+
+**Component Specification Template:**
+
+```markdown
+### [Component Name]
+
+**Purpose:** [Clear purpose statement]
+**Usage:** [When and how to use]
+**Anatomy:** [Visual breakdown of parts]
+**States:** [All possible states with descriptions]
+**Variants:** [Different sizes/styles if applicable]
+**Accessibility:** [ARIA labels, keyboard navigation]
+**Content Guidelines:** [What content works best]
+**Interaction Behavior:** [How users interact]
+```
+
+### 4. Define Component Strategy
+
+Establish overall component library approach:
+"**Component Strategy:**
+
+**Foundation Components:** (from design system)
+
+- [Foundation component 1]
+- [Foundation component 2]
+
+**Custom Components:** (designed in this step)
+
+- [Custom component 1 with rationale]
+- [Custom component 2 with rationale]
+
+**Implementation Approach:**
+
+- Build custom components using design system tokens
+- Ensure consistency with established patterns
+- Follow accessibility best practices
+- Create reusable patterns for common use cases"
+
+### 5. Plan Implementation Roadmap
+
+Define how and when to build components:
+"**Implementation Roadmap:**
+
+**Phase 1 - Core Components:**
+
+- [Component 1] - needed for [critical flow]
+- [Component 2] - needed for [critical flow]
+
+**Phase 2 - Supporting Components:**
+
+- [Component 3] - enhances [user experience]
+- [Component 4] - supports [design pattern]
+
+**Phase 3 - Enhancement Components:**
+
+- [Component 5] - optimizes [user journey]
+- [Component 6] - adds [special feature]
+
+This roadmap helps prioritize development based on user journey criticality."
+
+### 6. Generate Component Strategy Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Component Strategy
+
+### Design System Components
+
+[Analysis of available design system components based on conversation]
+
+### Custom Components
+
+[Custom component specifications based on conversation]
+
+### Component Implementation Strategy
+
+[Component implementation strategy based on conversation]
+
+### Implementation Roadmap
+
+[Implementation roadmap based on conversation]
+```
+
+### 7. Present Content and Menu
+
+Show the generated component strategy content and present choices:
+"I've defined the component strategy for {{project_name}}. This balances using proven design system components with custom components for your unique needs.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine our component strategy
+[P] Party Mode - Bring technical perspectives on component design
+[C] Continue - Save this to the document and move to UX patterns
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current component strategy content
+- Process the enhanced component insights that come back
+- Ask user: "Accept these improvements to the component strategy? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current component strategy
+- Process the collaborative component insights that come back
+- Ask user: "Accept these changes to the component strategy? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `./step-12-ux-patterns.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Design system coverage properly analyzed
+✅ All custom components thoroughly specified
+✅ Component strategy clearly defined
+✅ Implementation roadmap prioritized by user need
+✅ Accessibility considered for all components
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not analyzing design system coverage properly
+❌ Custom components not thoroughly specified
+❌ Missing accessibility considerations
+❌ Component strategy not aligned with user journeys
+❌ Implementation roadmap not prioritized effectively
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-12-ux-patterns.md` to define UX consistency patterns.
+
+Remember: Do NOT proceed to step-12 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-12-ux-patterns.md b/.claude/skills/bmad-create-ux-design/steps/step-12-ux-patterns.md
new file mode 100644
index 0000000..08b78d2
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-12-ux-patterns.md
@@ -0,0 +1,238 @@
+# Step 12: UX Consistency Patterns
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on establishing consistency patterns for common UX situations
+- 🎯 COLLABORATIVE pattern definition, not assumption-based design
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating UX patterns content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper pattern insights
+- **P (Party Mode)**: Bring multiple perspectives to define UX patterns
+- **C (Continue)**: Save the content to the document and proceed to next step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Component strategy from step 11 informs pattern decisions
+- User journeys from step 10 identify common pattern needs
+- Focus on consistency patterns for common UX situations
+
+## YOUR TASK:
+
+Establish UX consistency patterns for common situations like buttons, forms, navigation, and feedback.
+
+## UX PATTERNS SEQUENCE:
+
+### 1. Identify Pattern Categories
+
+Determine which patterns need definition for your product:
+"Let's establish consistency patterns for how {{project_name}} behaves in common situations.
+
+**Pattern Categories to Define:**
+
+- Button hierarchy and actions
+- Feedback patterns (success, error, warning, info)
+- Form patterns and validation
+- Navigation patterns
+- Modal and overlay patterns
+- Empty states and loading states
+- Search and filtering patterns
+
+Which categories are most critical for your product? We can go through each thoroughly or focus on the most important ones."
+
+### 2. Define Critical Patterns First
+
+Focus on patterns most relevant to your product:
+
+**For [Critical Pattern Category]:**
+"**[Pattern Type] Patterns:**
+What should users see/do when they need to [pattern action]?
+
+**Considerations:**
+
+- Visual hierarchy (primary vs. secondary actions)
+- Feedback mechanisms
+- Error recovery
+- Accessibility requirements
+- Mobile vs. desktop considerations
+
+**Examples:**
+
+- [Example 1 for this pattern type]
+- [Example 2 for this pattern type]
+
+How should {{project_name}} handle [pattern type] interactions?"
+
+### 3. Establish Pattern Guidelines
+
+Document specific design decisions:
+
+**Pattern Guidelines Template:**
+
+```markdown
+### [Pattern Type]
+
+**When to Use:** [Clear usage guidelines]
+**Visual Design:** [How it should look]
+**Behavior:** [How it should interact]
+**Accessibility:** [A11y requirements]
+**Mobile Considerations:** [Mobile-specific needs]
+**Variants:** [Different states or styles if applicable]
+```
+
+### 4. Design System Integration
+
+Ensure patterns work with chosen design system:
+"**Integration with [Design System]:**
+
+- How do these patterns complement our design system components?
+- What customizations are needed?
+- How do we maintain consistency while meeting unique needs?
+
+**Custom Pattern Rules:**
+
+- [Custom rule 1]
+- [Custom rule 2]
+- [Custom rule 3]"
+
+### 5. Create Pattern Documentation
+
+Generate comprehensive pattern library:
+
+**Pattern Library Structure:**
+
+- Clear usage guidelines for each pattern
+- Visual examples and specifications
+- Implementation notes for developers
+- Accessibility checklists
+- Mobile-first considerations
+
+### 6. Generate UX Patterns Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## UX Consistency Patterns
+
+### Button Hierarchy
+
+[Button hierarchy patterns based on conversation]
+
+### Feedback Patterns
+
+[Feedback patterns based on conversation]
+
+### Form Patterns
+
+[Form patterns based on conversation]
+
+### Navigation Patterns
+
+[Navigation patterns based on conversation]
+
+### Additional Patterns
+
+[Additional patterns based on conversation]
+```
+
+### 7. Present Content and Menu
+
+Show the generated UX patterns content and present choices:
+"I've established UX consistency patterns for {{project_name}}. These patterns ensure users have a consistent, predictable experience across all interactions.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine our UX patterns
+[P] Party Mode - Bring different perspectives on consistency patterns
+[C] Continue - Save this to the document and move to responsive design
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current UX patterns content
+- Process the enhanced pattern insights that come back
+- Ask user: "Accept these improvements to the UX patterns? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current UX patterns
+- Process the collaborative pattern insights that come back
+- Ask user: "Accept these changes to the UX patterns? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `./step-13-responsive-accessibility.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Critical pattern categories identified and prioritized
+✅ Consistency patterns clearly defined and documented
+✅ Patterns integrated with chosen design system
+✅ Accessibility considerations included for all patterns
+✅ Mobile-first approach incorporated
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not identifying the most critical pattern categories
+❌ Patterns too generic or not actionable
+❌ Missing accessibility considerations
+❌ Patterns not aligned with design system
+❌ Not considering mobile differences
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-13-responsive-accessibility.md` to define responsive design and accessibility strategy.
+
+Remember: Do NOT proceed to step-13 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md b/.claude/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md
new file mode 100644
index 0000000..612faa2
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md
@@ -0,0 +1,265 @@
+# Step 13: Responsive Design & Accessibility
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ ALWAYS treat this as collaborative discovery between UX facilitator and stakeholder
+- 📋 YOU ARE A UX FACILITATOR, not a content generator
+- 💬 FOCUS on responsive design strategy and accessibility compliance
+- 🎯 COLLABORATIVE strategy definition, not assumption-based design
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating responsive/accessibility content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted.
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to develop deeper responsive/accessibility insights
+- **P (Party Mode)**: Bring multiple perspectives to define responsive/accessibility strategy
+- **C (Continue)**: Save the content to the document and proceed to final step
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to this step's A/P/C menu
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Platform requirements from step 3 inform responsive design
+- Design direction from step 9 influences responsive layout choices
+- Focus on cross-device adaptation and accessibility compliance
+
+## YOUR TASK:
+
+Define responsive design strategy and accessibility requirements for the product.
+
+## RESPONSIVE & ACCESSIBILITY SEQUENCE:
+
+### 1. Define Responsive Strategy
+
+Establish how the design adapts across devices:
+"Let's define how {{project_name}} adapts across different screen sizes and devices.
+
+**Responsive Design Questions:**
+
+**Desktop Strategy:**
+
+- How should we use extra screen real estate?
+- Multi-column layouts, side navigation, or content density?
+- What desktop-specific features can we include?
+
+**Tablet Strategy:**
+
+- Should we use simplified layouts or touch-optimized interfaces?
+- How do gestures and touch interactions work on tablets?
+- What's the optimal information density for tablet screens?
+
+**Mobile Strategy:**
+
+- Bottom navigation or hamburger menu?
+- How do layouts collapse on small screens?
+- What's the most critical information to show mobile-first?"
+
+### 2. Establish Breakpoint Strategy
+
+Define when and how layouts change:
+"**Breakpoint Strategy:**
+We need to define screen size breakpoints where layouts adapt.
+
+**Common Breakpoints:**
+
+- Mobile: 320px - 767px
+- Tablet: 768px - 1023px
+- Desktop: 1024px+
+
+**For {{project_name}}, should we:**
+
+- Use standard breakpoints or custom ones?
+- Focus on mobile-first or desktop-first design?
+- Have specific breakpoints for your key use cases?"
+
+### 3. Design Accessibility Strategy
+
+Define accessibility requirements and compliance level:
+"**Accessibility Strategy:**
+What level of WCAG compliance does {{project_name}} need?
+
+**WCAG Levels:**
+
+- **Level A (Basic)** - Essential accessibility for legal compliance
+- **Level AA (Recommended)** - Industry standard for good UX
+- **Level AAA (Highest)** - Exceptional accessibility (rarely needed)
+
+**Based on your product:**
+
+- [Recommendation based on user base, legal requirements, etc.]
+
+**Key Accessibility Considerations:**
+
+- Color contrast ratios (4.5:1 for normal text)
+- Keyboard navigation support
+- Screen reader compatibility
+- Touch target sizes (minimum 44x44px)
+- Focus indicators and skip links"
+
+### 4. Define Testing Strategy
+
+Plan how to ensure responsive design and accessibility:
+"**Testing Strategy:**
+
+**Responsive Testing:**
+
+- Device testing on actual phones/tablets
+- Browser testing across Chrome, Firefox, Safari, Edge
+- Real device network performance testing
+
+**Accessibility Testing:**
+
+- Automated accessibility testing tools
+- Screen reader testing (VoiceOver, NVDA, JAWS)
+- Keyboard-only navigation testing
+- Color blindness simulation testing
+
+**User Testing:**
+
+- Include users with disabilities in testing
+- Test with diverse assistive technologies
+- Validate with actual target devices"
+
+### 5. Document Implementation Guidelines
+
+Create specific guidelines for developers:
+"**Implementation Guidelines:**
+
+**Responsive Development:**
+
+- Use relative units (rem, %, vw, vh) over fixed pixels
+- Implement mobile-first media queries
+- Test touch targets and gesture areas
+- Optimize images and assets for different devices
+
+**Accessibility Development:**
+
+- Semantic HTML structure
+- ARIA labels and roles
+- Keyboard navigation implementation
+- Focus management and skip links
+- High contrast mode support"
+
+### 6. Generate Responsive & Accessibility Content
+
+Prepare the content to append to the document:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Responsive Design & Accessibility
+
+### Responsive Strategy
+
+[Responsive strategy based on conversation]
+
+### Breakpoint Strategy
+
+[Breakpoint strategy based on conversation]
+
+### Accessibility Strategy
+
+[Accessibility strategy based on conversation]
+
+### Testing Strategy
+
+[Testing strategy based on conversation]
+
+### Implementation Guidelines
+
+[Implementation guidelines based on conversation]
+```
+
+### 7. Present Content and Menu
+
+Show the generated responsive and accessibility content and present choices:
+"I've defined the responsive design and accessibility strategy for {{project_name}}. This ensures your product works beautifully across all devices and is accessible to all users.
+
+**Here's what I'll add to the document:**
+
+[Show the complete markdown content from step 6]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Let's refine our responsive/accessibility strategy
+[P] Party Mode - Bring different perspectives on inclusive design
+[C] Continue - Save this to the document and complete the workflow
+
+### 8. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with the current responsive/accessibility content
+- Process the enhanced insights that come back
+- Ask user: "Accept these improvements to the responsive/accessibility strategy? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with the current responsive/accessibility strategy
+- Process the collaborative insights that come back
+- Ask user: "Accept these changes to the responsive/accessibility strategy? (y/n)"
+- If yes: Update content with improvements, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Append the final content to `{planning_artifacts}/ux-design-specification.md`
+- Update frontmatter: append step to end of stepsCompleted array
+- Load `./step-14-complete.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the document using the structure from step 6.
+
+## SUCCESS METRICS:
+
+✅ Responsive strategy clearly defined for all device types
+✅ Appropriate breakpoint strategy established
+✅ Accessibility requirements determined and documented
+✅ Comprehensive testing strategy planned
+✅ Implementation guidelines provided for Developer agent
+✅ A/P/C menu presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Not considering all device types and screen sizes
+❌ Accessibility requirements not properly researched
+❌ Testing strategy not comprehensive enough
+❌ Implementation guidelines too generic or unclear
+❌ Not addressing specific accessibility challenges for your product
+❌ Not presenting A/P/C menu after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-14-complete.md` to finalize the UX design workflow.
+
+Remember: Do NOT proceed to step-14 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/.claude/skills/bmad-create-ux-design/steps/step-14-complete.md b/.claude/skills/bmad-create-ux-design/steps/step-14-complete.md
new file mode 100644
index 0000000..67d99c4
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/steps/step-14-complete.md
@@ -0,0 +1,171 @@
+# Step 14: Workflow Completion
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- ✅ THIS IS A FINAL STEP - Workflow completion required
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- 🛑 NO content generation - this is a wrap-up step
+- 📋 FINALIZE document and update workflow status
+- 💬 FOCUS on completion, validation, and next steps
+- 🎯 UPDATE workflow status files with completion information
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 💾 Update the main workflow status file with completion information
+- 📖 Suggest potential next workflow steps for the user
+- 🚫 DO NOT load additional steps after this one
+
+## TERMINATION STEP PROTOCOLS:
+
+- This is a FINAL step - workflow completion required
+- 📖 Update output file frontmatter, adding this step to the end of the list of stepsCompleted to indicate all is finished..
+- Output completion summary and next step guidance
+- Update the main workflow status file with finalized document
+- Suggest potential next workflow steps for the user
+- Mark workflow as complete in status tracking
+
+## CONTEXT BOUNDARIES:
+
+- Complete UX design specification is available from all previous steps
+- Workflow frontmatter shows all completed steps
+- All collaborative content has been generated and saved
+- Focus on completion, validation, and next steps
+
+## YOUR TASK:
+
+Complete the UX design workflow, update status files, and suggest next steps for the project.
+
+## WORKFLOW COMPLETION SEQUENCE:
+
+### 1. Announce Workflow Completion
+
+Inform user that the UX design is complete:
+"🎉 **UX Design Complete, {{user_name}}!**
+
+I've successfully collaborated with you to create a comprehensive UX design specification for {{project_name}}.
+
+**What we've accomplished:**
+
+- ✅ Project understanding and user insights
+- ✅ Core experience and emotional response definition
+- ✅ UX pattern analysis and inspiration
+- ✅ Design system choice and implementation strategy
+- ✅ Core interaction definition and experience mechanics
+- ✅ Visual design foundation (colors, typography, spacing)
+- ✅ Design direction mockups and visual explorations
+- ✅ User journey flows and interaction design
+- ✅ Component strategy and custom component specifications
+- ✅ UX consistency patterns for common interactions
+- ✅ Responsive design and accessibility strategy
+
+**The complete UX design specification is now available at:** `{planning_artifacts}/ux-design-specification.md`
+
+**Supporting Visual Assets:**
+
+- Color themes visualizer: `{planning_artifacts}/ux-color-themes.html`
+- Design directions mockups: `{planning_artifacts}/ux-design-directions.html`
+
+This specification is now ready to guide visual design, implementation, and development."
+
+### 2. Workflow Status Update
+
+Update the main workflow status file:
+
+- Load the project's workflow status file (if one exists)
+- Update workflow_status["create-ux-design"] = `{planning_artifacts}/ux-design-specification.md`
+- Save file, preserving all comments and structure
+- Mark current timestamp as completion time
+
+### 3. Suggest Next Steps
+
+UX Design complete. Invoke the `bmad-help` skill.
+
+### 5. Final Completion Confirmation
+
+Congratulate the user on the completion you both completed together of the UX.
+
+
+
+## SUCCESS METRICS:
+
+✅ UX design specification contains all required sections
+✅ All collaborative content properly saved to document
+✅ Workflow status file updated with completion information
+✅ Clear next step guidance provided to user
+✅ Document quality validation completed
+✅ User acknowledges completion and understands next options
+
+## FAILURE MODES:
+
+❌ Not updating workflow status file with completion information
+❌ Missing clear next step guidance for user
+❌ Not confirming document completeness with user
+❌ Workflow not properly marked as complete in status tracking
+❌ User unclear about what happens next
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## WORKFLOW COMPLETION CHECKLIST:
+
+### Design Specification Complete:
+
+- [ ] Executive summary and project understanding
+- [ ] Core experience and emotional response definition
+- [ ] UX pattern analysis and inspiration
+- [ ] Design system choice and strategy
+- [ ] Core interaction mechanics definition
+- [ ] Visual design foundation (colors, typography, spacing)
+- [ ] Design direction decisions and mockups
+- [ ] User journey flows and interaction design
+- [ ] Component strategy and specifications
+- [ ] UX consistency patterns documentation
+- [ ] Responsive design and accessibility strategy
+
+### Process Complete:
+
+- [ ] All steps completed with user confirmation
+- [ ] All content saved to specification document
+- [ ] Frontmatter properly updated with all steps
+- [ ] Workflow status file updated with completion
+- [ ] Next steps clearly communicated
+
+## NEXT STEPS GUIDANCE:
+
+**Immediate Options:**
+
+1. **Wireframe Generation** - Create low-fidelity layouts based on UX spec
+2. **Interactive Prototype** - Build clickable prototypes for testing
+3. **Solution Architecture** - Technical design with UX context
+4. **Figma Visual Design** - High-fidelity UI implementation
+5. **Epic Creation** - Break down UX requirements for development
+
+**Recommended Sequence:**
+For design-focused teams: Wireframes → Prototypes → Figma Design → Development
+For technical teams: Architecture → Epic Creation → Development
+
+Consider team capacity, timeline, and whether user validation is needed before implementation.
+
+## WORKFLOW FINALIZATION:
+
+- Set `lastStep = 14` in document frontmatter
+- Update workflow status file with completion timestamp
+- Provide completion summary to user
+- Do NOT load any additional steps
+
+## FINAL REMINDER:
+
+This UX design workflow is now complete. The specification serves as the foundation for all visual and development work. All design decisions, patterns, and requirements are documented to ensure consistent, accessible, and user-centered implementation.
+
+**Congratulations on completing the UX Design Specification for {{project_name}}!** 🎉
+
+**Core Deliverables:**
+
+- ✅ UX Design Specification: `{planning_artifacts}/ux-design-specification.md`
+- ✅ Color Themes Visualizer: `{planning_artifacts}/ux-color-themes.html`
+- ✅ Design Directions: `{planning_artifacts}/ux-design-directions.html`
diff --git a/.claude/skills/bmad-create-ux-design/ux-design-template.md b/.claude/skills/bmad-create-ux-design/ux-design-template.md
new file mode 100644
index 0000000..aeed9dc
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/ux-design-template.md
@@ -0,0 +1,13 @@
+---
+stepsCompleted: []
+inputDocuments: []
+---
+
+# UX Design Specification {{project_name}}
+
+**Author:** {{user_name}}
+**Date:** {{date}}
+
+---
+
+<!-- UX design content will be appended sequentially through collaborative workflow steps -->
diff --git a/.claude/skills/bmad-create-ux-design/workflow.md b/.claude/skills/bmad-create-ux-design/workflow.md
new file mode 100644
index 0000000..8ca55f1
--- /dev/null
+++ b/.claude/skills/bmad-create-ux-design/workflow.md
@@ -0,0 +1,35 @@
+# Create UX Design Workflow
+
+**Goal:** Create comprehensive UX design specifications through collaborative visual exploration and informed decision-making where you act as a UX facilitator working with a product stakeholder.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- Document state tracked in frontmatter
+- Append-only document building through conversation
+
+---
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+### Paths
+
+- `default_output_file` = `{planning_artifacts}/ux-design-specification.md`
+
+## EXECUTION
+
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+- Read fully and follow: `./steps/step-01-init.md` to begin the UX design workflow.
diff --git a/.claude/skills/bmad-dev-story/SKILL.md b/.claude/skills/bmad-dev-story/SKILL.md
new file mode 100644
index 0000000..0eb505c
--- /dev/null
+++ b/.claude/skills/bmad-dev-story/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-dev-story
+description: 'Execute story implementation following a context filled story spec file. Use when the user says "dev this story [story file]" or "implement the next story in the sprint plan"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-dev-story/checklist.md b/.claude/skills/bmad-dev-story/checklist.md
new file mode 100644
index 0000000..86d6e9b
--- /dev/null
+++ b/.claude/skills/bmad-dev-story/checklist.md
@@ -0,0 +1,80 @@
+---
+title: 'Enhanced Dev Story Definition of Done Checklist'
+validation-target: 'Story markdown ({{story_path}})'
+validation-criticality: 'HIGHEST'
+required-inputs:
+  - 'Story markdown file with enhanced Dev Notes containing comprehensive implementation context'
+  - 'Completed Tasks/Subtasks section with all items marked [x]'
+  - 'Updated File List section with all changed files'
+  - 'Updated Dev Agent Record with implementation notes'
+optional-inputs:
+  - 'Test results output'
+  - 'CI logs'
+  - 'Linting reports'
+validation-rules:
+  - 'Only permitted story sections modified: Tasks/Subtasks checkboxes, Dev Agent Record, File List, Change Log, Status'
+  - 'All implementation requirements from story Dev Notes must be satisfied'
+  - 'Definition of Done checklist must pass completely'
+  - 'Enhanced story context must contain sufficient technical guidance'
+---
+
+# 🎯 Enhanced Definition of Done Checklist
+
+**Critical validation:** Story is truly ready for review only when ALL items below are satisfied
+
+## 📋 Context & Requirements Validation
+
+- [ ] **Story Context Completeness:** Dev Notes contains ALL necessary technical requirements, architecture patterns, and implementation guidance
+- [ ] **Architecture Compliance:** Implementation follows all architectural requirements specified in Dev Notes
+- [ ] **Technical Specifications:** All technical specifications (libraries, frameworks, versions) from Dev Notes are implemented correctly
+- [ ] **Previous Story Learnings:** Previous story insights incorporated (if applicable) and build upon appropriately
+
+## ✅ Implementation Completion
+
+- [ ] **All Tasks Complete:** Every task and subtask marked complete with [x]
+- [ ] **Acceptance Criteria Satisfaction:** Implementation satisfies EVERY Acceptance Criterion in the story
+- [ ] **No Ambiguous Implementation:** Clear, unambiguous implementation that meets story requirements
+- [ ] **Edge Cases Handled:** Error conditions and edge cases appropriately addressed
+- [ ] **Dependencies Within Scope:** Only uses dependencies specified in story or project-context.md
+
+## 🧪 Testing & Quality Assurance
+
+- [ ] **Unit Tests:** Unit tests added/updated for ALL core functionality introduced/changed by this story
+- [ ] **Integration Tests:** Integration tests added/updated for component interactions when story requirements demand them
+- [ ] **End-to-End Tests:** End-to-end tests created for critical user flows when story requirements specify them
+- [ ] **Test Coverage:** Tests cover acceptance criteria and edge cases from story Dev Notes
+- [ ] **Regression Prevention:** ALL existing tests pass (no regressions introduced)
+- [ ] **Code Quality:** Linting and static checks pass when configured in project
+- [ ] **Test Framework Compliance:** Tests use project's testing frameworks and patterns from Dev Notes
+
+## 📝 Documentation & Tracking
+
+- [ ] **File List Complete:** File List includes EVERY new, modified, or deleted file (paths relative to repo root)
+- [ ] **Dev Agent Record Updated:** Contains relevant Implementation Notes and/or Debug Log for this work
+- [ ] **Change Log Updated:** Change Log includes clear summary of what changed and why
+- [ ] **Review Follow-ups:** All review follow-up tasks (marked [AI-Review]) completed and corresponding review items marked resolved (if applicable)
+- [ ] **Story Structure Compliance:** Only permitted sections of story file were modified
+
+## 🔚 Final Status Verification
+
+- [ ] **Story Status Updated:** Story Status set to "review"
+- [ ] **Sprint Status Updated:** Sprint status updated to "review" (when sprint tracking is used)
+- [ ] **Quality Gates Passed:** All quality checks and validations completed successfully
+- [ ] **No HALT Conditions:** No blocking issues or incomplete work remaining
+- [ ] **User Communication Ready:** Implementation summary prepared for user review
+
+## 🎯 Final Validation Output
+
+```
+Definition of Done: {{PASS/FAIL}}
+
+✅ **Story Ready for Review:** {{story_key}}
+📊 **Completion Score:** {{completed_items}}/{{total_items}} items passed
+🔍 **Quality Gates:** {{quality_gates_status}}
+📋 **Test Results:** {{test_results_summary}}
+📝 **Documentation:** {{documentation_status}}
+```
+
+**If FAIL:** List specific failures and required actions before story can be marked Ready for Review
+
+**If PASS:** Story is fully ready for code review and production consideration
diff --git a/.claude/skills/bmad-dev-story/workflow.md b/.claude/skills/bmad-dev-story/workflow.md
new file mode 100644
index 0000000..4164479
--- /dev/null
+++ b/.claude/skills/bmad-dev-story/workflow.md
@@ -0,0 +1,450 @@
+# Dev Story Workflow
+
+**Goal:** Execute story implementation following a context filled story spec file.
+
+**Your Role:** Developer implementing the story.
+- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
+- Generate all documents in {document_output_language}
+- Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List, Change Log, and Status
+- Execute ALL steps in exact order; do NOT skip steps
+- Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives other instruction.
+- Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.
+- User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `implementation_artifacts`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `story_file` = `` (explicit story path; auto-discovered if empty)
+- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+<workflow>
+  <critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
+  <critical>Generate all documents in {document_output_language}</critical>
+  <critical>Only modify the story file in these areas: Tasks/Subtasks checkboxes, Dev Agent Record (Debug Log, Completion Notes), File List,
+    Change Log, and Status</critical>
+  <critical>Execute ALL steps in exact order; do NOT skip steps</critical>
+  <critical>Absolutely DO NOT stop because of "milestones", "significant progress", or "session boundaries". Continue in a single execution
+    until the story is COMPLETE (all ACs satisfied and all tasks/subtasks checked) UNLESS a HALT condition is triggered or the USER gives
+    other instruction.</critical>
+  <critical>Do NOT schedule a "next session" or request review pauses unless a HALT condition applies. Only Step 6 decides completion.</critical>
+  <critical>User skill level ({user_skill_level}) affects conversation style ONLY, not code updates.</critical>
+
+  <step n="1" goal="Find next ready story and load it" tag="sprint-status">
+    <check if="{{story_path}} is provided">
+      <action>Use {{story_path}} directly</action>
+      <action>Read COMPLETE story file</action>
+      <action>Extract story_key from filename or metadata</action>
+      <goto anchor="task_check" />
+    </check>
+
+    <!-- Sprint-based story discovery -->
+    <check if="{{sprint_status}} file exists">
+      <critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
+      <action>Load the FULL file: {{sprint_status}}</action>
+      <action>Read ALL lines from beginning to end - do not skip any content</action>
+      <action>Parse the development_status section completely to understand story order</action>
+
+      <action>Find the FIRST story (by reading in order from top to bottom) where:
+        - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
+        - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
+        - Status value equals "ready-for-dev"
+      </action>
+
+      <check if="no ready-for-dev or in-progress story found">
+        <output>📋 No ready-for-dev stories found in sprint-status.yaml
+
+          **Current Sprint Status:** {{sprint_status_summary}}
+
+          **What would you like to do?**
+          1. Run `create-story` to create next story from epics with comprehensive context
+          2. Run `*validate-create-story` to improve existing stories before development (recommended quality check)
+          3. Specify a particular story file to develop (provide full path)
+          4. Check {{sprint_status}} file to see current sprint status
+
+          💡 **Tip:** Stories in `ready-for-dev` may not have been validated. Consider running `validate-create-story` first for a quality
+          check.
+        </output>
+        <ask>Choose option [1], [2], [3], or [4], or specify story file path:</ask>
+
+        <check if="user chooses '1'">
+          <action>HALT - Run create-story to create next story</action>
+        </check>
+
+        <check if="user chooses '2'">
+          <action>HALT - Run validate-create-story to improve existing stories</action>
+        </check>
+
+        <check if="user chooses '3'">
+          <ask>Provide the story file path to develop:</ask>
+          <action>Store user-provided story path as {{story_path}}</action>
+          <goto anchor="task_check" />
+        </check>
+
+        <check if="user chooses '4'">
+          <output>Loading {{sprint_status}} for detailed status review...</output>
+          <action>Display detailed sprint status analysis</action>
+          <action>HALT - User can review sprint status and provide story path</action>
+        </check>
+
+        <check if="user provides story file path">
+          <action>Store user-provided story path as {{story_path}}</action>
+          <goto anchor="task_check" />
+        </check>
+      </check>
+    </check>
+
+    <!-- Non-sprint story discovery -->
+    <check if="{{sprint_status}} file does NOT exist">
+      <action>Search {implementation_artifacts} for stories directly</action>
+      <action>Find stories with "ready-for-dev" status in files</action>
+      <action>Look for story files matching pattern: *-*-*.md</action>
+      <action>Read each candidate story file to check Status section</action>
+
+      <check if="no ready-for-dev stories found in story files">
+        <output>📋 No ready-for-dev stories found
+
+          **Available Options:**
+          1. Run `create-story` to create next story from epics with comprehensive context
+          2. Run `*validate-create-story` to improve existing stories
+          3. Specify which story to develop
+        </output>
+        <ask>What would you like to do? Choose option [1], [2], or [3]:</ask>
+
+        <check if="user chooses '1'">
+          <action>HALT - Run create-story to create next story</action>
+        </check>
+
+        <check if="user chooses '2'">
+          <action>HALT - Run validate-create-story to improve existing stories</action>
+        </check>
+
+        <check if="user chooses '3'">
+          <ask>It's unclear what story you want developed. Please provide the full path to the story file:</ask>
+          <action>Store user-provided story path as {{story_path}}</action>
+          <action>Continue with provided story file</action>
+        </check>
+      </check>
+
+      <check if="ready-for-dev story found in files">
+        <action>Use discovered story file and extract story_key</action>
+      </check>
+    </check>
+
+    <action>Store the found story_key (e.g., "1-2-user-authentication") for later status updates</action>
+    <action>Find matching story file in {implementation_artifacts} using story_key pattern: {{story_key}}.md</action>
+    <action>Read COMPLETE story file from discovered path</action>
+
+    <anchor id="task_check" />
+
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
+
+    <action>Load comprehensive context from story file's Dev Notes section</action>
+    <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
+    <action>Use enhanced story context to inform implementation decisions and approaches</action>
+
+    <action>Identify first incomplete task (unchecked [ ]) in Tasks/Subtasks</action>
+
+    <action if="no incomplete tasks">
+      <goto step="6">Completion sequence</goto>
+    </action>
+    <action if="story file inaccessible">HALT: "Cannot develop story without access to story file"</action>
+    <action if="incomplete task or subtask requirements ambiguous">ASK user to clarify or HALT</action>
+  </step>
+
+  <step n="2" goal="Load project context and story information">
+    <critical>Load all available context to inform implementation</critical>
+
+    <action>Load {project_context} for coding standards and project-wide patterns (if exists)</action>
+    <action>Parse sections: Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Dev Agent Record, File List, Change Log, Status</action>
+    <action>Load comprehensive context from story file's Dev Notes section</action>
+    <action>Extract developer guidance from Dev Notes: architecture requirements, previous learnings, technical specifications</action>
+    <action>Use enhanced story context to inform implementation decisions and approaches</action>
+    <output>✅ **Context Loaded**
+      Story and project context available for implementation
+    </output>
+  </step>
+
+  <step n="3" goal="Detect review continuation and extract review context">
+    <critical>Determine if this is a fresh start or continuation after code review</critical>
+
+    <action>Check if "Senior Developer Review (AI)" section exists in the story file</action>
+    <action>Check if "Review Follow-ups (AI)" subsection exists under Tasks/Subtasks</action>
+
+    <check if="Senior Developer Review section exists">
+      <action>Set review_continuation = true</action>
+      <action>Extract from "Senior Developer Review (AI)" section:
+        - Review outcome (Approve/Changes Requested/Blocked)
+        - Review date
+        - Total action items with checkboxes (count checked vs unchecked)
+        - Severity breakdown (High/Med/Low counts)
+      </action>
+      <action>Count unchecked [ ] review follow-up tasks in "Review Follow-ups (AI)" subsection</action>
+      <action>Store list of unchecked review items as {{pending_review_items}}</action>
+
+      <output>⏯️ **Resuming Story After Code Review** ({{review_date}})
+
+        **Review Outcome:** {{review_outcome}}
+        **Action Items:** {{unchecked_review_count}} remaining to address
+        **Priorities:** {{high_count}} High, {{med_count}} Medium, {{low_count}} Low
+
+        **Strategy:** Will prioritize review follow-up tasks (marked [AI-Review]) before continuing with regular tasks.
+      </output>
+    </check>
+
+    <check if="Senior Developer Review section does NOT exist">
+      <action>Set review_continuation = false</action>
+      <action>Set {{pending_review_items}} = empty</action>
+
+      <output>🚀 **Starting Fresh Implementation**
+
+        Story: {{story_key}}
+        Story Status: {{current_status}}
+        First incomplete task: {{first_task_description}}
+      </output>
+    </check>
+  </step>
+
+  <step n="4" goal="Mark story in-progress" tag="sprint-status">
+    <check if="{{sprint_status}} file exists">
+      <action>Load the FULL file: {{sprint_status}}</action>
+      <action>Read all development_status entries to find {{story_key}}</action>
+      <action>Get current status value for development_status[{{story_key}}]</action>
+
+      <check if="current status == 'ready-for-dev' OR review_continuation == true">
+        <action>Update the story in the sprint status report to = "in-progress"</action>
+        <action>Update last_updated field to current date</action>
+        <output>🚀 Starting work on story {{story_key}}
+          Status updated: ready-for-dev → in-progress
+        </output>
+      </check>
+
+      <check if="current status == 'in-progress'">
+        <output>⏯️ Resuming work on story {{story_key}}
+          Story is already marked in-progress
+        </output>
+      </check>
+
+      <check if="current status is neither ready-for-dev nor in-progress">
+        <output>⚠️ Unexpected story status: {{current_status}}
+          Expected ready-for-dev or in-progress. Continuing anyway...
+        </output>
+      </check>
+
+      <action>Store {{current_sprint_status}} for later use</action>
+    </check>
+
+    <check if="{{sprint_status}} file does NOT exist">
+      <output>ℹ️ No sprint status file exists - story progress will be tracked in story file only</output>
+      <action>Set {{current_sprint_status}} = "no-sprint-tracking"</action>
+    </check>
+  </step>
+
+  <step n="5" goal="Implement task following red-green-refactor cycle">
+    <critical>FOLLOW THE STORY FILE TASKS/SUBTASKS SEQUENCE EXACTLY AS WRITTEN - NO DEVIATION</critical>
+
+    <action>Review the current task/subtask from the story file - this is your authoritative implementation guide</action>
+    <action>Plan implementation following red-green-refactor cycle</action>
+
+    <!-- RED PHASE -->
+    <action>Write FAILING tests first for the task/subtask functionality</action>
+    <action>Confirm tests fail before implementation - this validates test correctness</action>
+
+    <!-- GREEN PHASE -->
+    <action>Implement MINIMAL code to make tests pass</action>
+    <action>Run tests to confirm they now pass</action>
+    <action>Handle error conditions and edge cases as specified in task/subtask</action>
+
+    <!-- REFACTOR PHASE -->
+    <action>Improve code structure while keeping tests green</action>
+    <action>Ensure code follows architecture patterns and coding standards from Dev Notes</action>
+
+    <action>Document technical approach and decisions in Dev Agent Record → Implementation Plan</action>
+
+    <action if="new dependencies required beyond story specifications">HALT: "Additional dependencies need user approval"</action>
+    <action if="3 consecutive implementation failures occur">HALT and request guidance</action>
+    <action if="required configuration is missing">HALT: "Cannot proceed without necessary configuration files"</action>
+
+    <critical>NEVER implement anything not mapped to a specific task/subtask in the story file</critical>
+    <critical>NEVER proceed to next task until current task/subtask is complete AND tests pass</critical>
+    <critical>Execute continuously without pausing until all tasks/subtasks are complete or explicit HALT condition</critical>
+    <critical>Do NOT propose to pause for review until Step 9 completion gates are satisfied</critical>
+  </step>
+
+  <step n="6" goal="Author comprehensive tests">
+    <action>Create unit tests for business logic and core functionality introduced/changed by the task</action>
+    <action>Add integration tests for component interactions specified in story requirements</action>
+    <action>Include end-to-end tests for critical user flows when story requirements demand them</action>
+    <action>Cover edge cases and error handling scenarios identified in story Dev Notes</action>
+  </step>
+
+  <step n="7" goal="Run validations and tests">
+    <action>Determine how to run tests for this repo (infer test framework from project structure)</action>
+    <action>Run all existing tests to ensure no regressions</action>
+    <action>Run the new tests to verify implementation correctness</action>
+    <action>Run linting and code quality checks if configured in project</action>
+    <action>Validate implementation meets ALL story acceptance criteria; enforce quantitative thresholds explicitly</action>
+    <action if="regression tests fail">STOP and fix before continuing - identify breaking changes immediately</action>
+    <action if="new tests fail">STOP and fix before continuing - ensure implementation correctness</action>
+  </step>
+
+  <step n="8" goal="Validate and mark task complete ONLY when fully done">
+    <critical>NEVER mark a task complete unless ALL conditions are met - NO LYING OR CHEATING</critical>
+
+    <!-- VALIDATION GATES -->
+    <action>Verify ALL tests for this task/subtask ACTUALLY EXIST and PASS 100%</action>
+    <action>Confirm implementation matches EXACTLY what the task/subtask specifies - no extra features</action>
+    <action>Validate that ALL acceptance criteria related to this task are satisfied</action>
+    <action>Run full test suite to ensure NO regressions introduced</action>
+
+    <!-- REVIEW FOLLOW-UP HANDLING -->
+    <check if="task is review follow-up (has [AI-Review] prefix)">
+      <action>Extract review item details (severity, description, related AC/file)</action>
+      <action>Add to resolution tracking list: {{resolved_review_items}}</action>
+
+      <!-- Mark task in Review Follow-ups section -->
+      <action>Mark task checkbox [x] in "Tasks/Subtasks → Review Follow-ups (AI)" section</action>
+
+      <!-- CRITICAL: Also mark corresponding action item in review section -->
+      <action>Find matching action item in "Senior Developer Review (AI) → Action Items" section by matching description</action>
+      <action>Mark that action item checkbox [x] as resolved</action>
+
+      <action>Add to Dev Agent Record → Completion Notes: "✅ Resolved review finding [{{severity}}]: {{description}}"</action>
+    </check>
+
+    <!-- ONLY MARK COMPLETE IF ALL VALIDATION PASS -->
+    <check if="ALL validation gates pass AND tests ACTUALLY exist and pass">
+      <action>ONLY THEN mark the task (and subtasks) checkbox with [x]</action>
+      <action>Update File List section with ALL new, modified, or deleted files (paths relative to repo root)</action>
+      <action>Add completion notes to Dev Agent Record summarizing what was ACTUALLY implemented and tested</action>
+    </check>
+
+    <check if="ANY validation fails">
+      <action>DO NOT mark task complete - fix issues first</action>
+      <action>HALT if unable to fix validation failures</action>
+    </check>
+
+    <check if="review_continuation == true and {{resolved_review_items}} is not empty">
+      <action>Count total resolved review items in this session</action>
+      <action>Add Change Log entry: "Addressed code review findings - {{resolved_count}} items resolved (Date: {{date}})"</action>
+    </check>
+
+    <action>Save the story file</action>
+    <action>Determine if more incomplete tasks remain</action>
+    <action if="more tasks remain">
+      <goto step="5">Next task</goto>
+    </action>
+    <action if="no tasks remain">
+      <goto step="9">Completion</goto>
+    </action>
+  </step>
+
+  <step n="9" goal="Story completion and mark for review" tag="sprint-status">
+    <action>Verify ALL tasks and subtasks are marked [x] (re-scan the story document now)</action>
+    <action>Run the full regression suite (do not skip)</action>
+    <action>Confirm File List includes every changed file</action>
+    <action>Execute enhanced definition-of-done validation</action>
+    <action>Update the story Status to: "review"</action>
+
+    <!-- Enhanced Definition of Done Validation -->
+    <action>Validate definition-of-done checklist with essential requirements:
+      - All tasks/subtasks marked complete with [x]
+      - Implementation satisfies every Acceptance Criterion
+      - Unit tests for core functionality added/updated
+      - Integration tests for component interactions added when required
+      - End-to-end tests for critical flows added when story demands them
+      - All tests pass (no regressions, new tests successful)
+      - Code quality checks pass (linting, static analysis if configured)
+      - File List includes every new/modified/deleted file (relative paths)
+      - Dev Agent Record contains implementation notes
+      - Change Log includes summary of changes
+      - Only permitted story sections were modified
+    </action>
+
+    <!-- Mark story ready for review - sprint status conditional -->
+    <check if="{sprint_status} file exists AND {{current_sprint_status}} != 'no-sprint-tracking'">
+      <action>Load the FULL file: {sprint_status}</action>
+      <action>Find development_status key matching {{story_key}}</action>
+      <action>Verify current status is "in-progress" (expected previous state)</action>
+      <action>Update development_status[{{story_key}}] = "review"</action>
+      <action>Update last_updated field to current date</action>
+      <action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+      <output>✅ Story status updated to "review" in sprint-status.yaml</output>
+    </check>
+
+    <check if="{sprint_status} file does NOT exist OR {{current_sprint_status}} == 'no-sprint-tracking'">
+      <output>ℹ️ Story status updated to "review" in story file (no sprint tracking configured)</output>
+    </check>
+
+    <check if="story key not found in sprint status">
+      <output>⚠️ Story file updated, but sprint-status update failed: {{story_key}} not found
+
+        Story status is set to "review" in file, but sprint-status.yaml may be out of sync.
+      </output>
+    </check>
+
+    <!-- Final validation gates -->
+    <action if="any task is incomplete">HALT - Complete remaining tasks before marking ready for review</action>
+    <action if="regression failures exist">HALT - Fix regression issues before completing</action>
+    <action if="File List is incomplete">HALT - Update File List with all changed files</action>
+    <action if="definition-of-done validation fails">HALT - Address DoD failures before completing</action>
+  </step>
+
+  <step n="10" goal="Completion communication and user support">
+    <action>Execute the enhanced definition-of-done checklist using the validation framework</action>
+    <action>Prepare a concise summary in Dev Agent Record → Completion Notes</action>
+
+    <action>Communicate to {user_name} that story implementation is complete and ready for review</action>
+    <action>Summarize key accomplishments: story ID, story key, title, key changes made, tests added, files modified</action>
+    <action>Provide the story file path and current status (now "review")</action>
+
+    <action>Based on {user_skill_level}, ask if user needs any explanations about:
+      - What was implemented and how it works
+      - Why certain technical decisions were made
+      - How to test or verify the changes
+      - Any patterns, libraries, or approaches used
+      - Anything else they'd like clarified
+    </action>
+
+    <check if="user asks for explanations">
+      <action>Provide clear, contextual explanations tailored to {user_skill_level}</action>
+      <action>Use examples and references to specific code when helpful</action>
+    </check>
+
+    <action>Once explanations are complete (or user indicates no questions), suggest logical next steps</action>
+    <action>Recommended next steps (flexible based on project setup):
+      - Review the implemented story and test the changes
+      - Verify all acceptance criteria are met
+      - Ensure deployment readiness if applicable
+      - Run `code-review` workflow for peer review
+      - Optional: If Test Architect module installed, run `/bmad:tea:automate` to expand guardrail tests
+    </action>
+
+    <output>💡 **Tip:** For best results, run `code-review` using a **different** LLM than the one that implemented this story.</output>
+    <check if="{sprint_status} file exists">
+      <action>Suggest checking {sprint_status} to see project progress</action>
+    </check>
+    <action>Remain flexible - allow user to choose their own path or ask for other assistance</action>
+  </step>
+
+</workflow>
diff --git a/.claude/skills/bmad-distillator/SKILL.md b/.claude/skills/bmad-distillator/SKILL.md
new file mode 100644
index 0000000..57c44d0
--- /dev/null
+++ b/.claude/skills/bmad-distillator/SKILL.md
@@ -0,0 +1,177 @@
+---
+name: bmad-distillator
+description: Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'.
+---
+
+# Distillator: A Document Distillation Engine
+
+## Overview
+
+This skill produces hyper-compressed, token-efficient documents (distillates) from any set of source documents. A distillate preserves every fact, decision, constraint, and relationship from the sources while stripping all overhead that humans need and LLMs don't. Act as an information extraction and compression specialist. The output is a single dense document (or semantically-split set) that a downstream LLM workflow can consume as sole context input without information loss.
+
+This is a compression task, not a summarization task. Summaries are lossy. Distillates are lossless compression optimized for LLM consumption.
+
+## On Activation
+
+1. **Validate inputs.** The caller must provide:
+   - **source_documents** (required) — One or more file paths, folder paths, or glob patterns to distill
+   - **downstream_consumer** (optional) — What workflow/agent consumes this distillate (e.g., "PRD creation", "architecture design"). When provided, use it to judge signal vs noise. When omitted, preserve everything.
+   - **token_budget** (optional) — Approximate target size. When provided and the distillate would exceed it, trigger semantic splitting.
+   - **output_path** (optional) — Where to save. When omitted, save adjacent to the primary source document with `-distillate.md` suffix.
+   - **--validate** (flag) — Run round-trip reconstruction test after producing the distillate.
+
+2. **Route** — proceed to Stage 1.
+
+## Stages
+
+| # | Stage | Purpose |
+|---|-------|---------|
+| 1 | Analyze | Run analysis script, determine routing and splitting |
+| 2 | Compress | Spawn compressor agent(s) to produce the distillate |
+| 3 | Verify & Output | Completeness check, format check, save output |
+| 4 | Round-Trip Validate | (--validate only) Reconstruct and diff against originals |
+
+### Stage 1: Analyze
+
+Run `scripts/analyze_sources.py --help` then run it with the source paths. Use its routing recommendation and grouping output to drive Stage 2. Do NOT read the source documents yourself.
+
+### Stage 2: Compress
+
+**Single mode** (routing = `"single"`, ≤3 files, ≤15K estimated tokens):
+
+Spawn one subagent using `agents/distillate-compressor.md` with all source file paths.
+
+**Fan-out mode** (routing = `"fan-out"`):
+
+1. Spawn one compressor subagent per group from the analysis output. Each compressor receives only its group's file paths and produces an intermediate distillate.
+
+2. After all compressors return, spawn one final **merge compressor** subagent using `agents/distillate-compressor.md`. Pass it the intermediate distillate contents as its input (not the original files). Its job is cross-group deduplication, thematic regrouping, and final compression.
+
+3. Clean up intermediate distillate content (it exists only in memory, not saved to disk).
+
+**Graceful degradation:** If subagent spawning is unavailable, read the source documents and perform the compression work directly using the same instructions from `agents/distillate-compressor.md`. For fan-out, process groups sequentially then merge.
+
+The compressor returns a structured JSON result containing the distillate content, source headings, named entities, and token estimate.
+
+### Stage 3: Verify & Output
+
+After the compressor (or merge compressor) returns:
+
+1. **Completeness check.** Using the headings and named entities list returned by the compressor, verify each appears in the distillate content. If gaps are found, send them back to the compressor for a targeted fix pass — not a full recompression. Limit to 2 fix passes maximum.
+
+2. **Format check.** Verify the output follows distillate format rules:
+   - No prose paragraphs (only bullets)
+   - No decorative formatting
+   - No repeated information
+   - Each bullet is self-contained
+   - Themes are clearly delineated with `##` headings
+
+3. **Determine output format.** Using the split prediction from Stage 1 and actual distillate size:
+
+   **Single distillate** (≤~5,000 tokens or token_budget not exceeded):
+
+   Save as a single file with frontmatter:
+
+   ```yaml
+   ---
+   type: bmad-distillate
+   sources:
+     - "{relative path to source file 1}"
+     - "{relative path to source file 2}"
+   downstream_consumer: "{consumer or 'general'}"
+   created: "{date}"
+   token_estimate: {approximate token count}
+   parts: 1
+   ---
+   ```
+
+   **Split distillate** (>~5,000 tokens, or token_budget requires it):
+
+   Create a folder `{base-name}-distillate/` containing:
+
+   ```
+   {base-name}-distillate/
+   ├── _index.md           # Orientation, cross-cutting items, section manifest
+   ├── 01-{topic-slug}.md  # Self-contained section
+   ├── 02-{topic-slug}.md
+   └── 03-{topic-slug}.md
+   ```
+
+   The `_index.md` contains:
+   - Frontmatter with sources (relative paths from the distillate folder to the originals)
+   - 3-5 bullet orientation (what was distilled, from what)
+   - Section manifest: each section's filename + 1-line description
+   - Cross-cutting items that span multiple sections
+
+   Each section file is self-contained — loadable independently. Include a 1-line context header: "This section covers [topic]. Part N of M."
+
+   Source paths in frontmatter must be relative to the distillate's location.
+
+4. **Measure distillate.** Run `scripts/analyze_sources.py` on the final distillate file(s) to get accurate token counts for the output. Use the `total_estimated_tokens` from this analysis as `distillate_total_tokens`.
+
+5. **Report results.** Always return structured JSON output:
+
+   ```json
+   {
+     "status": "complete",
+     "distillate": "{path or folder path}",
+     "section_distillates": ["{path1}", "{path2}"] or null,
+     "source_total_tokens": N,
+     "distillate_total_tokens": N,
+     "compression_ratio": "X:1",
+     "source_documents": ["{path1}", "{path2}"],
+     "completeness_check": "pass" or "pass_with_additions"
+   }
+   ```
+
+   Where `source_total_tokens` is from the Stage 1 analysis and `distillate_total_tokens` is from step 4. The `compression_ratio` is `source_total_tokens / distillate_total_tokens` formatted as "X:1" (e.g., "3.2:1").
+
+6. If `--validate` flag was set, proceed to Stage 4. Otherwise, done.
+
+### Stage 4: Round-Trip Validation (--validate only)
+
+This stage proves the distillate is lossless by reconstructing source documents from the distillate alone. Use for critical documents where information loss is unacceptable, or as a quality gate for high-stakes downstream workflows. Not for routine use — it adds significant token cost.
+
+1. **Spawn the reconstructor agent** using `agents/round-trip-reconstructor.md`. Pass it ONLY the distillate file path (or `_index.md` path for split distillates) — it must NOT have access to the original source documents.
+
+   For split distillates, spawn one reconstructor per section in parallel. Each receives its section file plus the `_index.md` for cross-cutting context.
+
+   **Graceful degradation:** If subagent spawning is unavailable, this stage cannot be performed by the main agent (it has already seen the originals). Report that round-trip validation requires subagent support and skip.
+
+2. **Receive reconstructions.** The reconstructor returns reconstruction file paths saved adjacent to the distillate.
+
+3. **Perform semantic diff.** Read both the original source documents and the reconstructions. For each section of the original, assess:
+   - Is the core information present in the reconstruction?
+   - Are specific details preserved (numbers, names, decisions)?
+   - Are relationships and rationale intact?
+   - Did the reconstruction add anything not in the original? (indicates hallucination filling gaps)
+
+4. **Produce validation report** saved adjacent to the distillate as `-validation-report.md`:
+
+   ```markdown
+   ---
+   type: distillate-validation
+   distillate: "{distillate path}"
+   sources: ["{source paths}"]
+   created: "{date}"
+   ---
+
+   ## Validation Summary
+   - Status: PASS | PASS_WITH_WARNINGS | FAIL
+   - Information preserved: {percentage estimate}
+   - Gaps found: {count}
+   - Hallucinations detected: {count}
+
+   ## Gaps (information in originals but missing from reconstruction)
+   - {gap description} — Source: {which original}, Section: {where}
+
+   ## Hallucinations (information in reconstruction not traceable to originals)
+   - {hallucination description} — appears to fill gap in: {section}
+
+   ## Possible Gap Markers (flagged by reconstructor)
+   - {marker description}
+   ```
+
+5. **If gaps are found**, offer to run a targeted fix pass on the distillate — adding the missing information without full recompression. Limit to 2 fix passes maximum.
+
+6. **Clean up** — delete the temporary reconstruction files after the report is generated.
\ No newline at end of file
diff --git a/.claude/skills/bmad-distillator/agents/distillate-compressor.md b/.claude/skills/bmad-distillator/agents/distillate-compressor.md
new file mode 100644
index 0000000..d581b79
--- /dev/null
+++ b/.claude/skills/bmad-distillator/agents/distillate-compressor.md
@@ -0,0 +1,116 @@
+# Distillate Compressor Agent
+
+Act as an information extraction and compression specialist. Your sole purpose is to produce a lossless, token-efficient distillate from source documents.
+
+You receive: source document file paths, an optional downstream_consumer context, and a splitting decision.
+
+You must load and apply `../resources/compression-rules.md` before producing output. Reference `../resources/distillate-format-reference.md` for the expected output format.
+
+## Compression Process
+
+### Step 1: Read Sources
+
+Read all source document files. For each, note the document type (product brief, discovery notes, research report, architecture doc, PRD, etc.) based on content and naming.
+
+### Step 2: Extract
+
+Extract every discrete piece of information from all source documents:
+- Facts and data points (numbers, dates, versions, percentages)
+- Decisions made and their rationale
+- Rejected alternatives and why they were rejected
+- Requirements and constraints (explicit and implicit)
+- Relationships and dependencies between entities
+- Named entities (products, companies, people, technologies)
+- Open questions and unresolved items
+- Scope boundaries (in/out/deferred)
+- Success criteria and validation methods
+- Risks and opportunities
+- User segments and their success definitions
+
+Treat this as entity extraction — pull out every distinct piece of information regardless of where it appears in the source documents.
+
+### Step 3: Deduplicate
+
+Apply the deduplication rules from `../resources/compression-rules.md`.
+
+### Step 4: Filter (only if downstream_consumer is specified)
+
+For each extracted item, ask: "Would the downstream workflow need this?"
+- Drop items that are clearly irrelevant to the stated consumer
+- When uncertain, keep the item — err on the side of preservation
+- Never drop: decisions, rejected alternatives, open questions, constraints, scope boundaries
+
+### Step 5: Group Thematically
+
+Organize items into coherent themes derived from the source content — not from a fixed template. The themes should reflect what the documents are actually about.
+
+Common groupings (use what fits, omit what doesn't, add what's needed):
+- Core concept / problem / motivation
+- Solution / approach / architecture
+- Users / segments
+- Technical decisions / constraints
+- Scope boundaries (in/out/deferred)
+- Competitive context
+- Success criteria
+- Rejected alternatives
+- Open questions
+- Risks and opportunities
+
+### Step 6: Compress Language
+
+For each item, apply the compression rules from `../resources/compression-rules.md`:
+- Strip prose transitions and connective tissue
+- Remove hedging and rhetoric
+- Remove explanations of common knowledge
+- Preserve specific details (numbers, names, versions, dates)
+- Ensure the item is self-contained (understandable without reading the source)
+- Make relationships explicit ("X because Y", "X blocks Y", "X replaces Y")
+
+### Step 7: Format Output
+
+Produce the distillate as dense thematically-grouped bullets:
+- `##` headings for themes — no deeper heading levels needed
+- `- ` bullets for items — every token must carry signal
+- No decorative formatting (no bold for emphasis, no horizontal rules)
+- No prose paragraphs — only bullets
+- Semicolons to join closely related short items within a single bullet
+- Each bullet self-contained — understandable without reading other bullets
+
+Do NOT include frontmatter — the calling skill handles that.
+
+## Semantic Splitting
+
+If the splitting decision indicates splitting is needed, load `../resources/splitting-strategy.md` and follow it.
+
+When splitting:
+
+1. Identify natural semantic boundaries in the content — coherent topic clusters, not arbitrary size breaks.
+
+2. Produce a **root distillate** containing:
+   - 3-5 bullet orientation (what was distilled, for whom, how many parts)
+   - Cross-references to section distillates
+   - Items that span multiple sections
+
+3. Produce **section distillates**, each self-sufficient. Include a 1-line context header: "This section covers [topic]. Part N of M from [source document names]."
+
+## Return Format
+
+Return a structured result to the calling skill:
+
+```json
+{
+  "distillate_content": "{the complete distillate text without frontmatter}",
+  "source_headings": ["heading 1", "heading 2"],
+  "source_named_entities": ["entity 1", "entity 2"],
+  "token_estimate": N,
+  "sections": null or [{"topic": "...", "content": "..."}]
+}
+```
+
+- **distillate_content**: The full distillate text
+- **source_headings**: All Level 2+ headings found across source documents (for completeness verification)
+- **source_named_entities**: Key named entities (products, companies, people, technologies, decisions) found in sources
+- **token_estimate**: Approximate token count of the distillate
+- **sections**: null for single distillates; array of section objects if semantically split
+
+Do not include conversational text, status updates, or preamble — return only the structured result.
diff --git a/.claude/skills/bmad-distillator/agents/round-trip-reconstructor.md b/.claude/skills/bmad-distillator/agents/round-trip-reconstructor.md
new file mode 100644
index 0000000..586e7f6
--- /dev/null
+++ b/.claude/skills/bmad-distillator/agents/round-trip-reconstructor.md
@@ -0,0 +1,68 @@
+# Round-Trip Reconstructor Agent
+
+Act as a document reconstruction specialist. Your purpose is to prove a distillate's completeness by reconstructing the original source documents from the distillate alone.
+
+**Critical constraint:** You receive ONLY the distillate file path. You must NOT have access to the original source documents. If you can see the originals, the test is meaningless.
+
+## Process
+
+### Step 1: Analyze the Distillate
+
+Read the distillate file. Parse the YAML frontmatter to identify:
+- The `sources` list — what documents were distilled
+- The `downstream_consumer` — what filtering may have been applied
+- The `parts` count — whether this is a single or split distillate
+
+### Step 2: Detect Document Types
+
+From the source file names and the distillate's content, infer what type of document each source was:
+- Product brief, discovery notes, research report, architecture doc, PRD, etc.
+- Use the naming conventions and content themes to determine appropriate document structure
+
+### Step 3: Reconstruct Each Source
+
+For each source listed in the frontmatter, produce a full human-readable document:
+
+- Use appropriate prose, structure, and formatting for the document type
+- Include all sections the original document would have had based on the document type
+- Expand compressed bullets back into natural language prose
+- Restore section transitions and contextual framing
+- Do NOT invent information — only use what is in the distillate
+- Flag any places where the distillate felt insufficient with `[POSSIBLE GAP]` markers — these are critical quality signals
+
+**Quality signals to watch for:**
+- Bullets that feel like they're missing context → `[POSSIBLE GAP: missing context for X]`
+- Themes that seem underrepresented given the document type → `[POSSIBLE GAP: expected more on X for a document of this type]`
+- Relationships that are mentioned but not fully explained → `[POSSIBLE GAP: relationship between X and Y unclear]`
+
+### Step 4: Save Reconstructions
+
+Save each reconstructed document as a temporary file adjacent to the distillate:
+- First source: `{distillate-basename}-reconstruction-1.md`
+- Second source: `{distillate-basename}-reconstruction-2.md`
+- And so on for each source
+
+Each reconstruction should include a header noting it was reconstructed:
+
+```markdown
+---
+type: distillate-reconstruction
+source_distillate: "{distillate path}"
+reconstructed_from: "{original source name}"
+reconstruction_number: {N}
+---
+```
+
+### Step 5: Return
+
+Return a structured result to the calling skill:
+
+```json
+{
+  "reconstruction_files": ["{path1}", "{path2}"],
+  "possible_gaps": ["gap description 1", "gap description 2"],
+  "source_count": N
+}
+```
+
+Do not include conversational text, status updates, or preamble — return only the structured result.
diff --git a/.claude/skills/bmad-distillator/resources/compression-rules.md b/.claude/skills/bmad-distillator/resources/compression-rules.md
new file mode 100644
index 0000000..b45b158
--- /dev/null
+++ b/.claude/skills/bmad-distillator/resources/compression-rules.md
@@ -0,0 +1,51 @@
+# Compression Rules
+
+These rules govern how source text is compressed into distillate format. Apply as a final pass over all output.
+
+## Strip — Remove entirely
+
+- Prose transitions: "As mentioned earlier", "It's worth noting", "In addition to this"
+- Rhetoric and persuasion: "This is a game-changer", "The exciting thing is"
+- Hedging: "We believe", "It's likely that", "Perhaps", "It seems"
+- Self-reference: "This document describes", "As outlined above"
+- Common knowledge explanations: "Vercel is a cloud platform company", "MIT is an open-source license", "JSON is a data interchange format"
+- Repeated introductions of the same concept
+- Section transition paragraphs
+- Formatting-only elements (decorative bold/italic for emphasis, horizontal rules for visual breaks)
+- Filler phrases: "In order to", "It should be noted that", "The fact that"
+
+## Preserve — Keep always
+
+- Specific numbers, dates, versions, percentages
+- Named entities (products, companies, people, technologies)
+- Decisions made and their rationale (compressed: "Decision: X. Reason: Y")
+- Rejected alternatives and why (compressed: "Rejected: X. Reason: Y")
+- Explicit constraints and non-negotiables
+- Dependencies and ordering relationships
+- Open questions and unresolved items
+- Scope boundaries (in/out/deferred)
+- Success criteria and how they're validated
+- User segments and what success means for each
+- Risks with their severity signals
+- Conflicts between source documents
+
+## Transform — Change form for efficiency
+
+- Long prose paragraphs → single dense bullet capturing the same information
+- "We decided to use X because Y and Z" → "X (rationale: Y, Z)"
+- Repeated category labels → group under a single heading, no per-item labels
+- "Risk: ... Severity: high" → "HIGH RISK: ..."
+- Conditional statements → "If X → Y" form
+- Multi-sentence explanations → semicolon-separated compressed form
+- Lists of related short items → single bullet with semicolons
+- "X is used for Y" → "X: Y" when context is clear
+- Verbose enumerations → parenthetical lists: "platforms (Cursor, Claude Code, Windsurf, Copilot)"
+
+## Deduplication Rules
+
+- Same fact in multiple documents → keep the version with most context
+- Same concept at different detail levels → keep the detailed version
+- Overlapping lists → merge into single list, no duplicates
+- When source documents disagree → note the conflict explicitly: "Brief says X; discovery notes say Y — unresolved"
+- Executive summary points that are expanded elsewhere → keep only the expanded version
+- Introductory framing repeated across sections → capture once under the most relevant theme
diff --git a/.claude/skills/bmad-distillator/resources/distillate-format-reference.md b/.claude/skills/bmad-distillator/resources/distillate-format-reference.md
new file mode 100644
index 0000000..d01cd49
--- /dev/null
+++ b/.claude/skills/bmad-distillator/resources/distillate-format-reference.md
@@ -0,0 +1,227 @@
+# Distillate Format Reference
+
+Examples showing the transformation from human-readable source content to distillate format.
+
+## Frontmatter
+
+Every distillate includes YAML frontmatter. Source paths are relative to the distillate's location so the distillate remains portable:
+
+```yaml
+---
+type: bmad-distillate
+sources:
+  - "product-brief-example.md"
+  - "product-brief-example-discovery-notes.md"
+downstream_consumer: "PRD creation"
+created: "2026-03-13"
+token_estimate: 1200
+parts: 1
+---
+```
+
+## Before/After Examples
+
+### Prose Paragraph to Dense Bullet
+
+**Before** (human-readable brief excerpt):
+```
+## What Makes This Different
+
+**The anti-fragmentation layer.** The AI tooling space is fracturing across 40+
+platforms with no shared methodology layer. BMAD is uniquely positioned to be the
+cross-platform constant — the structured approach that works the same in Cursor,
+Claude Code, Windsurf, Copilot, and whatever launches next month. Every other
+methodology or skill framework maintains its own platform support matrix. By
+building on the open-source skills CLI ecosystem, BMAD offloads the highest-churn
+maintenance burden and focuses on what actually differentiates it: the methodology
+itself.
+```
+
+**After** (distillate):
+```
+## Differentiation
+- Anti-fragmentation positioning: BMAD = cross-platform constant across 40+ fragmenting AI tools; no competitor provides shared methodology layer
+- Platform complexity delegated to Vercel skills CLI ecosystem (MIT); BMAD maintains methodology, not platform configs
+```
+
+### Technical Details to Compressed Facts
+
+**Before** (discovery notes excerpt):
+```
+## Competitive Landscape
+
+- **Vercel Skills.sh**: 83K+ skills, 18 agents, largest curated leaderboard —
+  but dev-only, skills trigger unreliably (20% without explicit prompting)
+- **SkillsMP**: 400K+ skills directory, pure aggregator with no curation or CLI
+- **ClawHub/OpenClaw**: ~3.2K curated skills with versioning/rollback, small ecosystem
+- **Lindy**: No-code AI agent builder for business automation — closed platform,
+  no skill sharing
+- **Microsoft Copilot Studio**: Enterprise no-code agent builder — vendor-locked
+  to Microsoft
+- **MindStudio**: No-code AI agent platform — siloed, no interoperability
+- **Make/Zapier AI**: Workflow automation adding AI agents — workflow-centric,
+  not methodology-centric
+- **Key gap**: NO competitor combines structured methodology with plugin
+  marketplace — this is BMAD's whitespace
+```
+
+**After** (distillate):
+```
+## Competitive Landscape
+- No competitor combines structured methodology + plugin marketplace (whitespace)
+- Skills.sh (Vercel): 83K skills, 18 agents, dev-only, 20% trigger reliability
+- SkillsMP: 400K skills, aggregator only, no curation/CLI
+- ClawHub: 3.2K curated, versioning, small ecosystem
+- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only
+```
+
+### Deduplication Across Documents
+
+When the same fact appears in both a brief and discovery notes:
+
+**Brief says:**
+```
+bmad-help must always be included as a base skill in every bundle
+```
+
+**Discovery notes say:**
+```
+bmad-help must always be included as a base skill in every bundle/install
+(solves discoverability problem)
+```
+
+**Distillate keeps the more contextual version:**
+```
+- bmad-help: always included as base skill in every bundle (solves discoverability)
+```
+
+### Decision/Rationale Compression
+
+**Before:**
+```
+We decided not to build our own platform support matrix going forward, instead
+delegating to the Vercel skills CLI ecosystem. The rationale is that maintaining
+20+ platform configs is the biggest maintenance burden and it's unsustainable
+at 40+ platforms.
+```
+
+**After:**
+```
+- Rejected: own platform support matrix. Reason: unsustainable at 40+ platforms; delegate to Vercel CLI ecosystem
+```
+
+## Full Example
+
+A complete distillate produced from a product brief and its discovery notes, targeted at PRD creation:
+
+```markdown
+---
+type: bmad-distillate
+sources:
+  - "product-brief-bmad-next-gen-installer.md"
+  - "product-brief-bmad-next-gen-installer-discovery-notes.md"
+downstream_consumer: "PRD creation"
+created: "2026-03-13"
+token_estimate: 1450
+parts: 1
+---
+
+## Core Concept
+- BMAD Next-Gen Installer: replaces monolithic Node.js CLI with skill-based plugin architecture for distributing BMAD methodology across 40+ AI platforms
+- Three layers: self-describing plugins (bmad-manifest.json), cross-platform install via Vercel skills CLI (MIT), runtime registration via bmad-setup skill
+- Transforms BMAD from dev-only methodology into open platform for any domain (creative, therapeutic, educational, personal)
+
+## Problem
+- Current installer maintains ~20 platform configs manually; each platform convention change requires installer update, test, release — largest maintenance burden on team
+- Node.js/npm required — blocks non-technical users on UI-based platforms (Claude Co-Work, etc.)
+- CSV manifests are static, generated once at install; no runtime scanning/registration
+- Unsustainable at 40+ platforms; new tools launching weekly
+
+## Solution Architecture
+- Plugins: skill bundles with Anthropic plugin standard as base format + bmad-manifest.json extending for BMAD-specific metadata (installer options, capabilities, help integration, phase ordering, dependencies)
+- Existing manifest example: `{"module-code":"bmm","replaces-skill":"bmad-create-product-brief","capabilities":[{"name":"create-brief","menu-code":"CB","supports-headless":true,"phase-name":"1-analysis","after":["brainstorming"],"before":["create-prd"],"is-required":true}]}`
+- Vercel skills CLI handles platform translation; integration pattern (wrap/fork/call) is PRD decision
+- bmad-setup: global skill scanning installed bmad-manifest.json files, registering capabilities, configuring project settings; always included as base skill in every bundle (solves bootstrapping)
+- bmad-update: plugin update path without full reinstall; technical approach (diff/replace/preserve customizations) is PRD decision
+- Distribution tiers: (1) NPX installer wrapping skills CLI for technical users, (2) zip bundle + platform-specific README for non-technical users, (3) future marketplace
+- Non-technical path has honest friction: "copy to right folder" requires knowing where; per-platform README instructions; improves over time as low-code space matures
+
+## Differentiation
+- Anti-fragmentation: BMAD = cross-platform constant; no competitor provides shared methodology layer across AI tools
+- Curated quality: all submissions gated, human-reviewed by BMad + core team; 13.4% of community skills have critical vulnerabilities (Snyk 2026); quality gate value increases as ecosystem gets noisier
+- Domain-agnostic: no competitor builds beyond software dev workflows; same plugin system powers any domain via BMAD Builder (separate initiative)
+
+## Users (ordered by v1 priority)
+- Module authors (primary v1): package/test/distribute plugins independently without installer changes
+- Developers: single-command install on any of 40+ platforms via NPX
+- Non-technical users: install without Node/Git/terminal; emerging segment including PMs, designers, educators
+- Future plugin creators: non-dev authors using BMAD Builder; need distribution without building own installer
+
+## Success Criteria
+- Zero (or near-zero) custom platform directory code; delegated to skills CLI ecosystem
+- Installation verified on top platforms by volume; skills CLI handles long tail
+- Non-technical install path validated with non-developer users
+- bmad-setup discovers/registers all plugins from manifests; clear errors for malformed manifests
+- At least one external module author successfully publishes plugin using manifest system
+- bmad-update works without full reinstall
+- Existing CLI users have documented migration path
+
+## Scope
+- In: manifest spec, bmad-setup, bmad-update, Vercel CLI integration, NPX installer, zip bundles, migration path
+- Out: BMAD Builder, marketplace web platform, skill conversion (prerequisite, separate), one-click install for all platforms, monetization, quality certification process (gated-submission principle is architectural requirement; process defined separately)
+- Deferred: CI/CD integration, telemetry for module authors, air-gapped enterprise install, zip bundle integrity verification (checksums/signing), deeper non-technical platform integrations
+
+## Current Installer (migration context)
+- Entry: `tools/installer/bmad-cli.js` (Commander.js) → `tools/installer/core/installer.js`
+- Platforms: `platform-codes.yaml` (~20 platforms with target dirs, legacy dirs, template types, special flags)
+- Manifests: CSV files (skill/workflow/agent-manifest.csv) are current source of truth, not JSON
+- External modules: `external-official-modules.yaml` (CIS, GDS, TEA, WDS) from npm with semver
+- Dependencies: 4-pass resolver (collect → parse → resolve → transitive); YAML-declared only
+- Config: prompts for name, communication language, document output language, output folder
+- Skills already use directory-per-skill layout; bmad-manifest.json sidecars exist but are not source of truth
+- Key shift: CSV-based static manifests → JSON-based runtime scanning
+
+## Vercel Skills CLI
+- `npx skills add <source>` — GitHub, GitLab, local paths, git URLs
+- 40+ agents; per-agent path mappings; symlinks (recommended) or copies
+- Scopes: project-level or global
+- Discovery: `skills/`, `.agents/skills/`, agent-specific paths, `.claude-plugin/marketplace.json`
+- Commands: add, list, find, remove, check, update, init
+- Non-interactive: `-y`, `--all` flags for CI/CD
+
+## Competitive Landscape
+- No competitor combines structured methodology + plugin marketplace (whitespace)
+- Skills.sh (Vercel): 83K skills, dev-only, 20% trigger reliability without explicit prompting
+- SkillsMP: 400K skills, aggregator only, no curation
+- ClawHub: 3.2K curated, versioning, small
+- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only
+- Market: $7.84B (2025) → $52.62B (2030); Agent Skills spec ~4 months old, 351K+ skills; standards converging under Linux Foundation AAIF (MCP, AGENTS.md, A2A)
+
+## Rejected Alternatives
+- Building own platform support matrix: unsustainable at 40+; delegate to Vercel ecosystem
+- One-click install for non-technical v1: emerging space; guidance-based, improve over time
+- Prior roadmap/brainstorming: clean start, unconstrained by previous planning
+
+## Open Questions
+- Vercel CLI integration pattern: wrap/fork/call/peer dependency?
+- bmad-update mechanics: diff/replace? Preserve user customizations?
+- Migration story: command/manual reinstall/compatibility shim?
+- Cross-platform testing: CI matrix for top N? Community testing for rest?
+- bmad-manifest.json as open standard submission to Agent Skills governance?
+- Platforms NOT supported by Vercel skills CLI?
+- Manifest versioning strategy for backward compatibility?
+- Plugin author getting-started experience and tooling?
+
+## Opportunities
+- Module authors as acquisition channel: each published plugin distributes BMAD to creator's audience
+- CI/CD integration: bmad-setup as pipeline one-liner increases stickiness
+- Educational institutions: structured methodology + non-technical install → university AI curriculum
+- Skill composability: mixing BMAD modules with third-party skills for custom methodology stacks
+
+## Risks
+- Manifest format evolution creates versioning/compatibility burden once third-party authors publish
+- Quality gate needs defined process, not just claim — gated review model addresses
+- 40+ platform testing environments even with Vercel handling translation
+- Scope creep pressure from marketplace vision (explicitly excluded but primary long-term value)
+- Vercel dependency: minor supply-chain risk; MIT license allows fork if deprioritized
+```
diff --git a/.claude/skills/bmad-distillator/resources/splitting-strategy.md b/.claude/skills/bmad-distillator/resources/splitting-strategy.md
new file mode 100644
index 0000000..37fec03
--- /dev/null
+++ b/.claude/skills/bmad-distillator/resources/splitting-strategy.md
@@ -0,0 +1,78 @@
+# Semantic Splitting Strategy
+
+When the source content is large (exceeds ~15,000 tokens) or a token_budget requires it, split the distillate into semantically coherent sections rather than arbitrary size breaks.
+
+## Why Semantic Over Size-Based
+
+Arbitrary splits (every N tokens) break coherence. A downstream workflow loading "part 2 of 4" gets context fragments. Semantic splits produce self-contained topic clusters that a workflow can load selectively — "give me just the technical decisions section" — which is more useful and more token-efficient for the consumer.
+
+## Splitting Process
+
+### 1. Identify Natural Boundaries
+
+After the initial extraction and deduplication (Steps 1-2 of the compression process), look for natural semantic boundaries:
+- Distinct problem domains or functional areas
+- Different stakeholder perspectives (users, technical, business)
+- Temporal boundaries (current state vs future vision)
+- Scope boundaries (in-scope vs out-of-scope vs deferred)
+- Phase boundaries (analysis, design, implementation)
+
+Choose boundaries that produce sections a downstream workflow might load independently.
+
+### 2. Assign Items to Sections
+
+For each extracted item, assign it to the most relevant section. Items that span multiple sections go in the root distillate.
+
+Cross-cutting items (items relevant to multiple sections):
+- Constraints that affect all areas → root distillate
+- Decisions with broad impact → root distillate
+- Section-specific decisions → section distillate
+
+### 3. Produce Root Distillate
+
+The root distillate contains:
+- **Orientation** (3-5 bullets): what was distilled, from what sources, for what consumer, how many sections
+- **Cross-references**: list of section distillates with 1-line descriptions
+- **Cross-cutting items**: facts, decisions, and constraints that span multiple sections
+- **Scope summary**: high-level in/out/deferred if applicable
+
+### 4. Produce Section Distillates
+
+Each section distillate must be self-sufficient — a reader loading only one section should understand it without the others.
+
+Each section includes:
+- **Context header** (1 line): "This section covers [topic]. Part N of M from [source document names]."
+- **Section content**: thematically-grouped bullets following the same compression rules as a single distillate
+- **Cross-references** (if needed): pointers to other sections for related content
+
+### 5. Output Structure
+
+Create a folder `{base-name}-distillate/` containing:
+
+```
+{base-name}-distillate/
+├── _index.md           # Root distillate: orientation, cross-cutting items, section manifest
+├── 01-{topic-slug}.md  # Self-contained section
+├── 02-{topic-slug}.md
+└── 03-{topic-slug}.md
+```
+
+Example:
+```
+product-brief-distillate/
+├── _index.md
+├── 01-problem-solution.md
+├── 02-technical-decisions.md
+└── 03-users-market.md
+```
+
+## Size Targets
+
+When a token_budget is specified:
+- Root distillate: ~20% of budget (orientation + cross-cutting items)
+- Remaining budget split proportionally across sections based on content density
+- If a section exceeds its proportional share, compress more aggressively or sub-split
+
+When no token_budget but splitting is needed:
+- Aim for sections of 3,000-5,000 tokens each
+- Root distillate as small as possible while remaining useful standalone
diff --git a/.claude/skills/bmad-distillator/scripts/analyze_sources.py b/.claude/skills/bmad-distillator/scripts/analyze_sources.py
new file mode 100644
index 0000000..38ddcbe
--- /dev/null
+++ b/.claude/skills/bmad-distillator/scripts/analyze_sources.py
@@ -0,0 +1,300 @@
+# /// script
+# /// requires-python = ">=3.10"
+# /// dependencies = []
+# ///
+"""Analyze source documents for the distillation generator.
+
+Enumerates files from paths/folders/globs, computes sizes and token estimates,
+detects document types from naming conventions, and suggests groupings for
+related documents (e.g., a brief paired with its discovery notes).
+
+Accepts: file paths, folder paths (scans recursively for .md/.txt/.yaml/.yml/.json),
+or glob patterns. Skips node_modules, .git, __pycache__, .venv, _bmad-output.
+
+Output JSON structure:
+  status: "ok" | "error"
+  files[]: path, filename, size_bytes, estimated_tokens, doc_type
+  summary: total_files, total_size_bytes, total_estimated_tokens
+  groups[]: group_key, files[] with role (primary/companion/standalone)
+    - Groups related docs by naming convention (e.g., brief + discovery-notes)
+  routing: recommendation ("single" | "fan-out"), reason
+    - single: ≤3 files AND ≤15K estimated tokens
+    - fan-out: >3 files OR >15K estimated tokens
+  split_prediction: prediction ("likely" | "unlikely"), reason, estimated_distillate_tokens
+    - Estimates distillate at ~1/3 source size; splits if >5K tokens
+"""
+
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+# Extensions to include when scanning folders
+INCLUDE_EXTENSIONS = {".md", ".txt", ".yaml", ".yml", ".json"}
+
+# Directories to skip when scanning folders
+SKIP_DIRS = {
+    "node_modules", ".git", "__pycache__", ".venv", "venv",
+    ".claude", "_bmad-output", ".cursor", ".vscode",
+}
+
+# Approximate chars per token for estimation
+CHARS_PER_TOKEN = 4
+
+# Thresholds
+SINGLE_COMPRESSOR_MAX_TOKENS = 15_000
+SINGLE_DISTILLATE_MAX_TOKENS = 5_000
+
+# Naming patterns for document type detection
+DOC_TYPE_PATTERNS = [
+    (r"discovery[_-]notes", "discovery-notes"),
+    (r"product[_-]brief", "product-brief"),
+    (r"research[_-]report", "research-report"),
+    (r"architecture", "architecture-doc"),
+    (r"prd", "prd"),
+    (r"distillate", "distillate"),
+    (r"changelog", "changelog"),
+    (r"readme", "readme"),
+    (r"spec", "specification"),
+    (r"requirements", "requirements"),
+    (r"design[_-]doc", "design-doc"),
+    (r"meeting[_-]notes", "meeting-notes"),
+    (r"brainstorm", "brainstorming"),
+    (r"interview", "interview-notes"),
+]
+
+# Patterns for grouping related documents
+GROUP_PATTERNS = [
+    # base document + discovery notes
+    (r"^(.+?)(?:-discovery-notes|-discovery_notes)\.(\w+)$", r"\1.\2"),
+    # base document + appendix
+    (r"^(.+?)(?:-appendix|-addendum)(?:-\w+)?\.(\w+)$", r"\1.\2"),
+    # base document + review/feedback
+    (r"^(.+?)(?:-review|-feedback)\.(\w+)$", r"\1.\2"),
+]
+
+
+def resolve_inputs(inputs: list[str]) -> list[Path]:
+    """Resolve input arguments to a flat list of file paths."""
+    files: list[Path] = []
+    for inp in inputs:
+        path = Path(inp)
+        if path.is_file():
+            files.append(path.resolve())
+        elif path.is_dir():
+            for root, dirs, filenames in os.walk(path):
+                dirs[:] = [d for d in dirs if d not in SKIP_DIRS]
+                for fn in sorted(filenames):
+                    fp = Path(root) / fn
+                    if fp.suffix.lower() in INCLUDE_EXTENSIONS:
+                        files.append(fp.resolve())
+        else:
+            # Try as glob
+            matches = glob.glob(inp, recursive=True)
+            for m in sorted(matches):
+                mp = Path(m)
+                if mp.is_file() and mp.suffix.lower() in INCLUDE_EXTENSIONS:
+                    files.append(mp.resolve())
+    # Deduplicate while preserving order
+    seen: set[Path] = set()
+    deduped: list[Path] = []
+    for f in files:
+        if f not in seen:
+            seen.add(f)
+            deduped.append(f)
+    return deduped
+
+
+def detect_doc_type(filename: str) -> str:
+    """Detect document type from filename."""
+    name_lower = filename.lower()
+    for pattern, doc_type in DOC_TYPE_PATTERNS:
+        if re.search(pattern, name_lower):
+            return doc_type
+    return "unknown"
+
+
+def suggest_groups(files: list[Path]) -> list[dict]:
+    """Suggest document groupings based on naming conventions."""
+    groups: dict[str, list[dict]] = {}
+    ungrouped: list[dict] = []
+
+    file_map = {f.name: f for f in files}
+
+    assigned: set[str] = set()
+
+    for f in files:
+        if f.name in assigned:
+            continue
+
+        matched = False
+        for pattern, base_pattern in GROUP_PATTERNS:
+            m = re.match(pattern, f.name, re.IGNORECASE)
+            if m:
+                # This file is a companion — find its base
+                base_name = re.sub(pattern, base_pattern, f.name, flags=re.IGNORECASE)
+                group_key = base_name
+                if group_key not in groups:
+                    groups[group_key] = []
+                    # Add the base file if it exists
+                    if base_name in file_map and base_name not in assigned:
+                        groups[group_key].append({
+                            "path": str(file_map[base_name]),
+                            "filename": base_name,
+                            "role": "primary",
+                        })
+                        assigned.add(base_name)
+                groups[group_key].append({
+                    "path": str(f),
+                    "filename": f.name,
+                    "role": "companion",
+                })
+                assigned.add(f.name)
+                matched = True
+                break
+
+        if not matched:
+            # Check if this file is a base that already has companions
+            if f.name in groups:
+                continue  # Already added as primary
+            ungrouped.append({
+                "path": str(f),
+                "filename": f.name,
+            })
+
+    result = []
+    for group_key, members in groups.items():
+        result.append({
+            "group_key": group_key,
+            "files": members,
+        })
+    for ug in ungrouped:
+        if ug["filename"] not in assigned:
+            result.append({
+                "group_key": ug["filename"],
+                "files": [{"path": ug["path"], "filename": ug["filename"], "role": "standalone"}],
+            })
+
+    return result
+
+
+def analyze(inputs: list[str], output_path: str | None = None) -> None:
+    """Main analysis function."""
+    files = resolve_inputs(inputs)
+
+    if not files:
+        result = {
+            "status": "error",
+            "error": "No readable files found from provided inputs",
+            "inputs": inputs,
+        }
+        output_json(result, output_path)
+        return
+
+    # Analyze each file
+    file_details = []
+    total_chars = 0
+    for f in files:
+        size = f.stat().st_size
+        total_chars += size
+        file_details.append({
+            "path": str(f),
+            "filename": f.name,
+            "size_bytes": size,
+            "estimated_tokens": size // CHARS_PER_TOKEN,
+            "doc_type": detect_doc_type(f.name),
+        })
+
+    total_tokens = total_chars // CHARS_PER_TOKEN
+    groups = suggest_groups(files)
+
+    # Routing recommendation
+    if len(files) <= 3 and total_tokens <= SINGLE_COMPRESSOR_MAX_TOKENS:
+        routing = "single"
+        routing_reason = (
+            f"{len(files)} file(s), ~{total_tokens:,} estimated tokens — "
+            f"within single compressor threshold"
+        )
+    else:
+        routing = "fan-out"
+        routing_reason = (
+            f"{len(files)} file(s), ~{total_tokens:,} estimated tokens — "
+            f"exceeds single compressor threshold "
+            f"({'>' + str(SINGLE_COMPRESSOR_MAX_TOKENS) + ' tokens' if total_tokens > SINGLE_COMPRESSOR_MAX_TOKENS else '> 3 files'})"
+        )
+
+    # Split prediction
+    estimated_distillate_tokens = total_tokens // 3  # rough: distillate is ~1/3 of source
+    if estimated_distillate_tokens > SINGLE_DISTILLATE_MAX_TOKENS:
+        split_prediction = "likely"
+        split_reason = (
+            f"Estimated distillate ~{estimated_distillate_tokens:,} tokens "
+            f"exceeds {SINGLE_DISTILLATE_MAX_TOKENS:,} threshold"
+        )
+    else:
+        split_prediction = "unlikely"
+        split_reason = (
+            f"Estimated distillate ~{estimated_distillate_tokens:,} tokens "
+            f"within {SINGLE_DISTILLATE_MAX_TOKENS:,} threshold"
+        )
+
+    result = {
+        "status": "ok",
+        "files": file_details,
+        "summary": {
+            "total_files": len(files),
+            "total_size_bytes": total_chars,
+            "total_estimated_tokens": total_tokens,
+        },
+        "groups": groups,
+        "routing": {
+            "recommendation": routing,
+            "reason": routing_reason,
+        },
+        "split_prediction": {
+            "prediction": split_prediction,
+            "reason": split_reason,
+            "estimated_distillate_tokens": estimated_distillate_tokens,
+        },
+    }
+
+    output_json(result, output_path)
+
+
+def output_json(data: dict, output_path: str | None) -> None:
+    """Write JSON to file or stdout."""
+    json_str = json.dumps(data, indent=2)
+    if output_path:
+        Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+        Path(output_path).write_text(json_str + "\n")
+        print(f"Results written to {output_path}", file=sys.stderr)
+    else:
+        print(json_str)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "inputs",
+        nargs="+",
+        help="File paths, folder paths, or glob patterns to analyze",
+    )
+    parser.add_argument(
+        "-o", "--output",
+        help="Output JSON to file instead of stdout",
+    )
+    args = parser.parse_args()
+    analyze(args.inputs, args.output)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/.claude/skills/bmad-distillator/scripts/tests/test_analyze_sources.py b/.claude/skills/bmad-distillator/scripts/tests/test_analyze_sources.py
new file mode 100644
index 0000000..3c65ef2
--- /dev/null
+++ b/.claude/skills/bmad-distillator/scripts/tests/test_analyze_sources.py
@@ -0,0 +1,204 @@
+"""Tests for analyze_sources.py"""
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+# Add parent dir to path so we can import the script
+import sys
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from analyze_sources import (
+    resolve_inputs,
+    detect_doc_type,
+    suggest_groups,
+    analyze,
+    INCLUDE_EXTENSIONS,
+    SKIP_DIRS,
+)
+
+
+@pytest.fixture
+def temp_dir():
+    """Create a temp directory with sample files."""
+    with tempfile.TemporaryDirectory() as d:
+        # Create sample files
+        (Path(d) / "product-brief-foo.md").write_text("# Product Brief\nContent here")
+        (Path(d) / "product-brief-foo-discovery-notes.md").write_text("# Discovery\nNotes")
+        (Path(d) / "architecture-doc.md").write_text("# Architecture\nDesign here")
+        (Path(d) / "research-report.md").write_text("# Research\nFindings")
+        (Path(d) / "random.txt").write_text("Some text content")
+        (Path(d) / "image.png").write_bytes(b"\x89PNG")
+        # Create a subdirectory with more files
+        sub = Path(d) / "subdir"
+        sub.mkdir()
+        (sub / "prd-v2.md").write_text("# PRD\nRequirements")
+        # Create a skip directory
+        skip = Path(d) / "node_modules"
+        skip.mkdir()
+        (skip / "junk.md").write_text("Should be skipped")
+        yield d
+
+
+class TestResolveInputs:
+    def test_single_file(self, temp_dir):
+        f = str(Path(temp_dir) / "product-brief-foo.md")
+        result = resolve_inputs([f])
+        assert len(result) == 1
+        assert result[0].name == "product-brief-foo.md"
+
+    def test_folder_recursion(self, temp_dir):
+        result = resolve_inputs([temp_dir])
+        names = {f.name for f in result}
+        assert "product-brief-foo.md" in names
+        assert "prd-v2.md" in names
+        assert "random.txt" in names
+
+    def test_folder_skips_excluded_dirs(self, temp_dir):
+        result = resolve_inputs([temp_dir])
+        names = {f.name for f in result}
+        assert "junk.md" not in names
+
+    def test_folder_skips_non_text_files(self, temp_dir):
+        result = resolve_inputs([temp_dir])
+        names = {f.name for f in result}
+        assert "image.png" not in names
+
+    def test_glob_pattern(self, temp_dir):
+        pattern = str(Path(temp_dir) / "product-brief-*.md")
+        result = resolve_inputs([pattern])
+        assert len(result) == 2
+        names = {f.name for f in result}
+        assert "product-brief-foo.md" in names
+        assert "product-brief-foo-discovery-notes.md" in names
+
+    def test_deduplication(self, temp_dir):
+        f = str(Path(temp_dir) / "product-brief-foo.md")
+        result = resolve_inputs([f, f, f])
+        assert len(result) == 1
+
+    def test_mixed_inputs(self, temp_dir):
+        file_path = str(Path(temp_dir) / "architecture-doc.md")
+        folder_path = str(Path(temp_dir) / "subdir")
+        result = resolve_inputs([file_path, folder_path])
+        names = {f.name for f in result}
+        assert "architecture-doc.md" in names
+        assert "prd-v2.md" in names
+
+    def test_nonexistent_path(self):
+        result = resolve_inputs(["/nonexistent/path/file.md"])
+        assert len(result) == 0
+
+
+class TestDetectDocType:
+    @pytest.mark.parametrize("filename,expected", [
+        ("product-brief-foo.md", "product-brief"),
+        ("product_brief_bar.md", "product-brief"),
+        ("foo-discovery-notes.md", "discovery-notes"),
+        ("foo-discovery_notes.md", "discovery-notes"),
+        ("architecture-overview.md", "architecture-doc"),
+        ("my-prd.md", "prd"),
+        ("research-report-q4.md", "research-report"),
+        ("foo-distillate.md", "distillate"),
+        ("changelog.md", "changelog"),
+        ("readme.md", "readme"),
+        ("api-spec.md", "specification"),
+        ("design-doc-v2.md", "design-doc"),
+        ("meeting-notes-2026.md", "meeting-notes"),
+        ("brainstorm-session.md", "brainstorming"),
+        ("user-interview-notes.md", "interview-notes"),
+        ("random-file.md", "unknown"),
+    ])
+    def test_detection(self, filename, expected):
+        assert detect_doc_type(filename) == expected
+
+
+class TestSuggestGroups:
+    def test_groups_brief_with_discovery_notes(self, temp_dir):
+        files = [
+            Path(temp_dir) / "product-brief-foo.md",
+            Path(temp_dir) / "product-brief-foo-discovery-notes.md",
+        ]
+        groups = suggest_groups(files)
+        # Should produce one group with both files
+        paired = [g for g in groups if len(g["files"]) > 1]
+        assert len(paired) == 1
+        filenames = {f["filename"] for f in paired[0]["files"]}
+        assert "product-brief-foo.md" in filenames
+        assert "product-brief-foo-discovery-notes.md" in filenames
+
+    def test_standalone_files(self, temp_dir):
+        files = [
+            Path(temp_dir) / "architecture-doc.md",
+            Path(temp_dir) / "research-report.md",
+        ]
+        groups = suggest_groups(files)
+        assert len(groups) == 2
+        for g in groups:
+            assert len(g["files"]) == 1
+
+    def test_mixed_grouped_and_standalone(self, temp_dir):
+        files = [
+            Path(temp_dir) / "product-brief-foo.md",
+            Path(temp_dir) / "product-brief-foo-discovery-notes.md",
+            Path(temp_dir) / "architecture-doc.md",
+        ]
+        groups = suggest_groups(files)
+        paired = [g for g in groups if len(g["files"]) > 1]
+        standalone = [g for g in groups if len(g["files"]) == 1]
+        assert len(paired) == 1
+        assert len(standalone) == 1
+
+
+class TestAnalyze:
+    def test_basic_analysis(self, temp_dir):
+        f = str(Path(temp_dir) / "product-brief-foo.md")
+        output_file = str(Path(temp_dir) / "output.json")
+        analyze([f], output_file)
+        result = json.loads(Path(output_file).read_text())
+        assert result["status"] == "ok"
+        assert result["summary"]["total_files"] == 1
+        assert result["files"][0]["doc_type"] == "product-brief"
+        assert result["files"][0]["estimated_tokens"] > 0
+
+    def test_routing_single_small_input(self, temp_dir):
+        f = str(Path(temp_dir) / "product-brief-foo.md")
+        output_file = str(Path(temp_dir) / "output.json")
+        analyze([f], output_file)
+        result = json.loads(Path(output_file).read_text())
+        assert result["routing"]["recommendation"] == "single"
+
+    def test_routing_fanout_many_files(self, temp_dir):
+        # Create enough files to trigger fan-out (> 3 files)
+        for i in range(5):
+            (Path(temp_dir) / f"doc-{i}.md").write_text("x" * 1000)
+        output_file = str(Path(temp_dir) / "output.json")
+        analyze([temp_dir], output_file)
+        result = json.loads(Path(output_file).read_text())
+        assert result["routing"]["recommendation"] == "fan-out"
+
+    def test_folder_analysis(self, temp_dir):
+        output_file = str(Path(temp_dir) / "output.json")
+        analyze([temp_dir], output_file)
+        result = json.loads(Path(output_file).read_text())
+        assert result["status"] == "ok"
+        assert result["summary"]["total_files"] >= 4  # at least the base files
+        assert len(result["groups"]) > 0
+
+    def test_no_files_found(self):
+        output_file = "/tmp/test_analyze_empty.json"
+        analyze(["/nonexistent/path"], output_file)
+        result = json.loads(Path(output_file).read_text())
+        assert result["status"] == "error"
+        os.unlink(output_file)
+
+    def test_stdout_output(self, temp_dir, capsys):
+        f = str(Path(temp_dir) / "product-brief-foo.md")
+        analyze([f])
+        captured = capsys.readouterr()
+        result = json.loads(captured.out)
+        assert result["status"] == "ok"
diff --git a/.claude/skills/bmad-document-project/SKILL.md b/.claude/skills/bmad-document-project/SKILL.md
new file mode 100644
index 0000000..09422e1
--- /dev/null
+++ b/.claude/skills/bmad-document-project/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-document-project
+description: 'Document brownfield projects for AI context. Use when the user says "document this project" or "generate project docs"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-document-project/checklist.md b/.claude/skills/bmad-document-project/checklist.md
new file mode 100644
index 0000000..7b67d1e
--- /dev/null
+++ b/.claude/skills/bmad-document-project/checklist.md
@@ -0,0 +1,245 @@
+# Document Project Workflow - Validation Checklist
+
+## Scan Level and Resumability
+
+- [ ] Scan level selection offered (quick/deep/exhaustive) for initial_scan and full_rescan modes
+- [ ] Deep-dive mode automatically uses exhaustive scan (no choice given)
+- [ ] Quick scan does NOT read source files (only patterns, configs, manifests)
+- [ ] Deep scan reads files in critical directories per project type
+- [ ] Exhaustive scan reads ALL source files (excluding node_modules, dist, build)
+- [ ] State file (project-scan-report.json) created at workflow start
+- [ ] State file updated after each step completion
+- [ ] State file contains all required fields per schema
+- [ ] Resumability prompt shown if state file exists and is <24 hours old
+- [ ] Old state files (>24 hours) automatically archived
+- [ ] Resume functionality loads previous state correctly
+- [ ] Workflow can jump to correct step when resuming
+
+## Write-as-you-go Architecture
+
+- [ ] Each document written to disk IMMEDIATELY after generation
+- [ ] Document validation performed right after writing (section-level)
+- [ ] State file updated after each document is written
+- [ ] Detailed findings purged from context after writing (only summaries kept)
+- [ ] Context contains only high-level summaries (1-2 sentences per section)
+- [ ] No accumulation of full project analysis in memory
+
+## Batching Strategy (Deep/Exhaustive Scans)
+
+- [ ] Batching applied for deep and exhaustive scan levels
+- [ ] Batches organized by SUBFOLDER (not arbitrary file count)
+- [ ] Large files (>5000 LOC) handled with appropriate judgment
+- [ ] Each batch: read files, extract info, write output, validate, purge context
+- [ ] Batch completion tracked in state file (batches_completed array)
+- [ ] Batch summaries kept in context (1-2 sentences max)
+
+## Project Detection and Classification
+
+- [ ] Project type correctly identified and matches actual technology stack
+- [ ] Multi-part vs single-part structure accurately detected
+- [ ] All project parts identified if multi-part (no missing client/server/etc.)
+- [ ] Documentation requirements loaded for each part type
+- [ ] Architecture registry match is appropriate for detected stack
+
+## Technology Stack Analysis
+
+- [ ] All major technologies identified (framework, language, database, etc.)
+- [ ] Versions captured where available
+- [ ] Technology decision table is complete and accurate
+- [ ] Dependencies and libraries documented
+- [ ] Build tools and package managers identified
+
+## Codebase Scanning Completeness
+
+- [ ] All critical directories scanned based on project type
+- [ ] API endpoints documented (if requires_api_scan = true)
+- [ ] Data models captured (if requires_data_models = true)
+- [ ] State management patterns identified (if requires_state_management = true)
+- [ ] UI components inventoried (if requires_ui_components = true)
+- [ ] Configuration files located and documented
+- [ ] Authentication/security patterns identified
+- [ ] Entry points correctly identified
+- [ ] Integration points mapped (for multi-part projects)
+- [ ] Test files and patterns documented
+
+## Source Tree Analysis
+
+- [ ] Complete directory tree generated with no major omissions
+- [ ] Critical folders highlighted and described
+- [ ] Entry points clearly marked
+- [ ] Integration paths noted (for multi-part)
+- [ ] Asset locations identified (if applicable)
+- [ ] File organization patterns explained
+
+## Architecture Documentation Quality
+
+- [ ] Architecture document uses appropriate template from registry
+- [ ] All template sections filled with relevant information (no placeholders)
+- [ ] Technology stack section is comprehensive
+- [ ] Architecture pattern clearly explained
+- [ ] Data architecture documented (if applicable)
+- [ ] API design documented (if applicable)
+- [ ] Component structure explained (if applicable)
+- [ ] Source tree included and annotated
+- [ ] Testing strategy documented
+- [ ] Deployment architecture captured (if config found)
+
+## Development and Operations Documentation
+
+- [ ] Prerequisites clearly listed
+- [ ] Installation steps documented
+- [ ] Environment setup instructions provided
+- [ ] Local run commands specified
+- [ ] Build process documented
+- [ ] Test commands and approach explained
+- [ ] Deployment process documented (if applicable)
+- [ ] CI/CD pipeline details captured (if found)
+- [ ] Contribution guidelines extracted (if found)
+
+## Multi-Part Project Specific (if applicable)
+
+- [ ] Each part documented separately
+- [ ] Part-specific architecture files created (architecture-{part_id}.md)
+- [ ] Part-specific component inventories created (if applicable)
+- [ ] Part-specific development guides created
+- [ ] Integration architecture document created
+- [ ] Integration points clearly defined with type and details
+- [ ] Data flow between parts explained
+- [ ] project-parts.json metadata file created
+
+## Index and Navigation
+
+- [ ] index.md created as master entry point
+- [ ] Project structure clearly summarized in index
+- [ ] Quick reference section complete and accurate
+- [ ] All generated docs linked from index
+- [ ] All existing docs linked from index (if found)
+- [ ] Getting started section provides clear next steps
+- [ ] AI-assisted development guidance included
+- [ ] Navigation structure matches project complexity (simple for single-part, detailed for multi-part)
+
+## File Completeness
+
+- [ ] index.md generated
+- [ ] project-overview.md generated
+- [ ] source-tree-analysis.md generated
+- [ ] architecture.md (or per-part) generated
+- [ ] component-inventory.md (or per-part) generated if UI components exist
+- [ ] development-guide.md (or per-part) generated
+- [ ] api-contracts.md (or per-part) generated if APIs documented
+- [ ] data-models.md (or per-part) generated if data models found
+- [ ] deployment-guide.md generated if deployment config found
+- [ ] contribution-guide.md generated if guidelines found
+- [ ] integration-architecture.md generated if multi-part
+- [ ] project-parts.json generated if multi-part
+
+## Content Quality
+
+- [ ] Technical information is accurate and specific
+- [ ] No generic placeholders or "TODO" items remain
+- [ ] Examples and code snippets are relevant to actual project
+- [ ] File paths and directory references are correct
+- [ ] Technology names and versions are accurate
+- [ ] Terminology is consistent across all documents
+- [ ] Descriptions are clear and actionable
+
+## Brownfield PRD Readiness
+
+- [ ] Documentation provides enough context for AI to understand existing system
+- [ ] Integration points are clear for planning new features
+- [ ] Reusable components are identified for leveraging in new work
+- [ ] Data models are documented for schema extension planning
+- [ ] API contracts are documented for endpoint expansion
+- [ ] Code conventions and patterns are captured for consistency
+- [ ] Architecture constraints are clear for informed decision-making
+
+## Output Validation
+
+- [ ] All files saved to correct output folder
+- [ ] File naming follows convention (no part suffix for single-part, with suffix for multi-part)
+- [ ] No broken internal links between documents
+- [ ] Markdown formatting is correct and renders properly
+- [ ] JSON files are valid (project-parts.json if applicable)
+
+## Final Validation
+
+- [ ] User confirmed project classification is accurate
+- [ ] User provided any additional context needed
+- [ ] All requested areas of focus addressed
+- [ ] Documentation is immediately usable for brownfield PRD workflow
+- [ ] No critical information gaps identified
+
+## Issues Found
+
+### Critical Issues (must fix before completion)
+
+-
+
+### Minor Issues (can be addressed later)
+
+-
+
+### Missing Information (to note for user)
+
+-
+
+## Deep-Dive Mode Validation (if deep-dive was performed)
+
+- [ ] Deep-dive target area correctly identified and scoped
+- [ ] All files in target area read completely (no skipped files)
+- [ ] File inventory includes all exports with complete signatures
+- [ ] Dependencies mapped for all files
+- [ ] Dependents identified (who imports each file)
+- [ ] Code snippets included for key implementation details
+- [ ] Patterns and design approaches documented
+- [ ] State management strategy explained
+- [ ] Side effects documented (API calls, DB queries, etc.)
+- [ ] Error handling approaches captured
+- [ ] Testing files and coverage documented
+- [ ] TODOs and comments extracted
+- [ ] Dependency graph created showing relationships
+- [ ] Data flow traced through the scanned area
+- [ ] Integration points with rest of codebase identified
+- [ ] Related code and similar patterns found outside scanned area
+- [ ] Reuse opportunities documented
+- [ ] Implementation guidance provided
+- [ ] Modification instructions clear
+- [ ] Index.md updated with deep-dive link
+- [ ] Deep-dive documentation is immediately useful for implementation
+
+---
+
+## State File Quality
+
+- [ ] State file is valid JSON (no syntax errors)
+- [ ] State file is optimized (no pretty-printing, minimal whitespace)
+- [ ] State file contains all completed steps with timestamps
+- [ ] State file outputs_generated list is accurate and complete
+- [ ] State file resume_instructions are clear and actionable
+- [ ] State file findings contain only high-level summaries (not detailed data)
+- [ ] State file can be successfully loaded for resumption
+
+## Completion Criteria
+
+All items in the following sections must be checked:
+
+- ✓ Scan Level and Resumability
+- ✓ Write-as-you-go Architecture
+- ✓ Batching Strategy (if deep/exhaustive scan)
+- ✓ Project Detection and Classification
+- ✓ Technology Stack Analysis
+- ✓ Architecture Documentation Quality
+- ✓ Index and Navigation
+- ✓ File Completeness
+- ✓ Brownfield PRD Readiness
+- ✓ State File Quality
+- ✓ Deep-Dive Mode Validation (if applicable)
+
+The workflow is complete when:
+
+1. All critical checklist items are satisfied
+2. No critical issues remain
+3. User has reviewed and approved the documentation
+4. Generated docs are ready for use in brownfield PRD workflow
+5. Deep-dive docs (if any) are comprehensive and implementation-ready
+6. State file is valid and can enable resumption if interrupted
diff --git a/.claude/skills/bmad-document-project/documentation-requirements.csv b/.claude/skills/bmad-document-project/documentation-requirements.csv
new file mode 100644
index 0000000..9f773ab
--- /dev/null
+++ b/.claude/skills/bmad-document-project/documentation-requirements.csv
@@ -0,0 +1,12 @@
+project_type_id,requires_api_scan,requires_data_models,requires_state_management,requires_ui_components,requires_deployment_config,key_file_patterns,critical_directories,integration_scan_patterns,test_file_patterns,config_patterns,auth_security_patterns,schema_migration_patterns,entry_point_patterns,shared_code_patterns,monorepo_workspace_patterns,async_event_patterns,ci_cd_patterns,asset_patterns,hardware_interface_patterns,protocol_schema_patterns,localization_patterns,requires_hardware_docs,requires_asset_inventory
+web,true,true,true,true,true,package.json;tsconfig.json;*.config.js;*.config.ts;vite.config.*;webpack.config.*;next.config.*;nuxt.config.*,src/;app/;pages/;components/;api/;lib/;styles/;public/;static/,*client.ts;*service.ts;*api.ts;fetch*.ts;axios*.ts;*http*.ts,*.test.ts;*.spec.ts;*.test.tsx;*.spec.tsx;**/__tests__/**;**/*.test.*;**/*.spec.*,.env*;config/*;*.config.*;.config/;settings/,*auth*.ts;*session*.ts;middleware/auth*;*.guard.ts;*authenticat*;*permission*;guards/,migrations/**;prisma/**;*.prisma;alembic/**;knex/**;*migration*.sql;*migration*.ts,main.ts;index.ts;app.ts;server.ts;_app.tsx;_app.ts;layout.tsx,shared/**;common/**;utils/**;lib/**;helpers/**;@*/**;packages/**,pnpm-workspace.yaml;lerna.json;nx.json;turbo.json;workspace.json;rush.json,*event*.ts;*queue*.ts;*subscriber*.ts;*consumer*.ts;*producer*.ts;*worker*.ts;jobs/**,.github/workflows/**;.gitlab-ci.yml;Jenkinsfile;.circleci/**;azure-pipelines.yml;bitbucket-pipelines.yml,.drone.yml,public/**;static/**;assets/**;images/**;media/**,N/A,*.proto;*.graphql;graphql/**;schema.graphql;*.avro;openapi.*;swagger.*,i18n/**;locales/**;lang/**;translations/**;messages/**;*.po;*.pot,false,false
+mobile,true,true,true,true,true,package.json;pubspec.yaml;Podfile;build.gradle;app.json;capacitor.config.*;ionic.config.json,src/;app/;screens/;components/;services/;models/;assets/;ios/;android/,*client.ts;*service.ts;*api.ts;fetch*.ts;axios*.ts;*http*.ts,*.test.ts;*.test.tsx;*_test.dart;*.test.dart;**/__tests__/**,.env*;config/*;app.json;capacitor.config.*;google-services.json;GoogleService-Info.plist,*auth*.ts;*session*.ts;*authenticat*;*permission*;*biometric*;secure-store*,migrations/**;realm/**;*.realm;watermelondb/**;sqlite/**,main.ts;index.ts;App.tsx;App.ts;main.dart,shared/**;common/**;utils/**;lib/**;components/shared/**;@*/**,pnpm-workspace.yaml;lerna.json;nx.json;turbo.json,*event*.ts;*notification*.ts;*push*.ts;background-fetch*,fastlane/**;.github/workflows/**;.gitlab-ci.yml;bitbucket-pipelines.yml;appcenter-*,assets/**;Resources/**;res/**;*.xcassets;drawable*/;mipmap*/;images/**,N/A,*.proto;graphql/**;*.graphql,i18n/**;locales/**;translations/**;*.strings;*.xml,false,true
+backend,true,true,false,false,true,package.json;requirements.txt;go.mod;Gemfile;pom.xml;build.gradle;Cargo.toml;*.csproj,src/;api/;services/;models/;routes/;controllers/;middleware/;handlers/;repositories/;domain/,*client.ts;*repository.ts;*service.ts;*connector*.ts;*adapter*.ts,*.test.ts;*.spec.ts;*_test.go;test_*.py;*Test.java;*_test.rs,.env*;config/*;*.config.*;application*.yml;application*.yaml;appsettings*.json;settings.py,*auth*.ts;*session*.ts;*authenticat*;*authorization*;middleware/auth*;guards/;*jwt*;*oauth*,migrations/**;alembic/**;flyway/**;liquibase/**;prisma/**;*.prisma;*migration*.sql;*migration*.ts;db/migrate,main.ts;index.ts;server.ts;app.ts;main.go;main.py;Program.cs;__init__.py,shared/**;common/**;utils/**;lib/**;core/**;@*/**;pkg/**,pnpm-workspace.yaml;lerna.json;nx.json;go.work,*event*.ts;*queue*.ts;*subscriber*.ts;*consumer*.ts;*producer*.ts;*worker*.ts;*handler*.ts;jobs/**;workers/**,.github/workflows/**;.gitlab-ci.yml;Jenkinsfile;.circleci/**;azure-pipelines.yml;.drone.yml,N/A,N/A,*.proto;*.graphql;graphql/**;*.avro;*.thrift;openapi.*;swagger.*;schema/**,N/A,false,false
+cli,false,false,false,false,false,package.json;go.mod;Cargo.toml;setup.py;pyproject.toml;*.gemspec,src/;cmd/;cli/;bin/;lib/;commands/,N/A,*.test.ts;*_test.go;test_*.py;*.spec.ts;*_spec.rb,.env*;config/*;*.config.*;.*.rc;.*rc,N/A,N/A,main.ts;index.ts;cli.ts;main.go;main.py;__main__.py;bin/*,shared/**;common/**;utils/**;lib/**;helpers/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml;goreleaser.yml,N/A,N/A,N/A,N/A,false,false
+library,false,false,false,false,false,package.json;setup.py;Cargo.toml;go.mod;*.gemspec;*.csproj;pom.xml,src/;lib/;dist/;pkg/;build/;target/,N/A,*.test.ts;*_test.go;test_*.py;*.spec.ts;*Test.java;*_test.rs,.*.rc;tsconfig.json;rollup.config.*;vite.config.*;webpack.config.*,N/A,N/A,index.ts;index.js;lib.rs;main.go;__init__.py,src/**;lib/**;core/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml;.circleci/**,N/A,N/A,N/A,N/A,false,false
+desktop,false,false,true,true,true,package.json;Cargo.toml;*.csproj;CMakeLists.txt;tauri.conf.json;electron-builder.yml;wails.json,src/;app/;components/;main/;renderer/;resources/;assets/;build/,*service.ts;ipc*.ts;*bridge*.ts;*native*.ts;invoke*,*.test.ts;*.spec.ts;*_test.rs;*.spec.tsx,.env*;config/*;*.config.*;app.config.*;forge.config.*;builder.config.*,*auth*.ts;*session*.ts;keychain*;secure-storage*,N/A,main.ts;index.ts;main.js;src-tauri/main.rs;electron.ts,shared/**;common/**;utils/**;lib/**;components/shared/**,N/A,*event*.ts;*ipc*.ts;*message*.ts,.github/workflows/**;.gitlab-ci.yml;.circleci/**,resources/**;assets/**;icons/**;static/**;build/resources,N/A,N/A,i18n/**;locales/**;translations/**;lang/**,false,true
+game,false,false,true,false,false,*.unity;*.godot;*.uproject;package.json;project.godot,Assets/;Scenes/;Scripts/;Prefabs/;Resources/;Content/;Source/;src/;scenes/;scripts/,N/A,*Test.cs;*_test.gd;*Test.cpp;*.test.ts,.env*;config/*;*.ini;settings/;GameSettings/,N/A,N/A,main.gd;Main.cs;GameManager.cs;main.cpp;index.ts,shared/**;common/**;utils/**;Core/**;Framework/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml,Assets/**;Scenes/**;Prefabs/**;Materials/**;Textures/**;Audio/**;Models/**;*.fbx;*.blend;*.shader;*.hlsl;*.glsl;Shaders/**;VFX/**,N/A,N/A,Localization/**;Languages/**;i18n/**,false,true
+data,false,true,false,false,true,requirements.txt;pyproject.toml;dbt_project.yml;airflow.cfg;setup.py;Pipfile,dags/;pipelines/;models/;transformations/;notebooks/;sql/;etl/;jobs/,N/A,test_*.py;*_test.py;tests/**,.env*;config/*;profiles.yml;dbt_project.yml;airflow.cfg,N/A,migrations/**;dbt/models/**;*.sql;schemas/**,main.py;__init__.py;pipeline.py;dag.py,shared/**;common/**;utils/**;lib/**;helpers/**,N/A,*event*.py;*consumer*.py;*producer*.py;*worker*.py;jobs/**;tasks/**,.github/workflows/**;.gitlab-ci.yml;airflow/dags/**,N/A,N/A,*.proto;*.avro;schemas/**;*.parquet,N/A,false,false
+extension,true,false,true,true,false,manifest.json;package.json;wxt.config.ts,src/;popup/;content/;background/;assets/;components/,*message.ts;*runtime.ts;*storage.ts;*tabs.ts,*.test.ts;*.spec.ts;*.test.tsx,.env*;wxt.config.*;webpack.config.*;vite.config.*,*auth*.ts;*session*.ts;*permission*,N/A,index.ts;popup.ts;background.ts;content.ts,shared/**;common/**;utils/**;lib/**,N/A,*message*.ts;*event*.ts;chrome.runtime*;browser.runtime*,.github/workflows/**,assets/**;icons/**;images/**;static/**,N/A,N/A,_locales/**;locales/**;i18n/**,false,false
+infra,false,false,false,false,true,*.tf;*.tfvars;pulumi.yaml;cdk.json;*.yml;*.yaml;Dockerfile;docker-compose*.yml,terraform/;modules/;k8s/;charts/;playbooks/;roles/;policies/;stacks/,N/A,*_test.go;test_*.py;*_test.tf;*_spec.rb,.env*;*.tfvars;config/*;vars/;group_vars/;host_vars/,N/A,N/A,main.tf;index.ts;__main__.py;playbook.yml,modules/**;shared/**;common/**;lib/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml;.circleci/**,N/A,N/A,N/A,N/A,false,false
+embedded,false,false,false,false,false,platformio.ini;CMakeLists.txt;*.ino;Makefile;*.ioc;mbed-os.lib,src/;lib/;include/;firmware/;drivers/;hal/;bsp/;components/,N/A,test_*.c;*_test.cpp;*_test.c;tests/**,.env*;config/*;sdkconfig;*.json;settings/,N/A,N/A,main.c;main.cpp;main.ino;app_main.c,lib/**;shared/**;common/**;drivers/**,N/A,N/A,.github/workflows/**;.gitlab-ci.yml,N/A,*.h;*.hpp;drivers/**;hal/**;bsp/**;pinout.*;peripheral*;gpio*;*.fzz;schematics/**,*.proto;mqtt*;coap*;modbus*,N/A,true,false
diff --git a/.claude/skills/bmad-document-project/instructions.md b/.claude/skills/bmad-document-project/instructions.md
new file mode 100644
index 0000000..4a57b88
--- /dev/null
+++ b/.claude/skills/bmad-document-project/instructions.md
@@ -0,0 +1,128 @@
+# Document Project Workflow Router
+
+<critical>Communicate all responses in {communication_language}</critical>
+
+<workflow>
+
+<critical>This router determines workflow mode and delegates to specialized sub-workflows</critical>
+
+<step n="1" goal="Check for ability to resume and determine workflow mode">
+<action>Check for existing state file at: {project_knowledge}/project-scan-report.json</action>
+
+<check if="project-scan-report.json exists">
+  <action>Read state file and extract: timestamps, mode, scan_level, current_step, completed_steps, project_classification</action>
+  <action>Extract cached project_type_id(s) from state file if present</action>
+  <action>Calculate age of state file (current time - last_updated)</action>
+
+<ask>I found an in-progress workflow state from {{last_updated}}.
+
+    **Current Progress:**
+
+    - Mode: {{mode}}
+    - Scan Level: {{scan_level}}
+    - Completed Steps: {{completed_steps_count}}/{{total_steps}}
+    - Last Step: {{current_step}}
+    - Project Type(s): {{cached_project_types}}
+
+    Would you like to:
+
+    1. **Resume from where we left off** - Continue from step {{current_step}}
+    2. **Start fresh** - Archive old state and begin new scan
+    3. **Cancel** - Exit without changes
+
+    Your choice [1/2/3]:
+</ask>
+
+  <check if="user selects 1">
+    <action>Set resume_mode = true</action>
+    <action>Set workflow_mode = {{mode}}</action>
+    <action>Load findings summaries from state file</action>
+    <action>Load cached project_type_id(s) from state file</action>
+
+    <critical>CONDITIONAL CSV LOADING FOR RESUME:</critical>
+    <action>For each cached project_type_id, load ONLY the corresponding row from: ./documentation-requirements.csv</action>
+    <action>Skip loading project-types.csv and architecture_registry.csv (not needed on resume)</action>
+    <action>Store loaded doc requirements for use in remaining steps</action>
+
+    <action>Display: "Resuming {{workflow_mode}} from {{current_step}} with cached project type(s): {{cached_project_types}}"</action>
+
+    <check if="workflow_mode == deep_dive">
+      <action>Read fully and follow: ./workflows/deep-dive-workflow.md with resume context</action>
+    </check>
+
+    <check if="workflow_mode == initial_scan OR workflow_mode == full_rescan">
+      <action>Read fully and follow: ./workflows/full-scan-workflow.md with resume context</action>
+    </check>
+
+  </check>
+
+  <check if="user selects 2">
+    <action>Create archive directory: {project_knowledge}/.archive/</action>
+    <action>Move old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <action>Set resume_mode = false</action>
+    <action>Continue to Step 0.5</action>
+  </check>
+
+  <check if="user selects 3">
+    <action>Display: "Exiting workflow without changes."</action>
+    <action>Exit workflow</action>
+  </check>
+
+  <check if="state file age >= 24 hours">
+    <action>Display: "Found old state file (>24 hours). Starting fresh scan."</action>
+    <action>Archive old state file to: {project_knowledge}/.archive/project-scan-report-{{timestamp}}.json</action>
+    <action>Set resume_mode = false</action>
+    <action>Continue to Step 0.5</action>
+  </check>
+
+</step>
+
+<step n="3" goal="Check for existing documentation and determine workflow mode" if="resume_mode == false">
+<action>Check if {project_knowledge}/index.md exists</action>
+
+<check if="index.md exists">
+  <action>Read existing index.md to extract metadata (date, project structure, parts count)</action>
+  <action>Store as {{existing_doc_date}}, {{existing_structure}}</action>
+
+<ask>I found existing documentation generated on {{existing_doc_date}}.
+
+What would you like to do?
+
+1. **Re-scan entire project** - Update all documentation with latest changes
+2. **Deep-dive into specific area** - Generate detailed documentation for a particular feature/module/folder
+3. **Cancel** - Keep existing documentation as-is
+
+Your choice [1/2/3]:
+</ask>
+
+  <check if="user selects 1">
+    <action>Set workflow_mode = "full_rescan"</action>
+    <action>Display: "Starting full project rescan..."</action>
+    <action>Read fully and follow: ./workflows/full-scan-workflow.md</action>
+    <action>After sub-workflow completes, continue to Step 4</action>
+  </check>
+
+  <check if="user selects 2">
+    <action>Set workflow_mode = "deep_dive"</action>
+    <action>Set scan_level = "exhaustive"</action>
+    <action>Display: "Starting deep-dive documentation mode..."</action>
+    <action>Read fully and follow: ./workflows/deep-dive-workflow.md</action>
+    <action>After sub-workflow completes, continue to Step 4</action>
+  </check>
+
+  <check if="user selects 3">
+    <action>Display message: "Keeping existing documentation. Exiting workflow."</action>
+    <action>Exit workflow</action>
+  </check>
+</check>
+
+<check if="index.md does not exist">
+  <action>Set workflow_mode = "initial_scan"</action>
+  <action>Display: "No existing documentation found. Starting initial project scan..."</action>
+  <action>Read fully and follow: ./workflows/full-scan-workflow.md</action>
+  <action>After sub-workflow completes, continue to Step 4</action>
+</check>
+
+</step>
+
+</workflow>
diff --git a/.claude/skills/bmad-document-project/templates/deep-dive-template.md b/.claude/skills/bmad-document-project/templates/deep-dive-template.md
new file mode 100644
index 0000000..c1285cd
--- /dev/null
+++ b/.claude/skills/bmad-document-project/templates/deep-dive-template.md
@@ -0,0 +1,345 @@
+# {{target_name}} - Deep Dive Documentation
+
+**Generated:** {{date}}
+**Scope:** {{target_path}}
+**Files Analyzed:** {{file_count}}
+**Lines of Code:** {{total_loc}}
+**Workflow Mode:** Exhaustive Deep-Dive
+
+## Overview
+
+{{target_description}}
+
+**Purpose:** {{target_purpose}}
+**Key Responsibilities:** {{responsibilities}}
+**Integration Points:** {{integration_summary}}
+
+## Complete File Inventory
+
+{{#each files_in_inventory}}
+
+### {{file_path}}
+
+**Purpose:** {{purpose}}
+**Lines of Code:** {{loc}}
+**File Type:** {{file_type}}
+
+**What Future Contributors Must Know:** {{contributor_note}}
+
+**Exports:**
+{{#each exports}}
+
+- `{{signature}}` - {{description}}
+  {{/each}}
+
+**Dependencies:**
+{{#each imports}}
+
+- `{{import_path}}` - {{reason}}
+  {{/each}}
+
+**Used By:**
+{{#each dependents}}
+
+- `{{dependent_path}}`
+  {{/each}}
+
+**Key Implementation Details:**
+
+```{{language}}
+{{key_code_snippet}}
+```
+
+{{implementation_notes}}
+
+**Patterns Used:**
+{{#each patterns}}
+
+- {{pattern_name}}: {{pattern_description}}
+  {{/each}}
+
+**State Management:** {{state_approach}}
+
+**Side Effects:**
+{{#each side_effects}}
+
+- {{effect_type}}: {{effect_description}}
+  {{/each}}
+
+**Error Handling:** {{error_handling_approach}}
+
+**Testing:**
+
+- Test File: {{test_file_path}}
+- Coverage: {{coverage_percentage}}%
+- Test Approach: {{test_approach}}
+
+**Comments/TODOs:**
+{{#each todos}}
+
+- Line {{line_number}}: {{todo_text}}
+  {{/each}}
+
+---
+
+{{/each}}
+
+## Contributor Checklist
+
+- **Risks & Gotchas:** {{risks_notes}}
+- **Pre-change Verification Steps:** {{verification_steps}}
+- **Suggested Tests Before PR:** {{suggested_tests}}
+
+## Architecture & Design Patterns
+
+### Code Organization
+
+{{organization_approach}}
+
+### Design Patterns
+
+{{#each design_patterns}}
+
+- **{{pattern_name}}**: {{usage_description}}
+  {{/each}}
+
+### State Management Strategy
+
+{{state_management_details}}
+
+### Error Handling Philosophy
+
+{{error_handling_philosophy}}
+
+### Testing Strategy
+
+{{testing_strategy}}
+
+## Data Flow
+
+{{data_flow_diagram}}
+
+### Data Entry Points
+
+{{#each entry_points}}
+
+- **{{entry_name}}**: {{entry_description}}
+  {{/each}}
+
+### Data Transformations
+
+{{#each transformations}}
+
+- **{{transformation_name}}**: {{transformation_description}}
+  {{/each}}
+
+### Data Exit Points
+
+{{#each exit_points}}
+
+- **{{exit_name}}**: {{exit_description}}
+  {{/each}}
+
+## Integration Points
+
+### APIs Consumed
+
+{{#each apis_consumed}}
+
+- **{{api_endpoint}}**: {{api_description}}
+  - Method: {{method}}
+  - Authentication: {{auth_requirement}}
+  - Response: {{response_schema}}
+    {{/each}}
+
+### APIs Exposed
+
+{{#each apis_exposed}}
+
+- **{{api_endpoint}}**: {{api_description}}
+  - Method: {{method}}
+  - Request: {{request_schema}}
+  - Response: {{response_schema}}
+    {{/each}}
+
+### Shared State
+
+{{#each shared_state}}
+
+- **{{state_name}}**: {{state_description}}
+  - Type: {{state_type}}
+  - Accessed By: {{accessors}}
+    {{/each}}
+
+### Events
+
+{{#each events}}
+
+- **{{event_name}}**: {{event_description}}
+  - Type: {{publish_or_subscribe}}
+  - Payload: {{payload_schema}}
+    {{/each}}
+
+### Database Access
+
+{{#each database_operations}}
+
+- **{{table_name}}**: {{operation_type}}
+  - Queries: {{query_patterns}}
+  - Indexes Used: {{indexes}}
+    {{/each}}
+
+## Dependency Graph
+
+{{dependency_graph_visualization}}
+
+### Entry Points (Not Imported by Others in Scope)
+
+{{#each entry_point_files}}
+
+- {{file_path}}
+  {{/each}}
+
+### Leaf Nodes (Don't Import Others in Scope)
+
+{{#each leaf_files}}
+
+- {{file_path}}
+  {{/each}}
+
+### Circular Dependencies
+
+{{#if has_circular_dependencies}}
+⚠️ Circular dependencies detected:
+{{#each circular_deps}}
+
+- {{cycle_description}}
+  {{/each}}
+  {{else}}
+  ✓ No circular dependencies detected
+  {{/if}}
+
+## Testing Analysis
+
+### Test Coverage Summary
+
+- **Statements:** {{statements_coverage}}%
+- **Branches:** {{branches_coverage}}%
+- **Functions:** {{functions_coverage}}%
+- **Lines:** {{lines_coverage}}%
+
+### Test Files
+
+{{#each test_files}}
+
+- **{{test_file_path}}**
+  - Tests: {{test_count}}
+  - Approach: {{test_approach}}
+  - Mocking Strategy: {{mocking_strategy}}
+    {{/each}}
+
+### Test Utilities Available
+
+{{#each test_utilities}}
+
+- `{{utility_name}}`: {{utility_description}}
+  {{/each}}
+
+### Testing Gaps
+
+{{#each testing_gaps}}
+
+- {{gap_description}}
+  {{/each}}
+
+## Related Code & Reuse Opportunities
+
+### Similar Features Elsewhere
+
+{{#each similar_features}}
+
+- **{{feature_name}}** (`{{feature_path}}`)
+  - Similarity: {{similarity_description}}
+  - Can Reference For: {{reference_use_case}}
+    {{/each}}
+
+### Reusable Utilities Available
+
+{{#each reusable_utilities}}
+
+- **{{utility_name}}** (`{{utility_path}}`)
+  - Purpose: {{utility_purpose}}
+  - How to Use: {{usage_example}}
+    {{/each}}
+
+### Patterns to Follow
+
+{{#each patterns_to_follow}}
+
+- **{{pattern_name}}**: Reference `{{reference_file}}` for implementation
+  {{/each}}
+
+## Implementation Notes
+
+### Code Quality Observations
+
+{{#each quality_observations}}
+
+- {{observation}}
+  {{/each}}
+
+### TODOs and Future Work
+
+{{#each all_todos}}
+
+- **{{file_path}}:{{line_number}}**: {{todo_text}}
+  {{/each}}
+
+### Known Issues
+
+{{#each known_issues}}
+
+- {{issue_description}}
+  {{/each}}
+
+### Optimization Opportunities
+
+{{#each optimizations}}
+
+- {{optimization_suggestion}}
+  {{/each}}
+
+### Technical Debt
+
+{{#each tech_debt_items}}
+
+- {{debt_description}}
+  {{/each}}
+
+## Modification Guidance
+
+### To Add New Functionality
+
+{{modification_guidance_add}}
+
+### To Modify Existing Functionality
+
+{{modification_guidance_modify}}
+
+### To Remove/Deprecate
+
+{{modification_guidance_remove}}
+
+### Testing Checklist for Changes
+
+{{#each testing_checklist_items}}
+
+- [ ] {{checklist_item}}
+      {{/each}}
+
+---
+
+_Generated by `document-project` workflow (deep-dive mode)_
+_Base Documentation: docs/index.md_
+_Scan Date: {{date}}_
+_Analysis Mode: Exhaustive_
diff --git a/.claude/skills/bmad-document-project/templates/index-template.md b/.claude/skills/bmad-document-project/templates/index-template.md
new file mode 100644
index 0000000..0340a35
--- /dev/null
+++ b/.claude/skills/bmad-document-project/templates/index-template.md
@@ -0,0 +1,169 @@
+# {{project_name}} Documentation Index
+
+**Type:** {{repository_type}}{{#if is_multi_part}} with {{parts_count}} parts{{/if}}
+**Primary Language:** {{primary_language}}
+**Architecture:** {{architecture_type}}
+**Last Updated:** {{date}}
+
+## Project Overview
+
+{{project_description}}
+
+{{#if is_multi_part}}
+
+## Project Structure
+
+This project consists of {{parts_count}} parts:
+
+{{#each project_parts}}
+
+### {{part_name}} ({{part_id}})
+
+- **Type:** {{project_type}}
+- **Location:** `{{root_path}}`
+- **Tech Stack:** {{tech_stack_summary}}
+- **Entry Point:** {{entry_point}}
+  {{/each}}
+
+## Cross-Part Integration
+
+{{integration_summary}}
+
+{{/if}}
+
+## Quick Reference
+
+{{#if is_single_part}}
+
+- **Tech Stack:** {{tech_stack_summary}}
+- **Entry Point:** {{entry_point}}
+- **Architecture Pattern:** {{architecture_pattern}}
+- **Database:** {{database}}
+- **Deployment:** {{deployment_platform}}
+  {{else}}
+  {{#each project_parts}}
+
+### {{part_name}} Quick Ref
+
+- **Stack:** {{tech_stack_summary}}
+- **Entry:** {{entry_point}}
+- **Pattern:** {{architecture_pattern}}
+  {{/each}}
+  {{/if}}
+
+## Generated Documentation
+
+### Core Documentation
+
+- [Project Overview](./project-overview.md) - Executive summary and high-level architecture
+- [Source Tree Analysis](./source-tree-analysis.md) - Annotated directory structure
+
+{{#if is_single_part}}
+
+- [Architecture](./architecture.md) - Detailed technical architecture
+- [Component Inventory](./component-inventory.md) - Catalog of major components{{#if has_ui_components}} and UI elements{{/if}}
+- [Development Guide](./development-guide.md) - Local setup and development workflow
+  {{#if has_api_docs}}- [API Contracts](./api-contracts.md) - API endpoints and schemas{{/if}}
+  {{#if has_data_models}}- [Data Models](./data-models.md) - Database schema and models{{/if}}
+  {{else}}
+
+### Part-Specific Documentation
+
+{{#each project_parts}}
+
+#### {{part_name}} ({{part_id}})
+
+- [Architecture](./architecture-{{part_id}}.md) - Technical architecture for {{part_name}}
+  {{#if has_components}}- [Components](./component-inventory-{{part_id}}.md) - Component catalog{{/if}}
+- [Development Guide](./development-guide-{{part_id}}.md) - Setup and dev workflow
+  {{#if has_api}}- [API Contracts](./api-contracts-{{part_id}}.md) - API documentation{{/if}}
+  {{#if has_data}}- [Data Models](./data-models-{{part_id}}.md) - Data architecture{{/if}}
+  {{/each}}
+
+### Integration
+
+- [Integration Architecture](./integration-architecture.md) - How parts communicate
+- [Project Parts Metadata](./project-parts.json) - Machine-readable structure
+  {{/if}}
+
+### Optional Documentation
+
+{{#if has_deployment_guide}}- [Deployment Guide](./deployment-guide.md) - Deployment process and infrastructure{{/if}}
+{{#if has_contribution_guide}}- [Contribution Guide](./contribution-guide.md) - Contributing guidelines and standards{{/if}}
+
+## Existing Documentation
+
+{{#if has_existing_docs}}
+{{#each existing_docs}}
+
+- [{{title}}]({{path}}) - {{description}}
+  {{/each}}
+  {{else}}
+  No existing documentation files were found in the project.
+  {{/if}}
+
+## Getting Started
+
+{{#if is_single_part}}
+
+### Prerequisites
+
+{{prerequisites}}
+
+### Setup
+
+```bash
+{{setup_commands}}
+```
+
+### Run Locally
+
+```bash
+{{run_commands}}
+```
+
+### Run Tests
+
+```bash
+{{test_commands}}
+```
+
+{{else}}
+{{#each project_parts}}
+
+### {{part_name}} Setup
+
+**Prerequisites:** {{prerequisites}}
+
+**Install & Run:**
+
+```bash
+cd {{root_path}}
+{{setup_command}}
+{{run_command}}
+```
+
+{{/each}}
+{{/if}}
+
+## For AI-Assisted Development
+
+This documentation was generated specifically to enable AI agents to understand and extend this codebase.
+
+### When Planning New Features:
+
+**UI-only features:**
+{{#if is_multi_part}}→ Reference: `architecture-{{ui_part_id}}.md`, `component-inventory-{{ui_part_id}}.md`{{else}}→ Reference: `architecture.md`, `component-inventory.md`{{/if}}
+
+**API/Backend features:**
+{{#if is_multi_part}}→ Reference: `architecture-{{api_part_id}}.md`, `api-contracts-{{api_part_id}}.md`, `data-models-{{api_part_id}}.md`{{else}}→ Reference: `architecture.md`{{#if has_api_docs}}, `api-contracts.md`{{/if}}{{#if has_data_models}}, `data-models.md`{{/if}}{{/if}}
+
+**Full-stack features:**
+→ Reference: All architecture docs{{#if is_multi_part}} + `integration-architecture.md`{{/if}}
+
+**Deployment changes:**
+{{#if has_deployment_guide}}→ Reference: `deployment-guide.md`{{else}}→ Review CI/CD configs in project{{/if}}
+
+---
+
+_Documentation generated by BMAD Method `document-project` workflow_
diff --git a/.claude/skills/bmad-document-project/templates/project-overview-template.md b/.claude/skills/bmad-document-project/templates/project-overview-template.md
new file mode 100644
index 0000000..3bbb0d2
--- /dev/null
+++ b/.claude/skills/bmad-document-project/templates/project-overview-template.md
@@ -0,0 +1,103 @@
+# {{project_name}} - Project Overview
+
+**Date:** {{date}}
+**Type:** {{project_type}}
+**Architecture:** {{architecture_type}}
+
+## Executive Summary
+
+{{executive_summary}}
+
+## Project Classification
+
+- **Repository Type:** {{repository_type}}
+- **Project Type(s):** {{project_types_list}}
+- **Primary Language(s):** {{primary_languages}}
+- **Architecture Pattern:** {{architecture_pattern}}
+
+{{#if is_multi_part}}
+
+## Multi-Part Structure
+
+This project consists of {{parts_count}} distinct parts:
+
+{{#each project_parts}}
+
+### {{part_name}}
+
+- **Type:** {{project_type}}
+- **Location:** `{{root_path}}`
+- **Purpose:** {{purpose}}
+- **Tech Stack:** {{tech_stack}}
+  {{/each}}
+
+### How Parts Integrate
+
+{{integration_description}}
+{{/if}}
+
+## Technology Stack Summary
+
+{{#if is_single_part}}
+{{technology_table}}
+{{else}}
+{{#each project_parts}}
+
+### {{part_name}} Stack
+
+{{technology_table}}
+{{/each}}
+{{/if}}
+
+## Key Features
+
+{{key_features}}
+
+## Architecture Highlights
+
+{{architecture_highlights}}
+
+## Development Overview
+
+### Prerequisites
+
+{{prerequisites}}
+
+### Getting Started
+
+{{getting_started_summary}}
+
+### Key Commands
+
+{{#if is_single_part}}
+
+- **Install:** `{{install_command}}`
+- **Dev:** `{{dev_command}}`
+- **Build:** `{{build_command}}`
+- **Test:** `{{test_command}}`
+  {{else}}
+  {{#each project_parts}}
+
+#### {{part_name}}
+
+- **Install:** `{{install_command}}`
+- **Dev:** `{{dev_command}}`
+  {{/each}}
+  {{/if}}
+
+## Repository Structure
+
+{{repository_structure_summary}}
+
+## Documentation Map
+
+For detailed information, see:
+
+- [index.md](./index.md) - Master documentation index
+- [architecture.md](./architecture{{#if is_multi_part}}-{part_id}{{/if}}.md) - Detailed architecture
+- [source-tree-analysis.md](./source-tree-analysis.md) - Directory structure
+- [development-guide.md](./development-guide{{#if is_multi_part}}-{part_id}{{/if}}.md) - Development workflow
+
+---
+
+_Generated using BMAD Method `document-project` workflow_
diff --git a/.claude/skills/bmad-document-project/templates/project-scan-report-schema.json b/.claude/skills/bmad-document-project/templates/project-scan-report-schema.json
new file mode 100644
index 0000000..69e0598
--- /dev/null
+++ b/.claude/skills/bmad-document-project/templates/project-scan-report-schema.json
@@ -0,0 +1,160 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Project Scan Report Schema",
+  "description": "State tracking file for document-project workflow resumability",
+  "type": "object",
+  "required": ["workflow_version", "timestamps", "mode", "scan_level", "completed_steps", "current_step"],
+  "properties": {
+    "workflow_version": {
+      "type": "string",
+      "description": "Version of document-project workflow",
+      "example": "1.2.0"
+    },
+    "timestamps": {
+      "type": "object",
+      "required": ["started", "last_updated"],
+      "properties": {
+        "started": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow started"
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of last state update"
+        },
+        "completed": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow completed (if finished)"
+        }
+      }
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["initial_scan", "full_rescan", "deep_dive"],
+      "description": "Workflow execution mode"
+    },
+    "scan_level": {
+      "type": "string",
+      "enum": ["quick", "deep", "exhaustive"],
+      "description": "Scan depth level (deep_dive mode always uses exhaustive)"
+    },
+    "project_root": {
+      "type": "string",
+      "description": "Absolute path to project root directory"
+    },
+    "project_knowledge": {
+      "type": "string",
+      "description": "Absolute path to project knowledge folder"
+    },
+    "completed_steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["step", "status"],
+        "properties": {
+          "step": {
+            "type": "string",
+            "description": "Step identifier (e.g., 'step_1', 'step_2')"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["completed", "partial", "failed"]
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "outputs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Files written during this step"
+          },
+          "summary": {
+            "type": "string",
+            "description": "1-2 sentence summary of step outcome"
+          }
+        }
+      }
+    },
+    "current_step": {
+      "type": "string",
+      "description": "Current step identifier for resumption"
+    },
+    "findings": {
+      "type": "object",
+      "description": "High-level summaries only (detailed findings purged after writing)",
+      "properties": {
+        "project_classification": {
+          "type": "object",
+          "properties": {
+            "repository_type": { "type": "string" },
+            "parts_count": { "type": "integer" },
+            "primary_language": { "type": "string" },
+            "architecture_type": { "type": "string" }
+          }
+        },
+        "technology_stack": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "part_id": { "type": "string" },
+              "tech_summary": { "type": "string" }
+            }
+          }
+        },
+        "batches_completed": {
+          "type": "array",
+          "description": "For deep/exhaustive scans: subfolders processed",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": { "type": "string" },
+              "files_scanned": { "type": "integer" },
+              "summary": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "outputs_generated": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of all output files generated"
+    },
+    "resume_instructions": {
+      "type": "string",
+      "description": "Instructions for resuming from current_step"
+    },
+    "validation_status": {
+      "type": "object",
+      "properties": {
+        "last_validated": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "validation_errors": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "deep_dive_targets": {
+      "type": "array",
+      "description": "Track deep-dive areas analyzed (for deep_dive mode)",
+      "items": {
+        "type": "object",
+        "properties": {
+          "target_name": { "type": "string" },
+          "target_path": { "type": "string" },
+          "files_analyzed": { "type": "integer" },
+          "output_file": { "type": "string" },
+          "timestamp": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}
diff --git a/.claude/skills/bmad-document-project/templates/source-tree-template.md b/.claude/skills/bmad-document-project/templates/source-tree-template.md
new file mode 100644
index 0000000..2030621
--- /dev/null
+++ b/.claude/skills/bmad-document-project/templates/source-tree-template.md
@@ -0,0 +1,135 @@
+# {{project_name}} - Source Tree Analysis
+
+**Date:** {{date}}
+
+## Overview
+
+{{source_tree_overview}}
+
+{{#if is_multi_part}}
+
+## Multi-Part Structure
+
+This project is organized into {{parts_count}} distinct parts:
+
+{{#each project_parts}}
+
+- **{{part_name}}** (`{{root_path}}`): {{purpose}}
+  {{/each}}
+  {{/if}}
+
+## Complete Directory Structure
+
+```
+{{complete_source_tree}}
+```
+
+## Critical Directories
+
+{{#each critical_folders}}
+
+### `{{folder_path}}`
+
+{{description}}
+
+**Purpose:** {{purpose}}
+**Contains:** {{contents_summary}}
+{{#if entry_points}}**Entry Points:** {{entry_points}}{{/if}}
+{{#if integration_note}}**Integration:** {{integration_note}}{{/if}}
+
+{{/each}}
+
+{{#if is_multi_part}}
+
+## Part-Specific Trees
+
+{{#each project_parts}}
+
+### {{part_name}} Structure
+
+```
+{{source_tree}}
+```
+
+**Key Directories:**
+{{#each critical_directories}}
+
+- **`{{path}}`**: {{description}}
+  {{/each}}
+
+{{/each}}
+
+## Integration Points
+
+{{#each integration_points}}
+
+### {{from_part}} → {{to_part}}
+
+- **Location:** `{{integration_path}}`
+- **Type:** {{integration_type}}
+- **Details:** {{details}}
+  {{/each}}
+
+{{/if}}
+
+## Entry Points
+
+{{#if is_single_part}}
+
+- **Main Entry:** `{{main_entry_point}}`
+  {{#if additional_entry_points}}
+- **Additional:**
+  {{#each additional_entry_points}}
+  - `{{path}}`: {{description}}
+    {{/each}}
+    {{/if}}
+    {{else}}
+    {{#each project_parts}}
+
+### {{part_name}}
+
+- **Entry Point:** `{{entry_point}}`
+- **Bootstrap:** {{bootstrap_description}}
+  {{/each}}
+  {{/if}}
+
+## File Organization Patterns
+
+{{file_organization_patterns}}
+
+## Key File Types
+
+{{#each file_type_patterns}}
+
+### {{file_type}}
+
+- **Pattern:** `{{pattern}}`
+- **Purpose:** {{purpose}}
+- **Examples:** {{examples}}
+  {{/each}}
+
+## Asset Locations
+
+{{#if has_assets}}
+{{#each asset_locations}}
+
+- **{{asset_type}}**: `{{location}}` ({{file_count}} files, {{total_size}})
+  {{/each}}
+  {{else}}
+  No significant assets detected.
+  {{/if}}
+
+## Configuration Files
+
+{{#each config_files}}
+
+- **`{{path}}`**: {{description}}
+  {{/each}}
+
+## Notes for Development
+
+{{development_notes}}
+
+---
+
+_Generated using BMAD Method `document-project` workflow_
diff --git a/.claude/skills/bmad-document-project/workflow.md b/.claude/skills/bmad-document-project/workflow.md
new file mode 100644
index 0000000..a21e54b
--- /dev/null
+++ b/.claude/skills/bmad-document-project/workflow.md
@@ -0,0 +1,25 @@
+# Document Project Workflow
+
+**Goal:** Document brownfield projects for AI context.
+
+**Your Role:** Project documentation specialist.
+- Communicate all responses in {communication_language}
+
+---
+
+## INITIALIZATION
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Greet user** as `{user_name}`, speaking in `{communication_language}`.
+
+---
+
+## EXECUTION
+
+Read fully and follow: `./instructions.md`
diff --git a/.claude/skills/bmad-document-project/workflows/deep-dive-instructions.md b/.claude/skills/bmad-document-project/workflows/deep-dive-instructions.md
new file mode 100644
index 0000000..6a6d00e
--- /dev/null
+++ b/.claude/skills/bmad-document-project/workflows/deep-dive-instructions.md
@@ -0,0 +1,299 @@
+# Deep-Dive Documentation Instructions
+
+<workflow>
+
+<critical>This workflow performs exhaustive deep-dive documentation of specific areas</critical>
+<critical>Handles: deep_dive mode only</critical>
+<critical>YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`</critical>
+<critical>YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`</critical>
+
+<step n="13" goal="Deep-dive documentation of specific area" if="workflow_mode == deep_dive">
+<critical>Deep-dive mode requires literal full-file review. Sampling, guessing, or relying solely on tooling output is FORBIDDEN.</critical>
+<action>Load existing project structure from index.md and project-parts.json (if exists)</action>
+<action>Load source tree analysis to understand available areas</action>
+
+<step n="13a" goal="Identify area for deep-dive">
+  <action>Analyze existing documentation to suggest deep-dive options</action>
+
+<ask>What area would you like to deep-dive into?
+
+**Suggested Areas Based on Project Structure:**
+
+{{#if has_api_routes}}
+
+## API Routes ({{api_route_count}} endpoints found)
+
+{{#each api_route_groups}}
+{{group_index}}. {{group_name}} - {{endpoint_count}} endpoints in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_feature_modules}}
+
+## Feature Modules ({{feature_count}} features)
+
+{{#each feature_modules}}
+{{module_index}}. {{module_name}} - {{file_count}} files in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_ui_components}}
+
+### UI Component Areas
+
+{{#each component_groups}}
+{{group_index}}. {{group_name}} - {{component_count}} components in `{{path}}`
+{{/each}}
+{{/if}}
+
+{{#if has_services}}
+
+### Services/Business Logic
+
+{{#each service_groups}}
+{{service_index}}. {{service_name}} - `{{path}}`
+{{/each}}
+{{/if}}
+
+**Or specify custom:**
+
+- Folder path (e.g., "client/src/features/dashboard")
+- File path (e.g., "server/src/api/users.ts")
+- Feature name (e.g., "authentication system")
+
+Enter your choice (number or custom path):
+</ask>
+
+<action>Parse user input to determine: - target_type: "folder" | "file" | "feature" | "api_group" | "component_group" - target_path: Absolute path to scan - target_name: Human-readable name for documentation - target_scope: List of all files to analyze
+</action>
+
+<action>Store as {{deep_dive_target}}</action>
+
+<action>Display confirmation:
+Target: {{target_name}}
+Type: {{target_type}}
+Path: {{target_path}}
+Estimated files to analyze: {{estimated_file_count}}
+
+This will read EVERY file in this area. Proceed? [y/n]
+</action>
+
+<action if="user confirms 'n'">Return to Step 13a (select different area)</action>
+</step>
+
+<step n="13b" goal="Comprehensive exhaustive scan of target area">
+  <action>Set scan_mode = "exhaustive"</action>
+  <action>Initialize file_inventory = []</action>
+  <critical>You must read every line of every file in scope and capture a plain-language explanation (what the file does, side effects, why it matters) that future developer agents can act on. No shortcuts.</critical>
+
+  <check if="target_type == folder">
+    <action>Get complete recursive file list from {{target_path}}</action>
+    <action>Filter out: node_modules/, .git/, dist/, build/, coverage/, *.min.js, *.map</action>
+    <action>For EVERY remaining file in folder:
+      - Read complete file contents (all lines)
+      - Extract all exports (functions, classes, types, interfaces, constants)
+      - Extract all imports (dependencies)
+      - Identify purpose from comments and code structure
+      - Write 1-2 sentences (minimum) in natural language describing behaviour, side effects, assumptions, and anything a developer must know before modifying the file
+      - Extract function signatures with parameter types and return types
+      - Note any TODOs, FIXMEs, or comments
+      - Identify patterns (hooks, components, services, controllers, etc.)
+      - Capture per-file contributor guidance: `contributor_note`, `risks`, `verification_steps`, `suggested_tests`
+      - Store in file_inventory
+    </action>
+  </check>
+
+  <check if="target_type == file">
+    <action>Read complete file at {{target_path}}</action>
+    <action>Extract all information as above</action>
+    <action>Read all files it imports (follow import chain 1 level deep)</action>
+    <action>Find all files that import this file (dependents via grep)</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == api_group">
+    <action>Identify all route/controller files in API group</action>
+    <action>Read all route handlers completely</action>
+    <action>Read associated middleware, controllers, services</action>
+    <action>Read data models and schemas used</action>
+    <action>Extract complete request/response schemas</action>
+    <action>Document authentication and authorization requirements</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == feature">
+    <action>Search codebase for all files related to feature name</action>
+    <action>Include: UI components, API endpoints, models, services, tests</action>
+    <action>Read each file completely</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+  <check if="target_type == component_group">
+    <action>Get all component files in group</action>
+    <action>Read each component completely</action>
+    <action>Extract: Props interfaces, hooks used, child components, state management</action>
+    <action>Store all in file_inventory</action>
+  </check>
+
+<action>For each file in file\*inventory, document: - **File Path:** Full path - **Purpose:** What this file does (1-2 sentences) - **Lines of Code:** Total LOC - **Exports:** Complete list with signatures
+
+- Functions: `functionName(param: Type): ReturnType` - Description
+  - Classes: `ClassName` - Description with key methods
+  - Types/Interfaces: `TypeName` - Description
+  - Constants: `CONSTANT_NAME: Type` - Description - **Imports/Dependencies:** What it uses and why - **Used By:** Files that import this (dependents) - **Key Implementation Details:** Important logic, algorithms, patterns - **State Management:** If applicable (Redux, Context, local state) - **Side Effects:** API calls, database queries, file I/O, external services - **Error Handling:** Try/catch blocks, error boundaries, validation - **Testing:** Associated test files and coverage - **Comments/TODOs:** Any inline documentation or planned work
+    </action>
+
+<template-output>comprehensive_file_inventory</template-output>
+</step>
+
+<step n="13c" goal="Analyze relationships and data flow">
+  <action>Build dependency graph for scanned area:
+    - Create graph with files as nodes
+    - Add edges for import relationships
+    - Identify circular dependencies if any
+    - Find entry points (files not imported by others in scope)
+    - Find leaf nodes (files that don't import others in scope)
+  </action>
+
+<action>Trace data flow through the system: - Follow function calls and data transformations - Track API calls and their responses - Document state updates and propagation - Map database queries and mutations
+</action>
+
+<action>Identify integration points: - External APIs consumed - Internal APIs/services called - Shared state accessed - Events published/subscribed - Database tables accessed
+</action>
+
+<template-output>dependency_graph</template-output>
+<template-output>data_flow_analysis</template-output>
+<template-output>integration_points</template-output>
+</step>
+
+<step n="13d" goal="Find related code and similar patterns">
+  <action>Search codebase OUTSIDE scanned area for:
+    - Similar file/folder naming patterns
+    - Similar function signatures
+    - Similar component structures
+    - Similar API patterns
+    - Reusable utilities that could be used
+  </action>
+
+<action>Identify code reuse opportunities: - Shared utilities available - Design patterns used elsewhere - Component libraries available - Helper functions that could apply
+</action>
+
+<action>Find reference implementations: - Similar features in other parts of codebase - Established patterns to follow - Testing approaches used elsewhere
+</action>
+
+<template-output>related_code_references</template-output>
+<template-output>reuse_opportunities</template-output>
+</step>
+
+<step n="13e" goal="Generate comprehensive deep-dive documentation">
+  <action>Create documentation filename: deep-dive-{{sanitized_target_name}}.md</action>
+  <action>Aggregate contributor insights across files:
+    - Combine unique risk/gotcha notes into {{risks_notes}}
+    - Combine verification steps developers should run before changes into {{verification_steps}}
+    - Combine recommended test commands into {{suggested_tests}}
+  </action>
+
+<action>Load complete deep-dive template from: ../templates/deep-dive-template.md</action>
+<action>Fill template with all collected data from steps 13b-13d</action>
+<action>Write filled template to: {project_knowledge}/deep-dive-{{sanitized_target_name}}.md</action>
+<action>Validate deep-dive document completeness</action>
+
+<template-output>deep_dive_documentation</template-output>
+
+<action>Update state file: - Add to deep_dive_targets array: {"target_name": "{{target_name}}", "target_path": "{{target_path}}", "files_analyzed": {{file_count}}, "output_file": "deep-dive-{{sanitized_target_name}}.md", "timestamp": "{{now}}"} - Add output to outputs_generated - Update last_updated timestamp
+</action>
+</step>
+
+<step n="13f" goal="Update master index with deep-dive link">
+  <action>Read existing index.md</action>
+
+<action>Check if "Deep-Dive Documentation" section exists</action>
+
+  <check if="section does not exist">
+    <action>Add new section after "Generated Documentation":
+
+## Deep-Dive Documentation
+
+Detailed exhaustive analysis of specific areas:
+
+    </action>
+
+  </check>
+
+<action>Add link to new deep-dive doc:
+
+- [{{target_name}} Deep-Dive](./deep-dive-{{sanitized_target_name}}.md) - Comprehensive analysis of {{target_description}} ({{file_count}} files, {{total_loc}} LOC) - Generated {{date}}
+  </action>
+
+  <action>Update index metadata:
+  Last Updated: {{date}}
+  Deep-Dives: {{deep_dive_count}}
+  </action>
+
+  <action>Save updated index.md</action>
+
+  <template-output>updated_index</template-output>
+  </step>
+
+<step n="13g" goal="Offer to continue or complete">
+  <action>Display summary:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Deep-Dive Documentation Complete! ✓
+
+**Generated:** {project_knowledge}/deep-dive-{{target_name}}.md
+**Files Analyzed:** {{file_count}}
+**Lines of Code Scanned:** {{total_loc}}
+**Time Taken:** ~{{duration}}
+
+**Documentation Includes:**
+
+- Complete file inventory with all exports
+- Dependency graph and data flow
+- Integration points and API contracts
+- Testing analysis and coverage
+- Related code and reuse opportunities
+- Implementation guidance
+
+**Index Updated:** {project_knowledge}/index.md now includes link to this deep-dive
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+</action>
+
+<ask>Would you like to:
+
+1. **Deep-dive another area** - Analyze another feature/module/folder
+2. **Finish** - Complete workflow
+
+Your choice [1/2]:
+</ask>
+
+  <action if="user selects 1">
+    <action>Clear current deep_dive_target</action>
+    <action>Go to Step 13a (select new area)</action>
+  </action>
+
+  <action if="user selects 2">
+    <action>Display final message:
+
+All deep-dive documentation complete!
+
+**Master Index:** {project_knowledge}/index.md
+**Deep-Dives Generated:** {{deep_dive_count}}
+
+These comprehensive docs are now ready for:
+
+- Architecture review
+- Implementation planning
+- Code understanding
+- Brownfield PRD creation
+
+Thank you for using the document-project workflow!
+</action>
+<action>Exit workflow</action>
+</action>
+</step>
+</step>
+
+</workflow>
diff --git a/.claude/skills/bmad-document-project/workflows/deep-dive-workflow.md b/.claude/skills/bmad-document-project/workflows/deep-dive-workflow.md
new file mode 100644
index 0000000..c55f036
--- /dev/null
+++ b/.claude/skills/bmad-document-project/workflows/deep-dive-workflow.md
@@ -0,0 +1,34 @@
+# Deep-Dive Documentation Sub-Workflow
+
+**Goal:** Exhaustive deep-dive documentation of specific project areas.
+
+**Your Role:** Deep-dive documentation specialist.
+- Deep-dive mode requires literal full-file review. Sampling, guessing, or relying solely on tooling output is FORBIDDEN.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_knowledge`
+- `user_name`
+- `communication_language`, `document_output_language`
+- `date` as system-generated current datetime
+
+✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
+✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`.
+
+### Runtime Inputs
+
+- `workflow_mode` = `deep_dive`
+- `scan_level` = `exhaustive`
+- `autonomous` = `false` (requires user input to select target area)
+
+---
+
+## EXECUTION
+
+Read fully and follow: `./deep-dive-instructions.md`
diff --git a/.claude/skills/bmad-document-project/workflows/full-scan-instructions.md b/.claude/skills/bmad-document-project/workflows/full-scan-instructions.md
new file mode 100644
index 0000000..dd90c4e
--- /dev/null
+++ b/.claude/skills/bmad-document-project/workflows/full-scan-instructions.md
@@ -0,0 +1,1107 @@
+# Full Project Scan Instructions
+
+<workflow>
+
+<critical>This workflow performs complete project documentation (Steps 1-12)</critical>
+<critical>Handles: initial_scan and full_rescan modes</critical>
+<critical>YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`</critical>
+<critical>YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`</critical>
+
+<step n="0.5" goal="Load documentation requirements data for fresh starts (not needed for resume)" if="resume_mode == false">
+<critical>DATA LOADING STRATEGY - Understanding the Documentation Requirements System:</critical>
+
+<action>Display explanation to user:
+
+**How Project Type Detection Works:**
+
+This workflow uses a single comprehensive CSV file to intelligently document your project:
+
+**documentation-requirements.csv** (../documentation-requirements.csv)
+
+- Contains 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
+- 24-column schema combining project type detection AND documentation requirements
+- **Detection columns**: project_type_id, key_file_patterns (used to identify project type from codebase)
+- **Requirement columns**: requires_api_scan, requires_data_models, requires_ui_components, etc.
+- **Pattern columns**: critical_directories, test_file_patterns, config_patterns, etc.
+- Acts as a "scan guide" - tells the workflow WHERE to look and WHAT to document
+- Example: For project_type_id="web", key_file_patterns includes "package.json;tsconfig.json;\*.config.js" and requires_api_scan=true
+
+**When Documentation Requirements are Loaded:**
+
+- **Fresh Start (initial_scan)**: Load all 12 rows → detect type using key_file_patterns → use that row's requirements
+- **Resume**: Load ONLY the doc requirements row(s) for cached project_type_id(s)
+- **Full Rescan**: Same as fresh start (may re-detect project type)
+- **Deep Dive**: Load ONLY doc requirements for the part being deep-dived
+  </action>
+
+<action>Now loading documentation requirements data for fresh start...</action>
+
+<action>Load documentation-requirements.csv from: ../documentation-requirements.csv</action>
+<action>Store all 12 rows indexed by project_type_id for project detection and requirements lookup</action>
+<action>Display: "Loaded documentation requirements for 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)"</action>
+
+<action>Display: "✓ Documentation requirements loaded successfully. Ready to begin project analysis."</action>
+</step>
+
+<step n="0.6" goal="Check for existing documentation and determine workflow mode">
+<action>Check if {project_knowledge}/index.md exists</action>
+
+<check if="index.md exists">
+  <action>Read existing index.md to extract metadata (date, project structure, parts count)</action>
+  <action>Store as {{existing_doc_date}}, {{existing_structure}}</action>
+
+<ask>I found existing documentation generated on {{existing_doc_date}}.
+
+What would you like to do?
+
+1. **Re-scan entire project** - Update all documentation with latest changes
+2. **Deep-dive into specific area** - Generate detailed documentation for a particular feature/module/folder
+3. **Cancel** - Keep existing documentation as-is
+
+Your choice [1/2/3]:
+</ask>
+
+  <check if="user selects 1">
+    <action>Set workflow_mode = "full_rescan"</action>
+    <action>Continue to scan level selection below</action>
+  </check>
+
+  <check if="user selects 2">
+    <action>Set workflow_mode = "deep_dive"</action>
+    <action>Set scan_level = "exhaustive"</action>
+    <action>Initialize state file with mode=deep_dive, scan_level=exhaustive</action>
+    <action>Jump to Step 13</action>
+  </check>
+
+  <check if="user selects 3">
+    <action>Display message: "Keeping existing documentation. Exiting workflow."</action>
+    <action>Exit workflow</action>
+  </check>
+</check>
+
+<check if="index.md does not exist">
+  <action>Set workflow_mode = "initial_scan"</action>
+  <action>Continue to scan level selection below</action>
+</check>
+
+<action if="workflow_mode != deep_dive">Select Scan Level</action>
+
+<check if="workflow_mode == initial_scan OR workflow_mode == full_rescan">
+  <ask>Choose your scan depth level:
+
+**1. Quick Scan** (2-5 minutes) [DEFAULT]
+
+- Pattern-based analysis without reading source files
+- Scans: Config files, package manifests, directory structure
+- Best for: Quick project overview, initial understanding
+- File reading: Minimal (configs, README, package.json, etc.)
+
+**2. Deep Scan** (10-30 minutes)
+
+- Reads files in critical directories based on project type
+- Scans: All critical paths from documentation requirements
+- Best for: Comprehensive documentation for brownfield PRD
+- File reading: Selective (key files in critical directories)
+
+**3. Exhaustive Scan** (30-120 minutes)
+
+- Reads ALL source files in project
+- Scans: Every source file (excludes node_modules, dist, build)
+- Best for: Complete analysis, migration planning, detailed audit
+- File reading: Complete (all source files)
+
+Your choice [1/2/3] (default: 1):
+</ask>
+
+  <action if="user selects 1 OR user presses enter">
+    <action>Set scan_level = "quick"</action>
+    <action>Display: "Using Quick Scan (pattern-based, no source file reading)"</action>
+  </action>
+
+  <action if="user selects 2">
+    <action>Set scan_level = "deep"</action>
+    <action>Display: "Using Deep Scan (reading critical files per project type)"</action>
+  </action>
+
+  <action if="user selects 3">
+    <action>Set scan_level = "exhaustive"</action>
+    <action>Display: "Using Exhaustive Scan (reading all source files)"</action>
+  </action>
+
+<action>Initialize state file: {project_knowledge}/project-scan-report.json</action>
+<critical>Every time you touch the state file, record: step id, human-readable summary (what you actually did), precise timestamp, and any outputs written. Vague phrases are unacceptable.</critical>
+<action>Write initial state:
+{
+"workflow_version": "1.2.0",
+"timestamps": {"started": "{{current_timestamp}}", "last_updated": "{{current_timestamp}}"},
+"mode": "{{workflow_mode}}",
+"scan_level": "{{scan_level}}",
+"project_root": "{{project_root_path}}",
+"project_knowledge": "{{project_knowledge}}",
+"completed_steps": [],
+"current_step": "step_1",
+"findings": {},
+"outputs_generated": ["project-scan-report.json"],
+"resume_instructions": "Starting from step 1"
+}
+</action>
+<action>Continue with standard workflow from Step 1</action>
+</check>
+</step>
+
+<step n="1" goal="Detect project structure and classify project type" if="workflow_mode != deep_dive">
+<action>Ask user: "What is the root directory of the project to document?" (default: current working directory)</action>
+<action>Store as {{project_root_path}}</action>
+
+<action>Scan {{project_root_path}} for key indicators:
+
+- Directory structure (presence of client/, server/, api/, src/, app/, etc.)
+- Key files (package.json, go.mod, requirements.txt, etc.)
+- Technology markers matching detection_keywords from project-types.csv
+  </action>
+
+<action>Detect if project is:
+
+- **Monolith**: Single cohesive codebase
+- **Monorepo**: Multiple parts in one repository
+- **Multi-part**: Separate client/server or similar architecture
+  </action>
+
+<check if="multiple distinct parts detected (e.g., client/ and server/ folders)">
+  <action>List detected parts with their paths</action>
+  <ask>I detected multiple parts in this project:
+  {{detected_parts_list}}
+
+Is this correct? Should I document each part separately? [y/n]
+</ask>
+
+<action if="user confirms">Set repository_type = "monorepo" or "multi-part"</action>
+<action if="user confirms">For each detected part: - Identify root path - Run project type detection using key_file_patterns from documentation-requirements.csv - Store as part in project_parts array
+</action>
+
+<action if="user denies or corrects">Ask user to specify correct parts and their paths</action>
+</check>
+
+<check if="single cohesive project detected">
+  <action>Set repository_type = "monolith"</action>
+  <action>Create single part in project_parts array with root_path = {{project_root_path}}</action>
+  <action>Run project type detection using key_file_patterns from documentation-requirements.csv</action>
+</check>
+
+<action>For each part, match detected technologies and file patterns against key_file_patterns column in documentation-requirements.csv</action>
+<action>Assign project_type_id to each part</action>
+<action>Load corresponding documentation_requirements row for each part</action>
+
+<ask>I've classified this project:
+{{project_classification_summary}}
+
+Does this look correct? [y/n/edit]
+</ask>
+
+<template-output>project_structure</template-output>
+<template-output>project_parts_metadata</template-output>
+
+<action>IMMEDIATELY update state file with step completion:
+
+- Add to completed_steps: {"step": "step_1", "status": "completed", "timestamp": "{{now}}", "summary": "Classified as {{repository_type}} with {{parts_count}} parts"}
+- Update current_step = "step_2"
+- Update findings.project_classification with high-level summary only
+- **CACHE project_type_id(s)**: Add project_types array: [{"part_id": "{{part_id}}", "project_type_id": "{{project_type_id}}", "display_name": "{{display_name}}"}]
+- This cached data prevents reloading all CSV files on resume - we can load just the needed documentation_requirements row(s)
+- Update last_updated timestamp
+- Write state file
+  </action>
+
+<action>PURGE detailed scan results from memory, keep only summary: "{{repository_type}}, {{parts_count}} parts, {{primary_tech}}"</action>
+</step>
+
+<step n="2" goal="Discover existing documentation and gather user context" if="workflow_mode != deep_dive">
+<action>For each part, scan for existing documentation using patterns:
+- README.md, README.rst, README.txt
+- CONTRIBUTING.md, CONTRIBUTING.rst
+- ARCHITECTURE.md, ARCHITECTURE.txt, docs/architecture/
+- DEPLOYMENT.md, DEPLOY.md, docs/deployment/
+- API.md, docs/api/
+- Any files in docs/, documentation/, .github/ folders
+</action>
+
+<action>Create inventory of existing_docs with:
+
+- File path
+- File type (readme, architecture, api, etc.)
+- Which part it belongs to (if multi-part)
+  </action>
+
+<ask>I found these existing documentation files:
+{{existing_docs_list}}
+
+Are there any other important documents or key areas I should focus on while analyzing this project? [Provide paths or guidance, or type 'none']
+</ask>
+
+<action>Store user guidance as {{user_context}}</action>
+
+<template-output>existing_documentation_inventory</template-output>
+<template-output>user_provided_context</template-output>
+
+<action>Update state file:
+
+- Add to completed_steps: {"step": "step_2", "status": "completed", "timestamp": "{{now}}", "summary": "Found {{existing_docs_count}} existing docs"}
+- Update current_step = "step_3"
+- Update last_updated timestamp
+  </action>
+
+<action>PURGE detailed doc contents from memory, keep only: "{{existing_docs_count}} docs found"</action>
+</step>
+
+<step n="3" goal="Analyze technology stack for each part" if="workflow_mode != deep_dive">
+<action>For each part in project_parts:
+  - Load key_file_patterns from documentation_requirements
+  - Scan part root for these patterns
+  - Parse technology manifest files (package.json, go.mod, requirements.txt, etc.)
+  - Extract: framework, language, version, database, dependencies
+  - Build technology_table with columns: Category, Technology, Version, Justification
+</action>
+
+<action>Determine architecture pattern based on detected tech stack:
+
+- Use project_type_id as primary indicator (e.g., "web" → layered/component-based, "backend" → service/API-centric)
+- Consider framework patterns (e.g., React → component hierarchy, Express → middleware pipeline)
+- Note architectural style in technology table
+- Store as {{architecture_pattern}} for each part
+  </action>
+
+<template-output>technology_stack</template-output>
+<template-output>architecture_patterns</template-output>
+
+<action>Update state file:
+
+- Add to completed_steps: {"step": "step_3", "status": "completed", "timestamp": "{{now}}", "summary": "Tech stack: {{primary_framework}}"}
+- Update current_step = "step_4"
+- Update findings.technology_stack with summary per part
+- Update last_updated timestamp
+  </action>
+
+<action>PURGE detailed tech analysis from memory, keep only: "{{framework}} on {{language}}"</action>
+</step>
+
+<step n="4" goal="Perform conditional analysis based on project type requirements" if="workflow_mode != deep_dive">
+
+<critical>BATCHING STRATEGY FOR DEEP/EXHAUSTIVE SCANS</critical>
+
+<check if="scan_level == deep OR scan_level == exhaustive">
+  <action>This step requires file reading. Apply batching strategy:</action>
+
+<action>Identify subfolders to process based on: - scan_level == "deep": Use critical_directories from documentation_requirements - scan_level == "exhaustive": Get ALL subfolders recursively (excluding node_modules, .git, dist, build, coverage)
+</action>
+
+<action>For each subfolder to scan: 1. Read all files in subfolder (consider file size - use judgment for files >5000 LOC) 2. Extract required information based on conditional flags below 3. IMMEDIATELY write findings to appropriate output file 4. Validate written document (section-level validation) 5. Update state file with batch completion 6. PURGE detailed findings from context, keep only 1-2 sentence summary 7. Move to next subfolder
+</action>
+
+<action>Track batches in state file:
+findings.batches_completed: [
+{"path": "{{subfolder_path}}", "files_scanned": {{count}}, "summary": "{{brief_summary}}"}
+]
+</action>
+</check>
+
+<check if="scan_level == quick">
+  <action>Use pattern matching only - do NOT read source files</action>
+  <action>Use glob/grep to identify file locations and patterns</action>
+  <action>Extract information from filenames, directory structure, and config files only</action>
+</check>
+
+<action>For each part, check documentation_requirements boolean flags and execute corresponding scans:</action>
+
+<check if="requires_api_scan == true">
+  <action>Scan for API routes and endpoints using integration_scan_patterns</action>
+  <action>Look for: controllers/, routes/, api/, handlers/, endpoints/</action>
+
+  <check if="scan_level == quick">
+    <action>Use glob to find route files, extract patterns from filenames and folder structure</action>
+  </check>
+
+  <check if="scan_level == deep OR scan_level == exhaustive">
+    <action>Read files in batches (one subfolder at a time)</action>
+    <action>Extract: HTTP methods, paths, request/response types from actual code</action>
+  </check>
+
+<action>Build API contracts catalog</action>
+<action>IMMEDIATELY write to: {project_knowledge}/api-contracts-{part_id}.md</action>
+<action>Validate document has all required sections</action>
+<action>Update state file with output generated</action>
+<action>PURGE detailed API data, keep only: "{{api_count}} endpoints documented"</action>
+<template-output>api_contracts\*{part_id}</template-output>
+</check>
+
+<check if="requires_data_models == true">
+  <action>Scan for data models using schema_migration_patterns</action>
+  <action>Look for: models/, schemas/, entities/, migrations/, prisma/, ORM configs</action>
+
+  <check if="scan_level == quick">
+    <action>Identify schema files via glob, parse migration file names for table discovery</action>
+  </check>
+
+  <check if="scan_level == deep OR scan_level == exhaustive">
+    <action>Read model files in batches (one subfolder at a time)</action>
+    <action>Extract: table names, fields, relationships, constraints from actual code</action>
+  </check>
+
+<action>Build database schema documentation</action>
+<action>IMMEDIATELY write to: {project_knowledge}/data-models-{part_id}.md</action>
+<action>Validate document completeness</action>
+<action>Update state file with output generated</action>
+<action>PURGE detailed schema data, keep only: "{{table_count}} tables documented"</action>
+<template-output>data_models\*{part_id}</template-output>
+</check>
+
+<check if="requires_state_management == true">
+  <action>Analyze state management patterns</action>
+  <action>Look for: Redux, Context API, MobX, Vuex, Pinia, Provider patterns</action>
+  <action>Identify: stores, reducers, actions, state structure</action>
+  <template-output>state_management_patterns_{part_id}</template-output>
+</check>
+
+<check if="requires_ui_components == true">
+  <action>Inventory UI component library</action>
+  <action>Scan: components/, ui/, widgets/, views/ folders</action>
+  <action>Categorize: Layout, Form, Display, Navigation, etc.</action>
+  <action>Identify: Design system, component patterns, reusable elements</action>
+  <template-output>ui_component_inventory_{part_id}</template-output>
+</check>
+
+<check if="requires_hardware_docs == true">
+  <action>Look for hardware schematics using hardware_interface_patterns</action>
+  <ask>This appears to be an embedded/hardware project. Do you have:
+  - Pinout diagrams
+  - Hardware schematics
+  - PCB layouts
+  - Hardware documentation
+
+If yes, please provide paths or links. [Provide paths or type 'none']
+</ask>
+<action>Store hardware docs references</action>
+<template-output>hardware*documentation*{part_id}</template-output>
+</check>
+
+<check if="requires_asset_inventory == true">
+  <action>Scan and catalog assets using asset_patterns</action>
+  <action>Categorize by: Images, Audio, 3D Models, Sprites, Textures, etc.</action>
+  <action>Calculate: Total size, file counts, formats used</action>
+  <template-output>asset_inventory_{part_id}</template-output>
+</check>
+
+<action>Scan for additional patterns based on doc requirements:
+
+- config_patterns → Configuration management
+- auth_security_patterns → Authentication/authorization approach
+- entry_point_patterns → Application entry points and bootstrap
+- shared_code_patterns → Shared libraries and utilities
+- async_event_patterns → Event-driven architecture
+- ci_cd_patterns → CI/CD pipeline details
+- localization_patterns → i18n/l10n support
+  </action>
+
+<action>Apply scan_level strategy to each pattern scan (quick=glob only, deep/exhaustive=read files)</action>
+
+<template-output>comprehensive*analysis*{part_id}</template-output>
+
+<action>Update state file:
+
+- Add to completed_steps: {"step": "step_4", "status": "completed", "timestamp": "{{now}}", "summary": "Conditional analysis complete, {{files_generated}} files written"}
+- Update current_step = "step_5"
+- Update last_updated timestamp
+- List all outputs_generated
+  </action>
+
+<action>PURGE all detailed scan results from context. Keep only summaries:
+
+- "APIs: {{api_count}} endpoints"
+- "Data: {{table_count}} tables"
+- "Components: {{component_count}} components"
+  </action>
+  </step>
+
+<step n="5" goal="Generate source tree analysis with annotations" if="workflow_mode != deep_dive">
+<action>For each part, generate complete directory tree using critical_directories from doc requirements</action>
+
+<action>Annotate the tree with:
+
+- Purpose of each critical directory
+- Entry points marked
+- Key file locations highlighted
+- Integration points noted (for multi-part projects)
+  </action>
+
+<action if="multi-part project">Show how parts are organized and where they interface</action>
+
+<action>Create formatted source tree with descriptions:
+
+```
+project-root/
+├── client/          # React frontend (Part: client)
+│   ├── src/
+│   │   ├── components/  # Reusable UI components
+│   │   ├── pages/       # Route-based pages
+│   │   └── api/         # API client layer → Calls server/
+├── server/          # Express API backend (Part: api)
+│   ├── src/
+│   │   ├── routes/      # REST API endpoints
+│   │   ├── models/      # Database models
+│   │   └── services/    # Business logic
+```
+
+</action>
+
+<template-output>source_tree_analysis</template-output>
+<template-output>critical_folders_summary</template-output>
+
+<action>IMMEDIATELY write source-tree-analysis.md to disk</action>
+<action>Validate document structure</action>
+<action>Update state file:
+
+- Add to completed_steps: {"step": "step_5", "status": "completed", "timestamp": "{{now}}", "summary": "Source tree documented"}
+- Update current_step = "step_6"
+- Add output: "source-tree-analysis.md"
+  </action>
+  <action>PURGE detailed tree from context, keep only: "Source tree with {{folder_count}} critical folders"</action>
+  </step>
+
+<step n="6" goal="Extract development and operational information" if="workflow_mode != deep_dive">
+<action>Scan for development setup using key_file_patterns and existing docs:
+- Prerequisites (Node version, Python version, etc.)
+- Installation steps (npm install, etc.)
+- Environment setup (.env files, config)
+- Build commands (npm run build, make, etc.)
+- Run commands (npm start, go run, etc.)
+- Test commands using test_file_patterns
+</action>
+
+<action>Look for deployment configuration using ci_cd_patterns:
+
+- Dockerfile, docker-compose.yml
+- Kubernetes configs (k8s/, helm/)
+- CI/CD pipelines (.github/workflows/, .gitlab-ci.yml)
+- Deployment scripts
+- Infrastructure as Code (terraform/, pulumi/)
+  </action>
+
+<action if="CONTRIBUTING.md or similar found">
+  <action>Extract contribution guidelines:
+    - Code style rules
+    - PR process
+    - Commit conventions
+    - Testing requirements
+  </action>
+</action>
+
+<template-output>development_instructions</template-output>
+<template-output>deployment_configuration</template-output>
+<template-output>contribution_guidelines</template-output>
+
+<action>Update state file:
+
+- Add to completed_steps: {"step": "step_6", "status": "completed", "timestamp": "{{now}}", "summary": "Dev/deployment guides written"}
+- Update current_step = "step_7"
+- Add generated outputs to list
+  </action>
+  <action>PURGE detailed instructions, keep only: "Dev setup and deployment documented"</action>
+  </step>
+
+<step n="7" goal="Detect multi-part integration architecture" if="workflow_mode != deep_dive and project has multiple parts">
+<action>Analyze how parts communicate:
+- Scan integration_scan_patterns across parts
+- Identify: REST calls, GraphQL queries, gRPC, message queues, shared databases
+- Document: API contracts between parts, data flow, authentication flow
+</action>
+
+<action>Create integration_points array with:
+
+- from: source part
+- to: target part
+- type: REST API, GraphQL, gRPC, Event Bus, etc.
+- details: Endpoints, protocols, data formats
+  </action>
+
+<action>IMMEDIATELY write integration-architecture.md to disk</action>
+<action>Validate document completeness</action>
+
+<template-output>integration_architecture</template-output>
+
+<action>Update state file:
+
+- Add to completed_steps: {"step": "step_7", "status": "completed", "timestamp": "{{now}}", "summary": "Integration architecture documented"}
+- Update current_step = "step_8"
+  </action>
+  <action>PURGE integration details, keep only: "{{integration_count}} integration points"</action>
+  </step>
+
+<step n="8" goal="Generate architecture documentation for each part" if="workflow_mode != deep_dive">
+<action>For each part in project_parts:
+  - Use matched architecture template from Step 3 as base structure
+  - Fill in all sections with discovered information:
+    * Executive Summary
+    * Technology Stack (from Step 3)
+    * Architecture Pattern (from registry match)
+    * Data Architecture (from Step 4 data models scan)
+    * API Design (from Step 4 API scan if applicable)
+    * Component Overview (from Step 4 component scan if applicable)
+    * Source Tree (from Step 5)
+    * Development Workflow (from Step 6)
+    * Deployment Architecture (from Step 6)
+    * Testing Strategy (from test patterns)
+</action>
+
+<action if="single part project">
+  - Generate: architecture.md (no part suffix)
+</action>
+
+<action if="multi-part project">
+  - Generate: architecture-{part_id}.md for each part
+</action>
+
+<action>For each architecture file generated:
+
+- IMMEDIATELY write architecture file to disk
+- Validate against architecture template schema
+- Update state file with output
+- PURGE detailed architecture from context, keep only: "Architecture for {{part_id}} written"
+  </action>
+
+<template-output>architecture_document</template-output>
+
+<action>Update state file:
+
+- Add to completed_steps: {"step": "step_8", "status": "completed", "timestamp": "{{now}}", "summary": "Architecture docs written for {{parts_count}} parts"}
+- Update current_step = "step_9"
+  </action>
+  </step>
+
+<step n="9" goal="Generate supporting documentation files" if="workflow_mode != deep_dive">
+<action>Generate project-overview.md with:
+- Project name and purpose (from README or user input)
+- Executive summary
+- Tech stack summary table
+- Architecture type classification
+- Repository structure (monolith/monorepo/multi-part)
+- Links to detailed docs
+</action>
+
+<action>Generate source-tree-analysis.md with:
+
+- Full annotated directory tree from Step 5
+- Critical folders explained
+- Entry points documented
+- Multi-part structure (if applicable)
+  </action>
+
+<action>IMMEDIATELY write project-overview.md to disk</action>
+<action>Validate document sections</action>
+
+<action>Generate source-tree-analysis.md (if not already written in Step 5)</action>
+<action>IMMEDIATELY write to disk and validate</action>
+
+<action>Generate component-inventory.md (or per-part versions) with:
+
+- All discovered components from Step 4
+- Categorized by type
+- Reusable vs specific components
+- Design system elements (if found)
+  </action>
+  <action>IMMEDIATELY write each component inventory to disk and validate</action>
+
+<action>Generate development-guide.md (or per-part versions) with:
+
+- Prerequisites and dependencies
+- Environment setup instructions
+- Local development commands
+- Build process
+- Testing approach and commands
+- Common development tasks
+  </action>
+  <action>IMMEDIATELY write each development guide to disk and validate</action>
+
+<action if="deployment configuration found">
+  <action>Generate deployment-guide.md with:
+    - Infrastructure requirements
+    - Deployment process
+    - Environment configuration
+    - CI/CD pipeline details
+  </action>
+  <action>IMMEDIATELY write to disk and validate</action>
+</action>
+
+<action if="contribution guidelines found">
+  <action>Generate contribution-guide.md with:
+    - Code style and conventions
+    - PR process
+    - Testing requirements
+    - Documentation standards
+  </action>
+  <action>IMMEDIATELY write to disk and validate</action>
+</action>
+
+<action if="API contracts documented">
+  <action>Generate api-contracts.md (or per-part) with:
+    - All API endpoints
+    - Request/response schemas
+    - Authentication requirements
+    - Example requests
+  </action>
+  <action>IMMEDIATELY write to disk and validate</action>
+</action>
+
+<action if="Data models documented">
+  <action>Generate data-models.md (or per-part) with:
+    - Database schema
+    - Table relationships
+    - Data models and entities
+    - Migration strategy
+  </action>
+  <action>IMMEDIATELY write to disk and validate</action>
+</action>
+
+<action if="multi-part project">
+  <action>Generate integration-architecture.md with:
+    - How parts communicate
+    - Integration points diagram/description
+    - Data flow between parts
+    - Shared dependencies
+  </action>
+  <action>IMMEDIATELY write to disk and validate</action>
+
+<action>Generate project-parts.json metadata file:
+`json
+    {
+      "repository_type": "monorepo",
+      "parts": [ ... ],
+      "integration_points": [ ... ]
+    }
+    `
+</action>
+<action>IMMEDIATELY write to disk</action>
+</action>
+
+<template-output>supporting_documentation</template-output>
+
+<action>Update state file:
+
+- Add to completed_steps: {"step": "step_9", "status": "completed", "timestamp": "{{now}}", "summary": "All supporting docs written"}
+- Update current_step = "step_10"
+- List all newly generated outputs
+  </action>
+
+<action>PURGE all document contents from context, keep only list of files generated</action>
+</step>
+
+<step n="10" goal="Generate master index as primary AI retrieval source" if="workflow_mode != deep_dive">
+
+<critical>INCOMPLETE DOCUMENTATION MARKER CONVENTION:
+When a document SHOULD be generated but wasn't (due to quick scan, missing data, conditional requirements not met):
+
+- Use EXACTLY this marker: _(To be generated)_
+- Place it at the end of the markdown link line
+- Example: - [API Contracts - Server](./api-contracts-server.md) _(To be generated)_
+- This allows Step 11 to detect and offer to complete these items
+- ALWAYS use this exact format for consistency and automated detection
+  </critical>
+
+<action>Create index.md with intelligent navigation based on project structure</action>
+
+<action if="single part project">
+  <action>Generate simple index with:
+    - Project name and type
+    - Quick reference (tech stack, architecture type)
+    - Links to all generated docs
+    - Links to discovered existing docs
+    - Getting started section
+  </action>
+</action>
+
+<action if="multi-part project">
+  <action>Generate comprehensive index with:
+    - Project overview and structure summary
+    - Part-based navigation section
+    - Quick reference by part
+    - Cross-part integration links
+    - Links to all generated and existing docs
+    - Getting started per part
+  </action>
+</action>
+
+<action>Include in index.md:
+
+## Project Documentation Index
+
+### Project Overview
+
+- **Type:** {{repository_type}} {{#if multi-part}}with {{parts.length}} parts{{/if}}
+- **Primary Language:** {{primary_language}}
+- **Architecture:** {{architecture_type}}
+
+### Quick Reference
+
+{{#if single_part}}
+
+- **Tech Stack:** {{tech_stack_summary}}
+- **Entry Point:** {{entry_point}}
+- **Architecture Pattern:** {{architecture_pattern}}
+  {{else}}
+  {{#each parts}}
+
+#### {{part_name}} ({{part_id}})
+
+- **Type:** {{project_type}}
+- **Tech Stack:** {{tech_stack}}
+- **Root:** {{root_path}}
+  {{/each}}
+  {{/if}}
+
+### Generated Documentation
+
+- [Project Overview](./project-overview.md)
+- [Architecture](./architecture{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless architecture_file_exists}} (To be generated) {{/unless}}
+- [Source Tree Analysis](./source-tree-analysis.md)
+- [Component Inventory](./component-inventory{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless component_inventory_exists}} (To be generated) {{/unless}}
+- [Development Guide](./development-guide{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless dev_guide_exists}} (To be generated) {{/unless}}
+  {{#if deployment_found}}- [Deployment Guide](./deployment-guide.md){{#unless deployment_guide_exists}} (To be generated) {{/unless}}{{/if}}
+  {{#if contribution_found}}- [Contribution Guide](./contribution-guide.md){{/if}}
+  {{#if api_documented}}- [API Contracts](./api-contracts{{#if multi-part}}-{part_id}{{/if}}.md){{#unless api_contracts_exists}} (To be generated) {{/unless}}{{/if}}
+  {{#if data_models_documented}}- [Data Models](./data-models{{#if multi-part}}-{part_id}{{/if}}.md){{#unless data_models_exists}} (To be generated) {{/unless}}{{/if}}
+  {{#if multi-part}}- [Integration Architecture](./integration-architecture.md){{#unless integration_arch_exists}} (To be generated) {{/unless}}{{/if}}
+
+### Existing Documentation
+
+{{#each existing_docs}}
+
+- [{{title}}]({{relative_path}}) - {{description}}
+  {{/each}}
+
+### Getting Started
+
+{{getting_started_instructions}}
+</action>
+
+<action>Before writing index.md, check which expected files actually exist:
+
+- For each document that should have been generated, check if file exists on disk
+- Set existence flags: architecture_file_exists, component_inventory_exists, dev_guide_exists, etc.
+- These flags determine whether to add the _(To be generated)_ marker
+- Track which files are missing in {{missing_docs_list}} for reporting
+  </action>
+
+<action>IMMEDIATELY write index.md to disk with appropriate _(To be generated)_ markers for missing files</action>
+<action>Validate index has all required sections and links are valid</action>
+
+<template-output>index</template-output>
+
+<action>Update state file:
+
+- Add to completed_steps: {"step": "step_10", "status": "completed", "timestamp": "{{now}}", "summary": "Master index generated"}
+- Update current_step = "step_11"
+- Add output: "index.md"
+  </action>
+
+<action>PURGE index content from context</action>
+</step>
+
+<step n="11" goal="Validate and review generated documentation" if="workflow_mode != deep_dive">
+<action>Show summary of all generated files:
+Generated in {{project_knowledge}}/:
+{{file_list_with_sizes}}
+</action>
+
+<action>Run validation checklist from ../checklist.md</action>
+
+<critical>INCOMPLETE DOCUMENTATION DETECTION:
+
+1. PRIMARY SCAN: Look for exact marker: _(To be generated)_
+2. FALLBACK SCAN: Look for fuzzy patterns (in case agent was lazy):
+   - _(TBD)_
+   - _(TODO)_
+   - _(Coming soon)_
+   - _(Not yet generated)_
+   - _(Pending)_
+3. Extract document metadata from each match for user selection
+   </critical>
+
+<action>Read {project_knowledge}/index.md</action>
+
+<action>Scan for incomplete documentation markers:
+Step 1: Search for exact pattern "_(To be generated)_" (case-sensitive)
+Step 2: For each match found, extract the entire line
+Step 3: Parse line to extract:
+
+- Document title (text within [brackets] or **bold**)
+- File path (from markdown link or inferable from title)
+- Document type (infer from filename: architecture, api-contracts, data-models, component-inventory, development-guide, deployment-guide, integration-architecture)
+- Part ID if applicable (extract from filename like "architecture-server.md" → part_id: "server")
+  Step 4: Add to {{incomplete_docs_strict}} array
+  </action>
+
+<action>Fallback fuzzy scan for alternate markers:
+Search for patterns: _(TBD)_, _(TODO)_, _(Coming soon)_, _(Not yet generated)_, _(Pending)_
+For each fuzzy match:
+
+- Extract same metadata as strict scan
+- Add to {{incomplete_docs_fuzzy}} array with fuzzy_match flag
+  </action>
+
+<action>Combine results:
+Set {{incomplete_docs_list}} = {{incomplete_docs_strict}} + {{incomplete_docs_fuzzy}}
+For each item store structure:
+{
+"title": "Architecture – Server",
+"file\*path": "./architecture-server.md",
+"doc_type": "architecture",
+"part_id": "server",
+"line_text": "- [Architecture – Server](./architecture-server.md) (To be generated)",
+"fuzzy_match": false
+}
+</action>
+
+<ask>Documentation generation complete!
+
+Summary:
+
+- Project Type: {{project_type_summary}}
+- Parts Documented: {{parts_count}}
+- Files Generated: {{files_count}}
+- Total Lines: {{total_lines}}
+
+{{#if incomplete_docs_list.length > 0}}
+⚠️ **Incomplete Documentation Detected:**
+
+I found {{incomplete_docs_list.length}} item(s) marked as incomplete:
+
+{{#each incomplete_docs_list}}
+{{@index + 1}}. **{{title}}** ({{doc_type}}{{#if part_id}} for {{part_id}}{{/if}}){{#if fuzzy_match}} ⚠️ [non-standard marker]{{/if}}
+{{/each}}
+
+{{/if}}
+
+Would you like to:
+
+{{#if incomplete_docs_list.length > 0}}
+
+1. **Generate incomplete documentation** - Complete any of the {{incomplete_docs_list.length}} items above
+2. Review any specific section [type section name]
+3. Add more detail to any area [type area name]
+4. Generate additional custom documentation [describe what]
+5. Finalize and complete [type 'done']
+   {{else}}
+6. Review any specific section [type section name]
+7. Add more detail to any area [type area name]
+8. Generate additional documentation [describe what]
+9. Finalize and complete [type 'done']
+   {{/if}}
+
+Your choice:
+</ask>
+
+<check if="user selects option 1 (generate incomplete)">
+  <ask>Which incomplete items would you like to generate?
+
+{{#each incomplete_docs_list}}
+{{@index + 1}}. {{title}} ({{doc_type}}{{#if part_id}} - {{part_id}}{{/if}})
+{{/each}}
+{{incomplete_docs_list.length + 1}}. All of them
+
+Enter number(s) separated by commas (e.g., "1,3,5"), or type 'all':
+</ask>
+
+<action>Parse user selection:
+
+- If "all", set {{selected_items}} = all items in {{incomplete_docs_list}}
+- If comma-separated numbers, extract selected items by index
+- Store result in {{selected_items}} array
+  </action>
+
+  <action>Display: "Generating {{selected_items.length}} document(s)..."</action>
+
+  <action>For each item in {{selected_items}}:
+
+1. **Identify the part and requirements:**
+   - Extract part_id from item (if exists)
+   - Look up part data in project_parts array from state file
+   - Load documentation_requirements for that part's project_type_id
+
+2. **Route to appropriate generation substep based on doc_type:**
+
+   **If doc_type == "architecture":**
+   - Display: "Generating architecture documentation for {{part_id}}..."
+   - Load architecture_match for this part from state file (Step 3 cache)
+   - Re-run Step 8 architecture generation logic ONLY for this specific part
+   - Use matched template and fill with cached data from state file
+   - Write architecture-{{part_id}}.md to disk
+   - Validate completeness
+
+   **If doc_type == "api-contracts":**
+   - Display: "Generating API contracts for {{part_id}}..."
+   - Load part data and documentation_requirements
+   - Re-run Step 4 API scan substep targeting ONLY this part
+   - Use scan_level from state file (quick/deep/exhaustive)
+   - Generate api-contracts-{{part_id}}.md
+   - Validate document structure
+
+   **If doc_type == "data-models":**
+   - Display: "Generating data models documentation for {{part_id}}..."
+   - Re-run Step 4 data models scan substep targeting ONLY this part
+   - Use schema_migration_patterns from documentation_requirements
+   - Generate data-models-{{part_id}}.md
+   - Validate completeness
+
+   **If doc_type == "component-inventory":**
+   - Display: "Generating component inventory for {{part_id}}..."
+   - Re-run Step 9 component inventory generation for this specific part
+   - Scan components/, ui/, widgets/ folders
+   - Generate component-inventory-{{part_id}}.md
+   - Validate structure
+
+   **If doc_type == "development-guide":**
+   - Display: "Generating development guide for {{part_id}}..."
+   - Re-run Step 9 development guide generation for this specific part
+   - Use key_file_patterns and test_file_patterns from documentation_requirements
+   - Generate development-guide-{{part_id}}.md
+   - Validate completeness
+
+   **If doc_type == "deployment-guide":**
+   - Display: "Generating deployment guide..."
+   - Re-run Step 6 deployment configuration scan
+   - Re-run Step 9 deployment guide generation
+   - Generate deployment-guide.md
+   - Validate structure
+
+   **If doc_type == "integration-architecture":**
+   - Display: "Generating integration architecture..."
+   - Re-run Step 7 integration analysis for all parts
+   - Generate integration-architecture.md
+   - Validate completeness
+
+3. **Post-generation actions:**
+   - Confirm file was written successfully
+   - Update state file with newly generated output
+   - Add to {{newly_generated_docs}} tracking list
+   - Display: "✓ Generated: {{file_path}}"
+
+4. **Handle errors:**
+   - If generation fails, log error and continue with next item
+   - Track failed items in {{failed_generations}} list
+     </action>
+
+<action>After all selected items are processed:
+
+**Update index.md to remove markers:**
+
+1. Read current index.md content
+2. For each item in {{newly_generated_docs}}:
+   - Find the line containing the file link and marker
+   - Remove the _(To be generated)_ or fuzzy marker text
+   - Leave the markdown link intact
+3. Write updated index.md back to disk
+4. Update state file to record index.md modification
+   </action>
+
+<action>Display generation summary:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ **Documentation Generation Complete!**
+
+**Successfully Generated:**
+{{#each newly_generated_docs}}
+
+- {{title}} → {{file_path}}
+  {{/each}}
+
+{{#if failed_generations.length > 0}}
+**Failed to Generate:**
+{{#each failed_generations}}
+
+- {{title}} ({{error_message}})
+  {{/each}}
+  {{/if}}
+
+**Updated:** index.md (removed incomplete markers)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+</action>
+
+<action>Update state file with all generation activities</action>
+
+<action>Return to Step 11 menu (loop back to check for any remaining incomplete items)</action>
+</check>
+
+<action if="user requests other changes (options 2-3)">Make requested modifications and regenerate affected files</action>
+<action if="user selects finalize (option 4 or 5)">Proceed to Step 12 completion</action>
+
+<check if="not finalizing">
+  <action>Update state file:
+- Add to completed_steps: {"step": "step_11_iteration", "status": "completed", "timestamp": "{{now}}", "summary": "Review iteration complete"}
+- Keep current_step = "step_11" (for loop back)
+- Update last_updated timestamp
+  </action>
+  <action>Loop back to beginning of Step 11 (re-scan for remaining incomplete docs)</action>
+</check>
+
+<check if="finalizing">
+  <action>Update state file:
+- Add to completed_steps: {"step": "step_11", "status": "completed", "timestamp": "{{now}}", "summary": "Validation and review complete"}
+- Update current_step = "step_12"
+  </action>
+  <action>Proceed to Step 12</action>
+</check>
+</step>
+
+<step n="12" goal="Finalize and provide next steps" if="workflow_mode != deep_dive">
+<action>Create final summary report</action>
+<action>Compile verification recap variables:
+  - Set {{verification_summary}} to the concrete tests, validations, or scripts you executed (or "none run").
+  - Set {{open_risks}} to any remaining risks or TODO follow-ups (or "none").
+  - Set {{next_checks}} to recommended actions before merging/deploying (or "none").
+</action>
+
+<action>Display completion message:
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Project Documentation Complete! ✓
+
+**Location:** {{project_knowledge}}/
+
+**Master Index:** {{project_knowledge}}/index.md
+👆 This is your primary entry point for AI-assisted development
+
+**Generated Documentation:**
+{{generated_files_list}}
+
+**Next Steps:**
+
+1. Review the index.md to familiarize yourself with the documentation structure
+2. When creating a brownfield PRD, point the PRD workflow to: {{project_knowledge}}/index.md
+3. For UI-only features: Reference {{project_knowledge}}/architecture-{{ui_part_id}}.md
+4. For API-only features: Reference {{project_knowledge}}/architecture-{{api_part_id}}.md
+5. For full-stack features: Reference both part architectures + integration-architecture.md
+
+**Verification Recap:**
+
+- Tests/extractions executed: {{verification_summary}}
+- Outstanding risks or follow-ups: {{open_risks}}
+- Recommended next checks before PR: {{next_checks}}
+
+**Brownfield PRD Command:**
+When ready to plan new features, run the PRD workflow and provide this index as input.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+</action>
+
+<action>FINALIZE state file:
+
+- Add to completed_steps: {"step": "step_12", "status": "completed", "timestamp": "{{now}}", "summary": "Workflow complete"}
+- Update timestamps.completed = "{{now}}"
+- Update current_step = "completed"
+- Write final state file
+  </action>
+
+<action>Display: "State file saved: {{project_knowledge}}/project-scan-report.json"</action>
+
+</workflow>
diff --git a/.claude/skills/bmad-document-project/workflows/full-scan-workflow.md b/.claude/skills/bmad-document-project/workflows/full-scan-workflow.md
new file mode 100644
index 0000000..5aaf4a5
--- /dev/null
+++ b/.claude/skills/bmad-document-project/workflows/full-scan-workflow.md
@@ -0,0 +1,34 @@
+# Full Project Scan Sub-Workflow
+
+**Goal:** Complete project documentation (initial scan or full rescan).
+
+**Your Role:** Full project scan documentation specialist.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_knowledge`
+- `user_name`
+- `communication_language`, `document_output_language`
+- `date` as system-generated current datetime
+
+✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
+✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`.
+
+### Runtime Inputs
+
+- `workflow_mode` = `""` (set by parent: `initial_scan` or `full_rescan`)
+- `scan_level` = `""` (set by parent: `quick`, `deep`, or `exhaustive`)
+- `resume_mode` = `false`
+- `autonomous` = `false` (requires user input at key decision points)
+
+---
+
+## EXECUTION
+
+Read fully and follow: `./full-scan-instructions.md`
diff --git a/.claude/skills/bmad-domain-research/SKILL.md b/.claude/skills/bmad-domain-research/SKILL.md
new file mode 100644
index 0000000..b3dbc12
--- /dev/null
+++ b/.claude/skills/bmad-domain-research/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-domain-research
+description: 'Conduct domain and industry research. Use when the user says wants to do domain research for a topic or industry'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-domain-research/domain-steps/step-01-init.md b/.claude/skills/bmad-domain-research/domain-steps/step-01-init.md
new file mode 100644
index 0000000..27d056b
--- /dev/null
+++ b/.claude/skills/bmad-domain-research/domain-steps/step-01-init.md
@@ -0,0 +1,137 @@
+# Domain Research Step 1: Domain Research Scope Confirmation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user confirmation
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ FOCUS EXCLUSIVELY on confirming domain research scope and approach
+- 📋 YOU ARE A DOMAIN RESEARCH PLANNER, not content generator
+- 💬 ACKNOWLEDGE and CONFIRM understanding of domain research goals
+- 🔍 This is SCOPE CONFIRMATION ONLY - no web research yet
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present [C] continue option after scope confirmation
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Research type = "domain" is already set
+- **Research topic = "{{research_topic}}"** - discovered from initial discussion
+- **Research goals = "{{research_goals}}"** - captured from initial discussion
+- Focus on industry/domain analysis with web research
+- Web search is required to verify and supplement your knowledge with current facts
+
+## YOUR TASK:
+
+Confirm domain research scope and approach for **{{research_topic}}** with the user's goals in mind.
+
+## DOMAIN SCOPE CONFIRMATION:
+
+### 1. Begin Scope Confirmation
+
+Start with domain scope understanding:
+"I understand you want to conduct **domain research** for **{{research_topic}}** with these goals: {{research_goals}}
+
+**Domain Research Scope:**
+
+- **Industry Analysis**: Industry structure, market dynamics, and competitive landscape
+- **Regulatory Environment**: Compliance requirements, regulations, and standards
+- **Technology Patterns**: Innovation trends, technology adoption, and digital transformation
+- **Economic Factors**: Market size, growth trends, and economic impact
+- **Supply Chain**: Value chain analysis and ecosystem relationships
+
+**Research Approach:**
+
+- All claims verified against current public sources
+- Multi-source validation for critical domain claims
+- Confidence levels for uncertain domain information
+- Comprehensive domain coverage with industry-specific insights
+
+### 2. Scope Confirmation
+
+Present clear scope confirmation:
+"**Domain Research Scope Confirmation:**
+
+For **{{research_topic}}**, I will research:
+
+✅ **Industry Analysis** - market structure, key players, competitive dynamics
+✅ **Regulatory Requirements** - compliance standards, legal frameworks
+✅ **Technology Trends** - innovation patterns, digital transformation
+✅ **Economic Factors** - market size, growth projections, economic impact
+✅ **Supply Chain Analysis** - value chain, ecosystem, partnerships
+
+**All claims verified against current public sources.**
+
+**Does this domain research scope and approach align with your goals?**
+[C] Continue - Begin domain research with this scope
+
+### 3. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- Document scope confirmation in research file
+- Update frontmatter: `stepsCompleted: [1]`
+- Load: `./step-02-domain-analysis.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append scope confirmation:
+
+```markdown
+## Domain Research Scope Confirmation
+
+**Research Topic:** {{research_topic}}
+**Research Goals:** {{research_goals}}
+
+**Domain Research Scope:**
+
+- Industry Analysis - market structure, competitive landscape
+- Regulatory Environment - compliance requirements, legal frameworks
+- Technology Trends - innovation patterns, digital transformation
+- Economic Factors - market size, growth projections
+- Supply Chain Analysis - value chain, ecosystem relationships
+
+**Research Methodology:**
+
+- All claims verified against current public sources
+- Multi-source validation for critical domain claims
+- Confidence level framework for uncertain information
+- Comprehensive domain coverage with industry-specific insights
+
+**Scope Confirmed:** {{date}}
+```
+
+## SUCCESS METRICS:
+
+✅ Domain research scope clearly confirmed with user
+✅ All domain analysis areas identified and explained
+✅ Research methodology emphasized
+✅ [C] continue option presented and handled correctly
+✅ Scope confirmation documented when user proceeds
+✅ Proper routing to next domain research step
+
+## FAILURE MODES:
+
+❌ Not clearly confirming domain research scope with user
+❌ Missing critical domain analysis areas
+❌ Not explaining that web search is required for current facts
+❌ Not presenting [C] continue option
+❌ Proceeding without user scope confirmation
+❌ Not routing to next domain research step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-02-domain-analysis.md` to begin industry analysis.
+
+Remember: This is SCOPE CONFIRMATION ONLY - no actual domain research yet, just confirming the research approach and scope!
diff --git a/.claude/skills/bmad-domain-research/domain-steps/step-02-domain-analysis.md b/.claude/skills/bmad-domain-research/domain-steps/step-02-domain-analysis.md
new file mode 100644
index 0000000..bb4cbb6
--- /dev/null
+++ b/.claude/skills/bmad-domain-research/domain-steps/step-02-domain-analysis.md
@@ -0,0 +1,229 @@
+# Domain Research Step 2: Industry Analysis
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE AN INDUSTRY ANALYST, not content generator
+- 💬 FOCUS on market size, growth, and industry dynamics
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after industry analysis content generation
+- 📝 WRITE INDUSTRY ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from step-01 are available
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+- Focus on market size, growth, and industry dynamics
+- Web search capabilities with source verification are enabled
+
+## YOUR TASK:
+
+Conduct industry analysis focusing on market size, growth, and industry dynamics. Search the web to verify and supplement current facts.
+
+## INDUSTRY ANALYSIS SEQUENCE:
+
+### 1. Begin Industry Analysis
+
+**UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different industry areas simultaneously and thoroughly.
+
+Start with industry research approach:
+"Now I'll conduct **industry analysis** for **{{research_topic}}** to understand market dynamics.
+
+**Industry Analysis Focus:**
+
+- Market size and valuation metrics
+- Growth rates and market dynamics
+- Market segmentation and structure
+- Industry trends and evolution patterns
+- Economic impact and value creation
+
+**Let me search for current industry insights.**"
+
+### 2. Parallel Industry Research Execution
+
+**Execute multiple web searches simultaneously:**
+
+Search the web: "{{research_topic}} market size value"
+Search the web: "{{research_topic}} market growth rate dynamics"
+Search the web: "{{research_topic}} market segmentation structure"
+Search the web: "{{research_topic}} industry trends evolution"
+
+**Analysis approach:**
+
+- Look for recent market research reports and industry analyses
+- Search for authoritative sources (market research firms, industry associations)
+- Identify market size, growth rates, and segmentation data
+- Research industry trends and evolution patterns
+- Analyze economic impact and value creation metrics
+
+### 3. Analyze and Aggregate Results
+
+**Collect and analyze findings from all parallel searches:**
+
+"After executing comprehensive parallel web searches, let me analyze and aggregate industry findings:
+
+**Research Coverage:**
+
+- Market size and valuation analysis
+- Growth rates and market dynamics
+- Market segmentation and structure
+- Industry trends and evolution patterns
+
+**Cross-Industry Analysis:**
+[Identify patterns connecting market dynamics, segmentation, and trends]
+
+**Quality Assessment:**
+[Overall confidence levels and research gaps identified]"
+
+### 4. Generate Industry Analysis Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare industry analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Industry Analysis
+
+### Market Size and Valuation
+
+[Market size analysis with source citations]
+_Total Market Size: [Current market valuation]_
+_Growth Rate: [CAGR and market growth projections]_
+_Market Segments: [Size and value of key market segments]_
+_Economic Impact: [Economic contribution and value creation]_
+_Source: [URL]_
+
+### Market Dynamics and Growth
+
+[Market dynamics analysis with source citations]
+_Growth Drivers: [Key factors driving market growth]_
+_Growth Barriers: [Factors limiting market expansion]_
+_Cyclical Patterns: [Industry seasonality and cycles]_
+_Market Maturity: [Life cycle stage and development phase]_
+_Source: [URL]_
+
+### Market Structure and Segmentation
+
+[Market structure analysis with source citations]
+_Primary Segments: [Key market segments and their characteristics]_
+_Sub-segment Analysis: [Detailed breakdown of market sub-segments]_
+_Geographic Distribution: [Regional market variations and concentrations]_
+_Vertical Integration: [Supply chain and value chain structure]_
+_Source: [URL]_
+
+### Industry Trends and Evolution
+
+[Industry trends analysis with source citations]
+_Emerging Trends: [Current industry developments and transformations]_
+_Historical Evolution: [Industry development over recent years]_
+_Technology Integration: [How technology is changing the industry]_
+_Future Outlook: [Projected industry developments and changes]_
+_Source: [URL]_
+
+### Competitive Dynamics
+
+[Competitive dynamics analysis with source citations]
+_Market Concentration: [Level of market consolidation and competition]_
+_Competitive Intensity: [Degree of competition and rivalry]_
+_Barriers to Entry: [Obstacles for new market entrants]_
+_Innovation Pressure: [Rate of innovation and change]_
+_Source: [URL]_
+```
+
+### 5. Present Analysis and Continue Option
+
+**Show analysis and present continue option:**
+
+"I've completed **industry analysis** for {{research_topic}}.
+
+**Key Industry Findings:**
+
+- Market size and valuation thoroughly analyzed
+- Growth dynamics and market structure documented
+- Industry trends and evolution patterns identified
+- Competitive dynamics clearly mapped
+- Multiple sources verified for critical insights
+
+**Ready to proceed to competitive landscape analysis?**
+[C] Continue - Save this to document and proceed to competitive landscape
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2]`
+- Load: `./step-03-competitive-landscape.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 4. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Market size and valuation thoroughly analyzed
+✅ Growth dynamics and market structure documented
+✅ Industry trends and evolution patterns identified
+✅ Competitive dynamics clearly mapped
+✅ Multiple sources verified for critical insights
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (competitive landscape)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying on training data instead of web search for current facts
+❌ Missing critical market size or growth data
+❌ Incomplete market structure analysis
+❌ Not identifying key industry trends
+❌ Not writing content immediately to document
+❌ Not presenting [C] continue option after content generation
+❌ Not routing to competitive landscape step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## INDUSTRY RESEARCH PROTOCOLS:
+
+- Research market research reports and industry analyses
+- Use authoritative sources (market research firms, industry associations)
+- Analyze market size, growth rates, and segmentation data
+- Study industry trends and evolution patterns
+- Search the web to verify facts
+- Present conflicting information when sources disagree
+- Apply confidence levels appropriately
+
+## INDUSTRY ANALYSIS STANDARDS:
+
+- Always cite URLs for web search results
+- Use authoritative industry research sources
+- Note data currency and potential limitations
+- Present multiple perspectives when sources conflict
+- Apply confidence levels to uncertain data
+- Focus on actionable industry insights
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-03-competitive-landscape.md` to analyze competitive landscape, key players, and ecosystem analysis for {{research_topic}}.
+
+Remember: Always write research content to document immediately and search the web to verify facts!
diff --git a/.claude/skills/bmad-domain-research/domain-steps/step-03-competitive-landscape.md b/.claude/skills/bmad-domain-research/domain-steps/step-03-competitive-landscape.md
new file mode 100644
index 0000000..0dc2de6
--- /dev/null
+++ b/.claude/skills/bmad-domain-research/domain-steps/step-03-competitive-landscape.md
@@ -0,0 +1,238 @@
+# Domain Research Step 3: Competitive Landscape
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A COMPETITIVE ANALYST, not content generator
+- 💬 FOCUS on key players, market share, and competitive dynamics
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after competitive analysis content generation
+- 📝 WRITE COMPETITIVE ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+- Focus on key players, market share, and competitive dynamics
+- Web search capabilities with source verification are enabled
+
+## YOUR TASK:
+
+Conduct competitive landscape analysis focusing on key players, market share, and competitive dynamics. Search the web to verify and supplement current facts.
+
+## COMPETITIVE LANDSCAPE ANALYSIS SEQUENCE:
+
+### 1. Begin Competitive Landscape Analysis
+
+**UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different competitive areas simultaneously and thoroughly.
+
+Start with competitive research approach:
+"Now I'll conduct **competitive landscape analysis** for **{{research_topic}}** to understand the competitive ecosystem.
+
+**Competitive Landscape Focus:**
+
+- Key players and market leaders
+- Market share and competitive positioning
+- Competitive strategies and differentiation
+- Business models and value propositions
+- Entry barriers and competitive dynamics
+
+**Let me search for current competitive insights.**"
+
+### 2. Parallel Competitive Research Execution
+
+**Execute multiple web searches simultaneously:**
+
+Search the web: "{{research_topic}} key players market leaders"
+Search the web: "{{research_topic}} market share competitive landscape"
+Search the web: "{{research_topic}} competitive strategies differentiation"
+Search the web: "{{research_topic}} entry barriers competitive dynamics"
+
+**Analysis approach:**
+
+- Look for recent competitive intelligence reports and market analyses
+- Search for company websites, annual reports, and investor presentations
+- Research market share data and competitive positioning
+- Analyze competitive strategies and differentiation approaches
+- Study entry barriers and competitive dynamics
+
+### 3. Analyze and Aggregate Results
+
+**Collect and analyze findings from all parallel searches:**
+
+"After executing comprehensive parallel web searches, let me analyze and aggregate competitive findings:
+
+**Research Coverage:**
+
+- Key players and market leaders analysis
+- Market share and competitive positioning assessment
+- Competitive strategies and differentiation mapping
+- Entry barriers and competitive dynamics evaluation
+
+**Cross-Competitive Analysis:**
+[Identify patterns connecting players, strategies, and market dynamics]
+
+**Quality Assessment:**
+[Overall confidence levels and research gaps identified]"
+
+### 4. Generate Competitive Landscape Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare competitive landscape analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Competitive Landscape
+
+### Key Players and Market Leaders
+
+[Key players analysis with source citations]
+_Market Leaders: [Dominant players and their market positions]_
+_Major Competitors: [Significant competitors and their specialties]_
+_Emerging Players: [New entrants and innovative companies]_
+_Global vs Regional: [Geographic distribution of key players]_
+_Source: [URL]_
+
+### Market Share and Competitive Positioning
+
+[Market share analysis with source citations]
+_Market Share Distribution: [Current market share breakdown]_
+_Competitive Positioning: [How players position themselves in the market]_
+_Value Proposition Mapping: [Different value propositions across players]_
+_Customer Segments Served: [Different customer bases by competitor]_
+_Source: [URL]_
+
+### Competitive Strategies and Differentiation
+
+[Competitive strategies analysis with source citations]
+_Cost Leadership Strategies: [Players competing on price and efficiency]_
+_Differentiation Strategies: [Players competing on unique value]_
+_Focus/Niche Strategies: [Players targeting specific segments]_
+_Innovation Approaches: [How different players innovate]_
+_Source: [URL]_
+
+### Business Models and Value Propositions
+
+[Business models analysis with source citations]
+_Primary Business Models: [How competitors make money]_
+_Revenue Streams: [Different approaches to monetization]_
+_Value Chain Integration: [Vertical integration vs partnership models]_
+_Customer Relationship Models: [How competitors build customer loyalty]_
+_Source: [URL]_
+
+### Competitive Dynamics and Entry Barriers
+
+[Competitive dynamics analysis with source citations]
+_Barriers to Entry: [Obstacles facing new market entrants]_
+_Competitive Intensity: [Level of rivalry and competitive pressure]_
+_Market Consolidation Trends: [M&A activity and market concentration]_
+_Switching Costs: [Costs for customers to switch between providers]_
+_Source: [URL]_
+
+### Ecosystem and Partnership Analysis
+
+[Ecosystem analysis with source citations]
+_Supplier Relationships: [Key supplier partnerships and dependencies]_
+_Distribution Channels: [How competitors reach customers]_
+_Technology Partnerships: [Strategic technology alliances]_
+_Ecosystem Control: [Who controls key parts of the value chain]_
+_Source: [URL]_
+```
+
+### 5. Present Analysis and Continue Option
+
+**Show analysis and present continue option:**
+
+"I've completed **competitive landscape analysis** for {{research_topic}}.
+
+**Key Competitive Findings:**
+
+- Key players and market leaders thoroughly identified
+- Market share and competitive positioning clearly mapped
+- Competitive strategies and differentiation analyzed
+- Business models and value propositions documented
+- Competitive dynamics and entry barriers evaluated
+
+**Ready to proceed to regulatory focus analysis?**
+[C] Continue - Save this to document and proceed to regulatory focus
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2, 3]`
+- Load: `./step-04-regulatory-focus.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 4. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Key players and market leaders thoroughly identified
+✅ Market share and competitive positioning clearly mapped
+✅ Competitive strategies and differentiation analyzed
+✅ Business models and value propositions documented
+✅ Competitive dynamics and entry barriers evaluated
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (regulatory focus)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying on training data instead of web search for current facts
+❌ Missing critical key players or market leaders
+❌ Incomplete market share or positioning analysis
+❌ Not identifying competitive strategies
+❌ Not writing content immediately to document
+❌ Not presenting [C] continue option after content generation
+❌ Not routing to regulatory focus step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## COMPETITIVE RESEARCH PROTOCOLS:
+
+- Research competitive intelligence reports and market analyses
+- Use company websites, annual reports, and investor presentations
+- Analyze market share data and competitive positioning
+- Study competitive strategies and differentiation approaches
+- Search the web to verify facts
+- Present conflicting information when sources disagree
+- Apply confidence levels appropriately
+
+## COMPETITIVE ANALYSIS STANDARDS:
+
+- Always cite URLs for web search results
+- Use authoritative competitive intelligence sources
+- Note data currency and potential limitations
+- Present multiple perspectives when sources conflict
+- Apply confidence levels to uncertain data
+- Focus on actionable competitive insights
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-04-regulatory-focus.md` to analyze regulatory requirements, compliance frameworks, and legal considerations for {{research_topic}}.
+
+Remember: Always write research content to document immediately and search the web to verify facts!
diff --git a/.claude/skills/bmad-domain-research/domain-steps/step-04-regulatory-focus.md b/.claude/skills/bmad-domain-research/domain-steps/step-04-regulatory-focus.md
new file mode 100644
index 0000000..e98010c
--- /dev/null
+++ b/.claude/skills/bmad-domain-research/domain-steps/step-04-regulatory-focus.md
@@ -0,0 +1,206 @@
+# Domain Research Step 4: Regulatory Focus
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A REGULATORY ANALYST, not content generator
+- 💬 FOCUS on compliance requirements and regulatory landscape
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after regulatory content generation
+- 📝 WRITE REGULATORY ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+- Focus on regulatory and compliance requirements for the domain
+- Web search capabilities with source verification are enabled
+
+## YOUR TASK:
+
+Conduct focused regulatory and compliance analysis with emphasis on requirements that impact {{research_topic}}. Search the web to verify and supplement current facts.
+
+## REGULATORY FOCUS SEQUENCE:
+
+### 1. Begin Regulatory Analysis
+
+Start with regulatory research approach:
+"Now I'll focus on **regulatory and compliance requirements** that impact **{{research_topic}}**.
+
+**Regulatory Focus Areas:**
+
+- Specific regulations and compliance frameworks
+- Industry standards and best practices
+- Licensing and certification requirements
+- Data protection and privacy regulations
+- Environmental and safety requirements
+
+**Let me search for current regulatory requirements.**"
+
+### 2. Web Search for Specific Regulations
+
+Search for current regulatory information:
+Search the web: "{{research_topic}} regulations compliance requirements"
+
+**Regulatory focus:**
+
+- Specific regulations applicable to the domain
+- Compliance frameworks and standards
+- Recent regulatory changes or updates
+- Enforcement agencies and oversight bodies
+
+### 3. Web Search for Industry Standards
+
+Search for current industry standards:
+Search the web: "{{research_topic}} standards best practices"
+
+**Standards focus:**
+
+- Industry-specific technical standards
+- Best practices and guidelines
+- Certification requirements
+- Quality assurance frameworks
+
+### 4. Web Search for Data Privacy Requirements
+
+Search for current privacy regulations:
+Search the web: "data privacy regulations {{research_topic}}"
+
+**Privacy focus:**
+
+- GDPR, CCPA, and other data protection laws
+- Industry-specific privacy requirements
+- Data governance and security standards
+- User consent and data handling requirements
+
+### 5. Generate Regulatory Analysis Content
+
+Prepare regulatory content with source citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Regulatory Requirements
+
+### Applicable Regulations
+
+[Specific regulations analysis with source citations]
+_Source: [URL]_
+
+### Industry Standards and Best Practices
+
+[Industry standards analysis with source citations]
+_Source: [URL]_
+
+### Compliance Frameworks
+
+[Compliance frameworks analysis with source citations]
+_Source: [URL]_
+
+### Data Protection and Privacy
+
+[Privacy requirements analysis with source citations]
+_Source: [URL]_
+
+### Licensing and Certification
+
+[Licensing requirements analysis with source citations]
+_Source: [URL]_
+
+### Implementation Considerations
+
+[Practical implementation considerations with source citations]
+_Source: [URL]_
+
+### Risk Assessment
+
+[Regulatory and compliance risk assessment]
+```
+
+### 6. Present Analysis and Continue Option
+
+Show the generated regulatory analysis and present continue option:
+"I've completed **regulatory requirements analysis** for {{research_topic}}.
+
+**Key Regulatory Findings:**
+
+- Specific regulations and frameworks identified
+- Industry standards and best practices mapped
+- Compliance requirements clearly documented
+- Implementation considerations provided
+- Risk assessment completed
+
+**Ready to proceed to technical trends?**
+[C] Continue - Save this to the document and move to technical trends
+
+### 7. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
+- Load: `./step-05-technical-trends.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 5. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Applicable regulations identified with current citations
+✅ Industry standards and best practices documented
+✅ Compliance frameworks clearly mapped
+✅ Data protection requirements analyzed
+✅ Implementation considerations provided
+✅ [C] continue option presented and handled correctly
+✅ Content properly appended to document when C selected
+
+## FAILURE MODES:
+
+❌ Relying on training data instead of web search for current facts
+❌ Missing critical regulatory requirements for the domain
+❌ Not providing implementation considerations for compliance
+❌ Not completing risk assessment for regulatory compliance
+❌ Not presenting [C] continue option after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## REGULATORY RESEARCH PROTOCOLS:
+
+- Search for specific regulations by name and number
+- Identify regulatory bodies and enforcement agencies
+- Research recent regulatory changes and updates
+- Map industry standards to regulatory requirements
+- Consider regional and jurisdictional differences
+
+## SOURCE VERIFICATION:
+
+- Always cite regulatory agency websites
+- Use official government and industry association sources
+- Note effective dates and implementation timelines
+- Present compliance requirement levels and obligations
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-05-technical-trends.md` to analyze technical trends and innovations in the domain.
+
+Remember: Search the web to verify regulatory facts and provide practical implementation considerations!
diff --git a/.claude/skills/bmad-domain-research/domain-steps/step-05-technical-trends.md b/.claude/skills/bmad-domain-research/domain-steps/step-05-technical-trends.md
new file mode 100644
index 0000000..55e834c
--- /dev/null
+++ b/.claude/skills/bmad-domain-research/domain-steps/step-05-technical-trends.md
@@ -0,0 +1,234 @@
+# Domain Research Step 5: Technical Trends
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A TECHNOLOGY ANALYST, not content generator
+- 💬 FOCUS on emerging technologies and innovation patterns
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after technical trends content generation
+- 📝 WRITE TECHNICAL TRENDS ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+- Focus on emerging technologies and innovation patterns in the domain
+- Web search capabilities with source verification are enabled
+
+## YOUR TASK:
+
+Conduct comprehensive technical trends analysis using current web data with emphasis on innovations and emerging technologies impacting {{research_topic}}.
+
+## TECHNICAL TRENDS SEQUENCE:
+
+### 1. Begin Technical Trends Analysis
+
+Start with technology research approach:
+"Now I'll conduct **technical trends and emerging technologies** analysis for **{{research_topic}}** using current data.
+
+**Technical Trends Focus:**
+
+- Emerging technologies and innovations
+- Digital transformation impacts
+- Automation and efficiency improvements
+- New business models enabled by technology
+- Future technology projections and roadmaps
+
+**Let me search for current technology developments.**"
+
+### 2. Web Search for Emerging Technologies
+
+Search for current technology information:
+Search the web: "{{research_topic}} emerging technologies innovations"
+
+**Technology focus:**
+
+- AI, machine learning, and automation impacts
+- Digital transformation trends
+- New technologies disrupting the industry
+- Innovation patterns and breakthrough developments
+
+### 3. Web Search for Digital Transformation
+
+Search for current transformation trends:
+Search the web: "{{research_topic}} digital transformation trends"
+
+**Transformation focus:**
+
+- Digital adoption trends and rates
+- Business model evolution
+- Customer experience innovations
+- Operational efficiency improvements
+
+### 4. Web Search for Future Outlook
+
+Search for future projections:
+Search the web: "{{research_topic}} future outlook trends"
+
+**Future focus:**
+
+- Technology roadmaps and projections
+- Market evolution predictions
+- Innovation pipelines and R&D trends
+- Long-term industry transformation
+
+### 5. Generate Technical Trends Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare technical analysis with source citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Technical Trends and Innovation
+
+### Emerging Technologies
+
+[Emerging technologies analysis with source citations]
+_Source: [URL]_
+
+### Digital Transformation
+
+[Digital transformation analysis with source citations]
+_Source: [URL]_
+
+### Innovation Patterns
+
+[Innovation patterns analysis with source citations]
+_Source: [URL]_
+
+### Future Outlook
+
+[Future outlook and projections with source citations]
+_Source: [URL]_
+
+### Implementation Opportunities
+
+[Implementation opportunity analysis with source citations]
+_Source: [URL]_
+
+### Challenges and Risks
+
+[Challenges and risks assessment with source citations]
+_Source: [URL]_
+
+## Recommendations
+
+### Technology Adoption Strategy
+
+[Technology adoption recommendations]
+
+### Innovation Roadmap
+
+[Innovation roadmap suggestions]
+
+### Risk Mitigation
+
+[Risk mitigation strategies]
+```
+
+### 6. Present Analysis and Complete Option
+
+Show the generated technical analysis and present complete option:
+"I've completed **technical trends and innovation analysis** for {{research_topic}}.
+
+**Technical Highlights:**
+
+- Emerging technologies and innovations identified
+- Digital transformation trends mapped
+- Future outlook and projections analyzed
+- Implementation opportunities and challenges documented
+- Practical recommendations provided
+
+**Technical Trends Research Completed:**
+
+- Emerging technologies and innovations identified
+- Digital transformation trends mapped
+- Future outlook and projections analyzed
+- Implementation opportunities and challenges documented
+
+**Ready to proceed to research synthesis and recommendations?**
+[C] Continue - Save this to document and proceed to synthesis
+
+### 7. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
+- Load: `./step-06-research-synthesis.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 5. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Emerging technologies identified with current data
+✅ Digital transformation trends clearly documented
+✅ Future outlook and projections analyzed
+✅ Implementation opportunities and challenges mapped
+✅ Strategic recommendations provided
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (research synthesis)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+❌ Missing critical emerging technologies in the domain
+❌ Not providing practical implementation recommendations
+❌ Not completing strategic recommendations
+❌ Not presenting completion option for research workflow
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## TECHNICAL RESEARCH PROTOCOLS:
+
+- Search for cutting-edge technologies and innovations
+- Identify disruption patterns and game-changers
+- Research technology adoption timelines and barriers
+- Consider regional technology variations
+- Analyze competitive technological advantages
+
+## RESEARCH WORKFLOW COMPLETION:
+
+When 'C' is selected:
+
+- All domain research steps completed
+- Comprehensive research document generated
+- All sections appended with source citations
+- Research workflow status updated
+- Final recommendations provided to user
+
+## NEXT STEPS:
+
+Research workflow complete. User may:
+
+- Use the domain research to inform other workflows (PRD, architecture, etc.)
+- Conduct additional research on specific topics if needed
+- Move forward with product development based on research insights
+
+Congratulations on completing comprehensive domain research! 🎉
diff --git a/.claude/skills/bmad-domain-research/domain-steps/step-06-research-synthesis.md b/.claude/skills/bmad-domain-research/domain-steps/step-06-research-synthesis.md
new file mode 100644
index 0000000..9e2261f
--- /dev/null
+++ b/.claude/skills/bmad-domain-research/domain-steps/step-06-research-synthesis.md
@@ -0,0 +1,444 @@
+# Domain Research Step 6: Research Synthesis and Completion
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A DOMAIN RESEARCH STRATEGIST, not content generator
+- 💬 FOCUS on comprehensive synthesis and authoritative conclusions
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📄 PRODUCE COMPREHENSIVE DOCUMENT with narrative intro, TOC, and summary
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] complete option after synthesis content generation
+- 💾 ONLY save when user chooses C (Complete)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` before completing workflow
+- 🚫 FORBIDDEN to complete workflow until C is selected
+- 📚 GENERATE COMPLETE DOCUMENT STRUCTURE with intro, TOC, and summary
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- **Research topic = "{{research_topic}}"** - comprehensive domain analysis
+- **Research goals = "{{research_goals}}"** - achieved through exhaustive research
+- All domain research sections have been completed (analysis, regulatory, technical)
+- Web search capabilities with source verification are enabled
+- This is the final synthesis step producing the complete research document
+
+## YOUR TASK:
+
+Produce a comprehensive, authoritative research document on **{{research_topic}}** with compelling narrative introduction, detailed TOC, and executive summary based on exhaustive domain research.
+
+## COMPREHENSIVE DOCUMENT SYNTHESIS:
+
+### 1. Document Structure Planning
+
+**Complete Research Document Structure:**
+
+```markdown
+# [Compelling Title]: Comprehensive {{research_topic}} Research
+
+## Executive Summary
+
+[Brief compelling overview of key findings and implications]
+
+## Table of Contents
+
+- Research Introduction and Methodology
+- Industry Overview and Market Dynamics
+- Technology Trends and Innovation Landscape
+- Regulatory Framework and Compliance Requirements
+- Competitive Landscape and Key Players
+- Strategic Insights and Recommendations
+- Implementation Considerations and Risk Assessment
+- Future Outlook and Strategic Opportunities
+- Research Methodology and Source Documentation
+- Appendices and Additional Resources
+```
+
+### 2. Generate Compelling Narrative Introduction
+
+**Introduction Requirements:**
+
+- Hook reader with compelling opening about {{research_topic}}
+- Establish research significance and timeliness
+- Outline comprehensive research methodology
+- Preview key findings and strategic implications
+- Set professional, authoritative tone
+
+**Web Search for Introduction Context:**
+Search the web: "{{research_topic}} significance importance"
+
+### 3. Synthesize All Research Sections
+
+**Section-by-Section Integration:**
+
+- Combine industry analysis from step-02
+- Integrate regulatory focus from step-03
+- Incorporate technical trends from step-04
+- Add cross-sectional insights and connections
+- Ensure comprehensive coverage with no gaps
+
+### 4. Generate Complete Document Content
+
+#### Final Document Structure:
+
+```markdown
+# [Compelling Title]: Comprehensive {{research_topic}} Domain Research
+
+## Executive Summary
+
+[2-3 paragraph compelling summary of the most critical findings and strategic implications for {{research_topic}} based on comprehensive current research]
+
+**Key Findings:**
+
+- [Most significant market dynamics]
+- [Critical regulatory considerations]
+- [Important technology trends]
+- [Strategic implications]
+
+**Strategic Recommendations:**
+
+- [Top 3-5 actionable recommendations based on research]
+
+## Table of Contents
+
+1. Research Introduction and Methodology
+2. {{research_topic}} Industry Overview and Market Dynamics
+3. Technology Landscape and Innovation Trends
+4. Regulatory Framework and Compliance Requirements
+5. Competitive Landscape and Ecosystem Analysis
+6. Strategic Insights and Domain Opportunities
+7. Implementation Considerations and Risk Assessment
+8. Future Outlook and Strategic Planning
+9. Research Methodology and Source Verification
+10. Appendices and Additional Resources
+
+## 1. Research Introduction and Methodology
+
+### Research Significance
+
+[Compelling narrative about why {{research_topic}} research is critical right now]
+_Why this research matters now: [Strategic importance with current context]_
+_Source: [URL]_
+
+### Research Methodology
+
+[Comprehensive description of research approach including:]
+
+- **Research Scope**: [Comprehensive coverage areas]
+- **Data Sources**: [Authoritative sources and verification approach]
+- **Analysis Framework**: [Structured analysis methodology]
+- **Time Period**: [current focus and historical context]
+- **Geographic Coverage**: [Regional/global scope]
+
+### Research Goals and Objectives
+
+**Original Goals:** {{research_goals}}
+
+**Achieved Objectives:**
+
+- [Goal 1 achievement with supporting evidence]
+- [Goal 2 achievement with supporting evidence]
+- [Additional insights discovered during research]
+
+## 2. {{research_topic}} Industry Overview and Market Dynamics
+
+### Market Size and Growth Projections
+
+[Comprehensive market analysis synthesized from step-02 with current data]
+_Market Size: [Current market valuation]_
+_Growth Rate: [CAGR and projections]_
+_Market Drivers: [Key growth factors]_
+_Source: [URL]_
+
+### Industry Structure and Value Chain
+
+[Complete industry structure analysis]
+_Value Chain Components: [Detailed breakdown]_
+_Industry Segments: [Market segmentation analysis]_
+_Economic Impact: [Industry economic significance]_
+_Source: [URL]_
+
+## 3. Technology Landscape and Innovation Trends
+
+### Current Technology Adoption
+
+[Technology trends analysis from step-04 with current context]
+_Emerging Technologies: [Key technologies affecting {{research_topic}}]_
+_Adoption Patterns: [Technology adoption rates and patterns]_
+_Innovation Drivers: [Factors driving technology change]_
+_Source: [URL]_
+
+### Digital Transformation Impact
+
+[Comprehensive analysis of technology's impact on {{research_topic}}]
+_Transformation Trends: [Major digital transformation patterns]_
+_Disruption Opportunities: [Technology-driven opportunities]_
+_Future Technology Outlook: [Emerging technologies and timelines]_
+_Source: [URL]_
+
+## 4. Regulatory Framework and Compliance Requirements
+
+### Current Regulatory Landscape
+
+[Regulatory analysis from step-03 with current updates]
+_Key Regulations: [Critical regulatory requirements]_
+_Compliance Standards: [Industry standards and best practices]_
+_Recent Changes: [current regulatory updates and implications]_
+_Source: [URL]_
+
+### Risk and Compliance Considerations
+
+[Comprehensive risk assessment]
+_Compliance Risks: [Major regulatory and compliance risks]_
+_Risk Mitigation Strategies: [Approaches to manage regulatory risks]_
+_Future Regulatory Trends: [Anticipated regulatory developments]_
+_Source: [URL]_
+
+## 5. Competitive Landscape and Ecosystem Analysis
+
+### Market Positioning and Key Players
+
+[Competitive analysis with current market positioning]
+_Market Leaders: [Dominant players and strategies]_
+_Emerging Competitors: [New entrants and innovative approaches]_
+_Competitive Dynamics: [Market competition patterns and trends]_
+_Source: [URL]_
+
+### Ecosystem and Partnership Landscape
+
+[Complete ecosystem analysis]
+_Ecosystem Players: [Key stakeholders and relationships]_
+_Partnership Opportunities: [Strategic collaboration potential]_
+_Supply Chain Dynamics: [Supply chain structure and risks]_
+_Source: [URL]_
+
+## 6. Strategic Insights and Domain Opportunities
+
+### Cross-Domain Synthesis
+
+[Strategic insights from integrating all research sections]
+_Market-Technology Convergence: [How technology and market forces interact]_
+_Regulatory-Strategic Alignment: [How regulatory environment shapes strategy]_
+_Competitive Positioning Opportunities: [Strategic advantages based on research]_
+_Source: [URL]_
+
+### Strategic Opportunities
+
+[High-value opportunities identified through comprehensive research]
+_Market Opportunities: [Specific market entry or expansion opportunities]_
+_Technology Opportunities: [Technology adoption or innovation opportunities]_
+_Partnership Opportunities: [Strategic collaboration and partnership potential]_
+_Source: [URL]_
+
+## 7. Implementation Considerations and Risk Assessment
+
+### Implementation Framework
+
+[Practical implementation guidance based on research findings]
+_Implementation Timeline: [Recommended phased approach]_
+_Resource Requirements: [Key resources and capabilities needed]_
+_Success Factors: [Critical success factors for implementation]_
+_Source: [URL]_
+
+### Risk Management and Mitigation
+
+[Comprehensive risk assessment and mitigation strategies]
+_Implementation Risks: [Major risks and mitigation approaches]_
+_Market Risks: [Market-related risks and contingency plans]_
+_Technology Risks: [Technology adoption and implementation risks]_
+_Source: [URL]_
+
+## 8. Future Outlook and Strategic Planning
+
+### Future Trends and Projections
+
+[Forward-looking analysis based on comprehensive research]
+_Near-term Outlook: [1-2 year projections and implications]_
+_Medium-term Trends: [3-5 year expected developments]_
+_Long-term Vision: [5+ year strategic outlook for {{research_topic}}]_
+_Source: [URL]_
+
+### Strategic Recommendations
+
+[Comprehensive strategic recommendations]
+_Immediate Actions: [Priority actions for next 6 months]_
+_Strategic Initiatives: [Key strategic initiatives for 1-2 years]_
+_Long-term Strategy: [Strategic positioning for 3+ years]_
+_Source: [URL]_
+
+## 9. Research Methodology and Source Verification
+
+### Comprehensive Source Documentation
+
+[Complete documentation of all research sources]
+_Primary Sources: [Key authoritative sources used]_
+_Secondary Sources: [Supporting research and analysis]_
+_Web Search Queries: [Complete list of search queries used]_
+
+### Research Quality Assurance
+
+[Quality assurance and validation approach]
+_Source Verification: [All factual claims verified with multiple sources]_
+_Confidence Levels: [Confidence assessments for uncertain data]_
+_Limitations: [Research limitations and areas for further investigation]_
+_Methodology Transparency: [Complete transparency about research approach]_
+
+## 10. Appendices and Additional Resources
+
+### Detailed Data Tables
+
+[Comprehensive data tables supporting research findings]
+_Market Data Tables: [Detailed market size, growth, and segmentation data]_
+_Technology Adoption Data: [Detailed technology adoption and trend data]_
+_Regulatory Reference Tables: [Complete regulatory requirements and compliance data]_
+
+### Additional Resources
+
+[Valuable resources for continued research and implementation]
+_Industry Associations: [Key industry organizations and resources]_
+_Research Organizations: [Authoritative research institutions and reports]_
+_Government Resources: [Regulatory agencies and official resources]_
+_Professional Networks: [Industry communities and knowledge sources]_
+
+---
+
+## Research Conclusion
+
+### Summary of Key Findings
+
+[Comprehensive summary of the most important research findings]
+
+### Strategic Impact Assessment
+
+[Assessment of strategic implications for {{research_topic}}]
+
+### Next Steps Recommendations
+
+[Specific next steps for leveraging this research]
+
+---
+
+**Research Completion Date:** {{date}}
+**Research Period:** Comprehensive analysis
+**Document Length:** As needed for comprehensive coverage
+**Source Verification:** All facts cited with sources
+**Confidence Level:** High - based on multiple authoritative sources
+
+_This comprehensive research document serves as an authoritative reference on {{research_topic}} and provides strategic insights for informed decision-making._
+```
+
+### 5. Present Complete Document and Final Option
+
+**Document Completion Presentation:**
+
+"I've completed the **comprehensive research document synthesis** for **{{research_topic}}**, producing an authoritative research document with:
+
+**Document Features:**
+
+- **Compelling Narrative Introduction**: Engaging opening that establishes research significance
+- **Comprehensive Table of Contents**: Complete navigation structure for easy reference
+- **Exhaustive Research Coverage**: All aspects of {{research_topic}} thoroughly analyzed
+- **Executive Summary**: Key findings and strategic implications highlighted
+- **Strategic Recommendations**: Actionable insights based on comprehensive research
+- **Complete Source Citations**: Every factual claim verified with sources
+
+**Research Completeness:**
+
+- Industry analysis and market dynamics fully documented
+- Technology trends and innovation landscape comprehensively covered
+- Regulatory framework and compliance requirements detailed
+- Competitive landscape and ecosystem analysis complete
+- Strategic insights and implementation guidance provided
+
+**Document Standards Met:**
+
+- Exhaustive research with no critical gaps
+- Professional structure and compelling narrative
+- As long as needed for comprehensive coverage
+- Multiple independent sources for all claims
+- Proper citations throughout
+
+**Ready to complete this comprehensive research document?**
+[C] Complete Research - Save final comprehensive document
+
+### 6. Handle Final Completion
+
+#### If 'C' (Complete Research):
+
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
+- Append the complete document to the research file
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
+- Complete the domain research workflow
+- Provide final document delivery confirmation
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the complete comprehensive research document using the full structure above. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
+
+## SUCCESS METRICS:
+
+✅ Compelling narrative introduction with research significance
+✅ Comprehensive table of contents with complete document structure
+✅ Exhaustive research coverage across all domain aspects
+✅ Executive summary with key findings and strategic implications
+✅ Strategic recommendations grounded in comprehensive research
+✅ Complete source verification with citations
+✅ Professional document structure and compelling narrative
+✅ [C] complete option presented and handled correctly
+✅ Domain research workflow completed with comprehensive document
+
+## FAILURE MODES:
+
+❌ Not producing compelling narrative introduction
+❌ Missing comprehensive table of contents
+❌ Incomplete research coverage across domain aspects
+❌ Not providing executive summary with key findings
+❌ Missing strategic recommendations based on research
+❌ Relying solely on training data without web verification for current facts
+❌ Producing document without professional structure
+❌ Not presenting completion option for final document
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## COMPREHENSIVE DOCUMENT STANDARDS:
+
+This step ensures the final research document:
+
+- Serves as an authoritative reference on {{research_topic}}
+- Provides compelling narrative and professional structure
+- Includes comprehensive coverage with no gaps
+- Maintains rigorous source verification standards
+- Delivers strategic insights and actionable recommendations
+- Meets professional research document quality standards
+
+## DOMAIN RESEARCH WORKFLOW COMPLETION:
+
+When 'C' is selected:
+
+- All domain research steps completed (1-5)
+- Comprehensive domain research document generated
+- Professional document structure with intro, TOC, and summary
+- All sections appended with source citations
+- Domain research workflow status updated to complete
+- Final comprehensive research document delivered to user
+
+## FINAL DELIVERABLE:
+
+Complete authoritative research document on {{research_topic}} that:
+
+- Establishes professional credibility through comprehensive research
+- Provides strategic insights for informed decision-making
+- Serves as reference document for continued use
+- Maintains highest research quality standards
+
+Congratulations on completing comprehensive domain research! 🎉
diff --git a/.claude/skills/bmad-domain-research/research.template.md b/.claude/skills/bmad-domain-research/research.template.md
new file mode 100644
index 0000000..1d99524
--- /dev/null
+++ b/.claude/skills/bmad-domain-research/research.template.md
@@ -0,0 +1,29 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'research'
+lastStep: 1
+research_type: '{{research_type}}'
+research_topic: '{{research_topic}}'
+research_goals: '{{research_goals}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+web_research_enabled: true
+source_verification: true
+---
+
+# Research Report: {{research_type}}
+
+**Date:** {{date}}
+**Author:** {{user_name}}
+**Research Type:** {{research_type}}
+
+---
+
+## Research Overview
+
+[Research overview and methodology will be appended here]
+
+---
+
+<!-- Content will be appended sequentially through research workflow steps -->
diff --git a/.claude/skills/bmad-domain-research/workflow.md b/.claude/skills/bmad-domain-research/workflow.md
new file mode 100644
index 0000000..fca2613
--- /dev/null
+++ b/.claude/skills/bmad-domain-research/workflow.md
@@ -0,0 +1,51 @@
+# Domain Research Workflow
+
+**Goal:** Conduct comprehensive domain/industry research using current web data and verified sources to produce complete research documents with compelling narratives and proper citations.
+
+**Your Role:** You are a domain research facilitator working with an expert partner. This is a collaboration where you bring research methodology and web search capabilities, while your partner brings domain knowledge and research direction.
+
+## PREREQUISITE
+
+**⛔ Web search required.** If unavailable, abort and tell the user.
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+## QUICK TOPIC DISCOVERY
+
+"Welcome {{user_name}}! Let's get started with your **domain/industry research**.
+
+**What domain, industry, or sector do you want to research?**
+
+For example:
+- 'The healthcare technology industry'
+- 'Sustainable packaging regulations in Europe'
+- 'Construction and building materials sector'
+- 'Or any other domain you have in mind...'"
+
+### Topic Clarification
+
+Based on the user's topic, briefly clarify:
+1. **Core Domain**: "What specific aspect of [domain] are you most interested in?"
+2. **Research Goals**: "What do you hope to achieve with this research?"
+3. **Scope**: "Should we focus broadly or dive deep into specific aspects?"
+
+## ROUTE TO DOMAIN RESEARCH STEPS
+
+After gathering the topic and goals:
+
+1. Set `research_type = "domain"`
+2. Set `research_topic = [discovered topic from discussion]`
+3. Set `research_goals = [discovered goals from discussion]`
+4. Create the starter output file: `{planning_artifacts}/research/domain-{{research_topic}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents
+5. Load: `./domain-steps/step-01-init.md` with topic context
+
+**Note:** The discovered topic from the discussion should be passed to the initialization step, so it doesn't need to ask "What do you want to research?" again - it can focus on refining the scope for domain research.
+
+**✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`**
diff --git a/.claude/skills/bmad-edit-prd/SKILL.md b/.claude/skills/bmad-edit-prd/SKILL.md
new file mode 100644
index 0000000..b16498d
--- /dev/null
+++ b/.claude/skills/bmad-edit-prd/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-edit-prd
+description: 'Edit an existing PRD. Use when the user says "edit this PRD".'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-edit-prd/data/prd-purpose.md b/.claude/skills/bmad-edit-prd/data/prd-purpose.md
new file mode 100644
index 0000000..755230b
--- /dev/null
+++ b/.claude/skills/bmad-edit-prd/data/prd-purpose.md
@@ -0,0 +1,197 @@
+# BMAD PRD Purpose
+
+**The PRD is the top of the required funnel that feeds all subsequent product development work in rhw BMad Method.**
+
+---
+
+## What is a BMAD PRD?
+
+A dual-audience document serving:
+1. **Human Product Managers and builders** - Vision, strategy, stakeholder communication
+2. **LLM Downstream Consumption** - UX Design → Architecture → Epics → Development AI Agents
+
+Each successive document becomes more AI-tailored and granular.
+
+---
+
+## Core Philosophy: Information Density
+
+**High Signal-to-Noise Ratio**
+
+Every sentence must carry information weight. LLMs consume precise, dense content efficiently.
+
+**Anti-Patterns (Eliminate These):**
+- ❌ "The system will allow users to..." → ✅ "Users can..."
+- ❌ "It is important to note that..." → ✅ State the fact directly
+- ❌ "In order to..." → ✅ "To..."
+- ❌ Conversational filler and padding → ✅ Direct, concise statements
+
+**Goal:** Maximum information per word. Zero fluff.
+
+---
+
+## The Traceability Chain
+
+**PRD starts the chain:**
+```
+Vision → Success Criteria → User Journeys → Functional Requirements → (future: User Stories)
+```
+
+**In the PRD, establish:**
+- Vision → Success Criteria alignment
+- Success Criteria → User Journey coverage
+- User Journey → Functional Requirement mapping
+- All requirements traceable to user needs
+
+**Why:** Each downstream artifact (UX, Architecture, Epics, Stories) must trace back to documented user needs and business objectives. This chain ensures we build the right thing.
+
+---
+
+## What Makes Great Functional Requirements?
+
+### FRs are Capabilities, Not Implementation
+
+**Good FR:** "Users can reset their password via email link"
+**Bad FR:** "System sends JWT via email and validates with database" (implementation leakage)
+
+**Good FR:** "Dashboard loads in under 2 seconds for 95th percentile"
+**Bad FR:** "Fast loading time" (subjective, unmeasurable)
+
+### SMART Quality Criteria
+
+**Specific:** Clear, precisely defined capability
+**Measurable:** Quantifiable with test criteria
+**Attainable:** Realistic within constraints
+**Relevant:** Aligns with business objectives
+**Traceable:** Links to source (executive summary or user journey)
+
+### FR Anti-Patterns
+
+**Subjective Adjectives:**
+- ❌ "easy to use", "intuitive", "user-friendly", "fast", "responsive"
+- ✅ Use metrics: "completes task in under 3 clicks", "loads in under 2 seconds"
+
+**Implementation Leakage:**
+- ❌ Technology names, specific libraries, implementation details
+- ✅ Focus on capability and measurable outcomes
+
+**Vague Quantifiers:**
+- ❌ "multiple users", "several options", "various formats"
+- ✅ "up to 100 concurrent users", "3-5 options", "PDF, DOCX, TXT formats"
+
+**Missing Test Criteria:**
+- ❌ "The system shall provide notifications"
+- ✅ "The system shall send email notifications within 30 seconds of trigger event"
+
+---
+
+## What Makes Great Non-Functional Requirements?
+
+### NFRs Must Be Measurable
+
+**Template:**
+```
+"The system shall [metric] [condition] [measurement method]"
+```
+
+**Examples:**
+- ✅ "The system shall respond to API requests in under 200ms for 95th percentile as measured by APM monitoring"
+- ✅ "The system shall maintain 99.9% uptime during business hours as measured by cloud provider SLA"
+- ✅ "The system shall support 10,000 concurrent users as measured by load testing"
+
+### NFR Anti-Patterns
+
+**Unmeasurable Claims:**
+- ❌ "The system shall be scalable" → ✅ "The system shall handle 10x load growth through horizontal scaling"
+- ❌ "High availability required" → ✅ "99.9% uptime as measured by cloud provider SLA"
+
+**Missing Context:**
+- ❌ "Response time under 1 second" → ✅ "API response time under 1 second for 95th percentile under normal load"
+
+---
+
+## Domain-Specific Requirements
+
+**Auto-Detect and Enforce Based on Project Context**
+
+Certain industries have mandatory requirements that must be present:
+
+- **Healthcare:** HIPAA Privacy & Security Rules, PHI encryption, audit logging, MFA
+- **Fintech:** PCI-DSS Level 1, AML/KYC compliance, SOX controls, financial audit trails
+- **GovTech:** NIST framework, Section 508 accessibility (WCAG 2.1 AA), FedRAMP, data residency
+- **E-Commerce:** PCI-DSS for payments, inventory accuracy, tax calculation by jurisdiction
+
+**Why:** Missing these requirements in the PRD means they'll be missed in architecture and implementation, creating expensive rework. During PRD creation there is a step to cover this - during validation we want to make sure it was covered. For this purpose steps will utilize a domain-complexity.csv and project-types.csv.
+
+---
+
+## Document Structure (Markdown, Human-Readable)
+
+### Required Sections
+1. **Executive Summary** - Vision, differentiator, target users
+2. **Success Criteria** - Measurable outcomes (SMART)
+3. **Product Scope** - MVP, Growth, Vision phases
+4. **User Journeys** - Comprehensive coverage
+5. **Domain Requirements** - Industry-specific compliance (if applicable)
+6. **Innovation Analysis** - Competitive differentiation (if applicable)
+7. **Project-Type Requirements** - Platform-specific needs
+8. **Functional Requirements** - Capability contract (FRs)
+9. **Non-Functional Requirements** - Quality attributes (NFRs)
+
+### Formatting for Dual Consumption
+
+**For Humans:**
+- Clear, professional language
+- Logical flow from vision to requirements
+- Easy for stakeholders to review and approve
+
+**For LLMs:**
+- ## Level 2 headers for all main sections (enables extraction)
+- Consistent structure and patterns
+- Precise, testable language
+- High information density
+
+---
+
+## Downstream Impact
+
+**How the PRD Feeds Next Artifacts:**
+
+**UX Design:**
+- User journeys → interaction flows
+- FRs → design requirements
+- Success criteria → UX metrics
+
+**Architecture:**
+- FRs → system capabilities
+- NFRs → architecture decisions
+- Domain requirements → compliance architecture
+- Project-type requirements → platform choices
+
+**Epics & Stories (created after architecture):**
+- FRs → user stories (1 FR could map to 1-3 stories potentially)
+- Acceptance criteria → story acceptance tests
+- Priority → sprint sequencing
+- Traceability → stories map back to vision
+
+**Development AI Agents:**
+- Precise requirements → implementation clarity
+- Test criteria → automated test generation
+- Domain requirements → compliance enforcement
+- Measurable NFRs → performance targets
+
+---
+
+## Summary: What Makes a Great BMAD PRD?
+
+✅ **High Information Density** - Every sentence carries weight, zero fluff
+✅ **Measurable Requirements** - All FRs and NFRs are testable with specific criteria
+✅ **Clear Traceability** - Each requirement links to user need and business objective
+✅ **Domain Awareness** - Industry-specific requirements auto-detected and included
+✅ **Zero Anti-Patterns** - No subjective adjectives, implementation leakage, or vague quantifiers
+✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable
+✅ **Markdown Format** - Professional, clean, accessible to all stakeholders
+
+---
+
+**Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective.
diff --git a/.claude/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md b/.claude/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md
new file mode 100644
index 0000000..39e3449
--- /dev/null
+++ b/.claude/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md
@@ -0,0 +1,242 @@
+---
+# File references (ONLY variables used in this step)
+prdPurpose: '../data/prd-purpose.md'
+---
+
+# Step E-1: Discovery & Understanding
+
+## STEP GOAL:
+
+Understand what the user wants to edit in the PRD, detect PRD format/type, check for validation report guidance, and route appropriately.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and PRD Improvement Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring analytical expertise and improvement guidance
+- ✅ User brings domain knowledge and edit requirements
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on discovering user intent and PRD format
+- 🚫 FORBIDDEN to make any edits yet
+- 💬 Approach: Inquisitive and analytical, understanding before acting
+- 🚪 This is a branch step - may route to legacy conversion
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Discover user's edit requirements
+- 🎯 Auto-detect validation reports in PRD folder (use as guide)
+- 🎯 Load validation report if provided (use as guide)
+- 🎯 Detect PRD format (BMAD/legacy)
+- 🎯 Route appropriately based on format
+- 💾 Document discoveries for next step
+- 🚫 FORBIDDEN to proceed without understanding requirements
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file to edit, optional validation report, auto-detected validation reports
+- Focus: User intent discovery and format detection only
+- Limits: Don't edit yet, don't validate yet
+- Dependencies: None - this is first edit step
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load PRD Purpose Standards
+
+Load and read the complete file at:
+`{prdPurpose}` (data/prd-purpose.md)
+
+This file defines what makes a great BMAD PRD. Internalize this understanding - it will guide improvement recommendations.
+
+### 2. Discover PRD to Edit
+
+"**PRD Edit Workflow**
+
+Which PRD would you like to edit?
+
+Please provide the path to the PRD file you want to edit."
+
+**Wait for user to provide PRD path.**
+
+### 3. Validate PRD Exists and Load
+
+Once PRD path is provided:
+- Check if PRD file exists at specified path
+- If not found: "I cannot find a PRD at that path. Please check the path and try again."
+- If found: Load the complete PRD file including frontmatter
+
+### 4. Check for Existing Validation Report
+
+**Check if validation report exists in the PRD folder:**
+
+```bash
+# Look for most recent validation report in the PRD folder
+ls -t {prd_folder_path}/validation-report-*.md 2>/dev/null | head -1
+```
+
+**If validation report found:**
+
+Display:
+"**📋 Found Validation Report**
+
+I found a validation report from {validation_date} in the PRD folder.
+
+This report contains findings from previous validation checks and can help guide our edits to fix known issues.
+
+**Would you like to:**
+- **[U] Use validation report** - Load it to guide and prioritize edits
+- **[S] Skip** - Proceed with manual edit discovery"
+
+**Wait for user input.**
+
+**IF U (Use validation report):**
+- Load the validation report file
+- Extract findings, issues, and improvement suggestions
+- Note: "Validation report loaded - will use it to guide prioritized improvements"
+- Continue to step 5
+
+**IF S (Skip) or no validation report found:**
+- Note: "Proceeding with manual edit discovery"
+- Continue to step 5
+
+**If no validation report found:**
+- Note: "No validation report found in PRD folder"
+- Continue to step 5 without asking user
+
+### 5. Ask About Validation Report
+
+"**Do you have a validation report to guide edits?**
+
+If you've run the validation workflow on this PRD, I can use that report to guide improvements and prioritize changes.
+
+Validation report path (or type 'none'):"
+
+**Wait for user input.**
+
+**If validation report path provided:**
+- Load the validation report
+- Extract findings, severity, improvement suggestions
+- Note: "Validation report loaded - will use it to guide prioritized improvements"
+
+**If no validation report:**
+- Note: "Proceeding with manual edit discovery"
+- Continue to step 6
+
+### 6. Discover Edit Requirements
+
+"**What would you like to edit in this PRD?**
+
+Please describe the changes you want to make. For example:
+- Fix specific issues (information density, implementation leakage, etc.)
+- Add missing sections or content
+- Improve structure and flow
+- Convert to BMAD format (if legacy PRD)
+- General improvements
+- Other changes
+
+**Describe your edit goals:**"
+
+**Wait for user to describe their requirements.**
+
+### 7. Detect PRD Format
+
+Analyze the loaded PRD:
+
+**Extract all ## Level 2 headers** from PRD
+
+**Check for BMAD PRD core sections:**
+1. Executive Summary
+2. Success Criteria
+3. Product Scope
+4. User Journeys
+5. Functional Requirements
+6. Non-Functional Requirements
+
+**Classify format:**
+- **BMAD Standard:** 5-6 core sections present
+- **BMAD Variant:** 3-4 core sections present, generally follows BMAD patterns
+- **Legacy (Non-Standard):** Fewer than 3 core sections, does not follow BMAD structure
+
+### 8. Route Based on Format and Context
+
+**IF validation report provided OR PRD is BMAD Standard/Variant:**
+
+Display: "**Edit Requirements Understood**
+
+**PRD Format:** {classification}
+{If validation report: "**Validation Guide:** Yes - will use validation report findings"}
+**Edit Goals:** {summary of user's requirements}
+
+**Proceeding to deep review and analysis...**"
+
+Read fully and follow: `./step-e-02-review.md`
+
+**IF PRD is Legacy (Non-Standard) AND no validation report:**
+
+Display: "**Format Detected:** Legacy PRD
+
+This PRD does not follow BMAD standard structure (only {count}/6 core sections present).
+
+**Your edit goals:** {user's requirements}
+
+**How would you like to proceed?**"
+
+Present MENU OPTIONS below for user selection
+
+### 9. Present MENU OPTIONS (Legacy PRDs Only)
+
+**[C] Convert to BMAD Format** - Convert PRD to BMAD standard structure, then apply your edits
+**[E] Edit As-Is** - Apply your edits without converting the format
+**[X] Exit** - Exit and review conversion options
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- IF C (Convert): Read fully and follow: `./step-e-01b-legacy-conversion.md`
+- IF E (Edit As-Is): Display "Proceeding with edits..." then load next step
+- IF X (Exit): Display summary and exit
+- IF Any other: help user, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- User's edit requirements clearly understood
+- Auto-detected validation reports loaded and analyzed (when found)
+- Manual validation report loaded and analyzed (if provided)
+- PRD format detected correctly
+- BMAD PRDs proceed directly to review step
+- Legacy PRDs pause and present conversion options
+- User can choose conversion path or edit as-is
+
+### ❌ SYSTEM FAILURE:
+
+- Not discovering user's edit requirements
+- Not auto-detecting validation reports in PRD folder
+- Not loading validation report when provided (auto or manual)
+- Missing format detection
+- Not pausing for legacy PRDs without guidance
+- Auto-proceeding without understanding intent
+
+**Master Rule:** Understand before editing. Detect format early so we can guide users appropriately. Auto-detect and use validation reports for prioritized improvements.
diff --git a/.claude/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md b/.claude/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md
new file mode 100644
index 0000000..54f8252
--- /dev/null
+++ b/.claude/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md
@@ -0,0 +1,204 @@
+---
+# File references (ONLY variables used in this step)
+prdFile: '{prd_file_path}'
+prdPurpose: '../data/prd-purpose.md'
+---
+
+# Step E-1B: Legacy PRD Conversion Assessment
+
+## STEP GOAL:
+
+Analyze legacy PRD against BMAD standards, identify gaps, propose conversion strategy, and let user choose how to proceed.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and PRD Improvement Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring BMAD standards expertise and conversion guidance
+- ✅ User brings domain knowledge and edit requirements
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on conversion assessment and proposal
+- 🚫 FORBIDDEN to perform conversion yet (that comes in edit step)
+- 💬 Approach: Analytical gap analysis with clear recommendations
+- 🚪 This is a branch step - user chooses conversion path
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Analyze legacy PRD against BMAD standard
+- 💾 Identify gaps and estimate conversion effort
+- 📖 Present conversion options with effort estimates
+- 🚫 FORBIDDEN to proceed without user selection
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Legacy PRD, user's edit requirements, prd-purpose standards
+- Focus: Conversion assessment only (not actual conversion)
+- Limits: Don't convert yet, don't validate yet
+- Dependencies: Step e-01 detected legacy format and routed here
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Assessment
+
+**Try to use Task tool with sub-agent:**
+
+"Perform legacy PRD conversion assessment:
+
+**Load the PRD and prd-purpose.md**
+
+**For each BMAD PRD section, analyze:**
+1. Does PRD have this section? (Executive Summary, Success Criteria, Product Scope, User Journeys, Functional Requirements, Non-Functional Requirements)
+2. If present: Is it complete and well-structured?
+3. If missing: What content exists that could migrate to this section?
+4. Effort to create/complete: Minimal / Moderate / Significant
+
+**Identify:**
+- Core sections present: {count}/6
+- Content gaps in each section
+- Overall conversion effort: Quick / Moderate / Substantial
+- Recommended approach: Full restructuring vs targeted improvements
+
+Return conversion assessment with gap analysis and effort estimate."
+
+**Graceful degradation (if no Task tool):**
+- Manually check PRD for each BMAD section
+- Note what's present and what's missing
+- Estimate conversion effort
+- Identify best conversion approach
+
+### 2. Build Gap Analysis
+
+**For each BMAD core section:**
+
+**Executive Summary:**
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Success Criteria:**
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Product Scope:**
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**User Journeys:**
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Functional Requirements:**
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Non-Functional Requirements:**
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Overall Assessment:**
+- Sections Present: {count}/6
+- Total Conversion Effort: [Quick/Moderate/Substantial]
+- Recommended: [Full restructuring / Targeted improvements]
+
+### 3. Present Conversion Assessment
+
+Display:
+
+"**Legacy PRD Conversion Assessment**
+
+**Current PRD Structure:**
+- Core sections present: {count}/6
+{List which sections are present/missing}
+
+**Gap Analysis:**
+
+{Present gap analysis table showing each section's status and effort}
+
+**Overall Conversion Effort:** {effort level}
+
+**Your Edit Goals:**
+{Reiterate user's stated edit requirements}
+
+**Recommendation:**
+{Based on effort and user goals, recommend best approach}
+
+**How would you like to proceed?**"
+
+### 4. Present MENU OPTIONS
+
+**[R] Restructure to BMAD** - Full conversion to BMAD format, then apply your edits
+**[I] Targeted Improvements** - Apply your edits to existing structure without restructuring
+**[E] Edit & Restructure** - Do both: convert format AND apply your edits
+**[X] Exit** - Review assessment and decide
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- IF R (Restructure): Note conversion mode, then load next step
+- IF I (Targeted): Note targeted mode, then load next step
+- IF E (Edit & Restructure): Note both mode, then load next step
+- IF X (Exit): Display summary, exit
+
+### 5. Document Conversion Strategy
+
+Store conversion decision for next step:
+
+- **Conversion mode:** [Full restructuring / Targeted improvements / Both]
+- **Edit requirements:** [user's requirements from step e-01]
+- **Gap analysis:** [summary of gaps identified]
+
+Display: "**Conversion Strategy Documented**
+
+Mode: {conversion mode}
+Edit goals: {summary}
+
+**Proceeding to deep review...**"
+
+Read fully and follow: `./step-e-02-review.md`
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All 6 BMAD core sections analyzed for gaps
+- Effort estimates provided for each section
+- Overall conversion effort assessed correctly
+- Clear recommendation provided based on effort and user goals
+- User chooses conversion strategy (restructure/targeted/both)
+- Conversion strategy documented for next step
+
+### ❌ SYSTEM FAILURE:
+
+- Not analyzing all 6 core sections
+- Missing effort estimates
+- Not providing clear recommendation
+- Auto-proceeding without user selection
+- Not documenting conversion strategy
+
+**Master Rule:** Legacy PRDs need conversion assessment so users understand the work involved and can choose the best approach.
diff --git a/.claude/skills/bmad-edit-prd/steps-e/step-e-02-review.md b/.claude/skills/bmad-edit-prd/steps-e/step-e-02-review.md
new file mode 100644
index 0000000..c01a0ad
--- /dev/null
+++ b/.claude/skills/bmad-edit-prd/steps-e/step-e-02-review.md
@@ -0,0 +1,245 @@
+---
+# File references (ONLY variables used in this step)
+prdFile: '{prd_file_path}'
+validationReport: '{validation_report_path}'  # If provided
+prdPurpose: '../data/prd-purpose.md'
+---
+
+# Step E-2: Deep Review & Analysis
+
+## STEP GOAL:
+
+Thoroughly review the existing PRD, analyze validation report findings (if provided), and prepare a detailed change plan before editing.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and PRD Improvement Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring analytical expertise and improvement planning
+- ✅ User brings domain knowledge and approval authority
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on review and analysis, not editing yet
+- 🚫 FORBIDDEN to make changes to PRD in this step
+- 💬 Approach: Thorough analysis with user confirmation on plan
+- 🚪 This is a middle step - user confirms plan before proceeding
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load and analyze validation report (if provided)
+- 🎯 Deep review of entire PRD
+- 🎯 Map validation findings to specific sections
+- 🎯 Prepare detailed change plan
+- 💬 Get user confirmation on plan
+- 🚫 FORBIDDEN to proceed to edit without user approval
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file, validation report (if provided), user requirements from step e-01
+- Focus: Analysis and planning only (no editing)
+- Limits: Don't change PRD yet, don't validate yet
+- Dependencies: Step e-01 completed - requirements and format known
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Deep Review
+
+**Try to use Task tool with sub-agent:**
+
+"Perform deep PRD review and change planning:
+
+**Context from step e-01:**
+- User's edit requirements: {user_requirements}
+- PRD format: {BMAD/legacy}
+- Validation report provided: {yes/no}
+- Conversion mode: {restructure/targeted/both} (if legacy)
+
+**IF validation report provided:**
+1. Extract all findings from validation report
+2. Map findings to specific PRD sections
+3. Prioritize by severity: Critical > Warning > Informational
+4. For each critical issue: identify specific fix needed
+5. For user's manual edit goals: identify where in PRD to apply
+
+**IF no validation report:**
+1. Read entire PRD thoroughly
+2. Analyze against BMAD standards (from prd-purpose.md)
+3. Identify issues in:
+   - Information density (anti-patterns)
+   - Structure and flow
+   - Completeness (missing sections/content)
+   - Measurability (unmeasurable requirements)
+   - Traceability (broken chains)
+   - Implementation leakage
+4. Map user's edit goals to specific sections
+
+**Output:**
+- Section-by-section analysis
+- Specific changes needed for each section
+- Prioritized action list
+- Recommended order for applying changes
+
+Return detailed change plan with section breakdown."
+
+**Graceful degradation (if no Task tool):**
+- Manually read PRD sections
+- Manually analyze validation report findings (if provided)
+- Build section-by-section change plan
+- Prioritize changes by severity/user goals
+
+### 2. Build Change Plan
+
+**Organize by PRD section:**
+
+**For each section (in order):**
+- **Current State:** Brief description of what exists
+- **Issues Identified:** [List from validation report or manual analysis]
+- **Changes Needed:** [Specific changes required]
+- **Priority:** [Critical/High/Medium/Low]
+- **User Requirements Met:** [Which user edit goals address this section]
+
+**Include:**
+- Sections to add (if missing)
+- Sections to update (if present but needs work)
+- Content to remove (if incorrect/leakage)
+- Structure changes (if reformatting needed)
+
+### 3. Prepare Change Plan Summary
+
+**Summary sections:**
+
+**Changes by Type:**
+- **Additions:** {count} sections to add
+- **Updates:** {count} sections to update
+- **Removals:** {count} items to remove
+- **Restructuring:** {yes/no} if format conversion needed
+
+**Priority Distribution:**
+- **Critical:** {count} changes (must fix)
+- **High:** {count} changes (important)
+- **Medium:** {count} changes (nice to have)
+- **Low:** {count} changes (optional)
+
+**Estimated Effort:**
+[Quick/Moderate/Substantial] based on scope and complexity
+
+### 4. Present Change Plan to User
+
+Display:
+
+"**Deep Review Complete - Change Plan**
+
+**PRD Analysis:**
+{Brief summary of PRD current state}
+
+{If validation report provided:}
+**Validation Findings:**
+{count} issues identified: {critical} critical, {warning} warnings
+
+**Your Edit Requirements:**
+{summary of what user wants to edit}
+
+**Proposed Change Plan:**
+
+**By Section:**
+{Present section-by-section breakdown}
+
+**By Priority:**
+- Critical: {count} items
+- High: {count} items
+- Medium: {count} items
+
+**Estimated Effort:** {effort level}
+
+**Questions:**
+1. Does this change plan align with what you had in mind?
+2. Any sections I should add/remove/reprioritize?
+3. Any concerns before I proceed with edits?
+
+**Review the plan and let me know if you'd like any adjustments.**"
+
+### 5. Get User Confirmation
+
+Wait for user to review and provide feedback.
+
+**If user wants adjustments:**
+- Discuss requested changes
+- Revise change plan accordingly
+- Represent for confirmation
+
+**If user approves:**
+- Note: "Change plan approved. Proceeding to edit step."
+- Continue to step 6
+
+### 6. Document Approved Plan
+
+Store approved change plan for next step:
+
+- **Approved changes:** Section-by-section list
+- **Priority order:** Sequence to apply changes
+- **User confirmed:** Yes
+
+Display: "**Change Plan Approved**
+
+{Brief summary of approved plan}
+
+**Proceeding to edit step...**"
+
+Read fully and follow: `./step-e-03-edit.md`
+
+### 7. Present MENU OPTIONS (If User Wants Discussion)
+
+**[A] Advanced Elicitation** - Get additional perspectives on change plan
+**[P] Party Mode** - Discuss with team for more ideas
+**[C] Continue to Edit** - Proceed with approved plan
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed to edit when user selects 'C'
+
+#### Menu Handling Logic:
+
+- IF A: Invoke the `bmad-advanced-elicitation` skill, then return to discussion
+- IF P: Invoke the `bmad-party-mode` skill, then return to discussion
+- IF C: Document approval, then load step-e-03-edit.md
+- IF Any other: discuss, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Validation report findings fully analyzed (if provided)
+- Deep PRD review completed systematically
+- Change plan built section-by-section
+- Changes prioritized by severity/user goals
+- User presented with clear plan
+- User confirms or adjusts plan
+- Approved plan documented for next step
+
+### ❌ SYSTEM FAILURE:
+
+- Not analyzing validation report findings (if provided)
+- Superficial review instead of deep analysis
+- Missing section-by-section breakdown
+- Not prioritizing changes
+- Proceeding without user approval
+
+**Master Rule:** Plan before editing. Thorough analysis ensures we make the right changes in the right order. User approval prevents misalignment.
diff --git a/.claude/skills/bmad-edit-prd/steps-e/step-e-03-edit.md b/.claude/skills/bmad-edit-prd/steps-e/step-e-03-edit.md
new file mode 100644
index 0000000..5b5e669
--- /dev/null
+++ b/.claude/skills/bmad-edit-prd/steps-e/step-e-03-edit.md
@@ -0,0 +1,250 @@
+---
+# File references (ONLY variables used in this step)
+prdFile: '{prd_file_path}'
+prdPurpose: '../data/prd-purpose.md'
+---
+
+# Step E-3: Edit & Update
+
+## STEP GOAL:
+
+Apply changes to the PRD following the approved change plan from step e-02, including content updates, structure improvements, and format conversion if needed.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 ALWAYS generate content WITH user input/approval
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and PRD Improvement Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring analytical expertise and precise editing skills
+- ✅ User brings domain knowledge and approval authority
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on implementing approved changes from step e-02
+- 🚫 FORBIDDEN to make changes beyond the approved plan
+- 💬 Approach: Methodical, section-by-section execution
+- 🚪 This is a middle step - user can request adjustments
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow approved change plan systematically
+- 💾 Edit PRD content according to plan
+- 📖 Update frontmatter as needed
+- 🚫 FORBIDDEN to proceed without completion
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file, approved change plan from step e-02, prd-purpose standards
+- Focus: Implementing changes from approved plan only
+- Limits: Don't add changes beyond plan, don't validate yet
+- Dependencies: Step e-02 completed - plan approved by user
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Retrieve Approved Change Plan
+
+From step e-02, retrieve:
+- **Approved changes:** Section-by-section list
+- **Priority order:** Sequence to apply changes
+- **User requirements:** Edit goals from step e-01
+
+Display: "**Starting PRD Edits**
+
+**Change Plan:** {summary}
+**Total Changes:** {count}
+**Estimated Effort:** {effort level}
+
+**Proceeding with edits section by section...**"
+
+### 2. Attempt Sub-Process Edits (For Complex Changes)
+
+**Try to use Task tool with sub-agent for major sections:**
+
+"Execute PRD edits for {section_name}:
+
+**Context:**
+- Section to edit: {section_name}
+- Current content: {existing content}
+- Changes needed: {specific changes from plan}
+- BMAD PRD standards: Load from prd-purpose.md
+
+**Tasks:**
+1. Read current PRD section
+2. Apply specified changes
+3. Ensure BMAD PRD principles compliance:
+   - High information density (no filler)
+   - Measurable requirements
+   - Clear structure
+   - Proper markdown formatting
+4. Return updated section content
+
+Apply changes and return updated section."
+
+**Graceful degradation (if no Task tool):**
+- Perform edits directly in current context
+- Load PRD section, apply changes, save
+
+### 3. Execute Changes Section-by-Section
+
+**For each section in approved plan (in priority order):**
+
+**a) Load current section**
+- Read the current PRD section content
+- Note what exists
+
+**b) Apply changes per plan**
+- Additions: Create new sections with proper content
+- Updates: Modify existing content per plan
+- Removals: Remove specified content
+- Restructuring: Reformat content to BMAD standard
+
+**c) Update PRD file**
+- Apply changes to PRD
+- Save updated PRD
+- Verify changes applied correctly
+
+**Display progress after each section:**
+"**Section Updated:** {section_name}
+Changes: {brief summary}
+{More sections remaining...}"
+
+### 4. Handle Restructuring (If Needed)
+
+**If conversion mode is "Full restructuring" or "Both":**
+
+**For restructuring:**
+- Reorganize PRD to BMAD standard structure
+- Ensure proper ## Level 2 headers
+- Reorder sections logically
+- Update PRD frontmatter to match BMAD format
+
+**Follow BMAD PRD structure:**
+1. Executive Summary
+2. Success Criteria
+3. Product Scope
+4. User Journeys
+5. Domain Requirements (if applicable)
+6. Innovation Analysis (if applicable)
+7. Project-Type Requirements
+8. Functional Requirements
+9. Non-Functional Requirements
+
+Display: "**PRD Restructured**
+BMAD standard structure applied.
+{Sections added/reordered}"
+
+### 5. Update PRD Frontmatter
+
+**Ensure frontmatter is complete and accurate:**
+
+```yaml
+---
+workflowType: 'prd'
+workflow: 'create'  # or 'validate' or 'edit'
+classification:
+  domain: '{domain}'
+  projectType: '{project_type}'
+  complexity: '{complexity}'
+inputDocuments: [list of input documents]
+stepsCompleted: ['step-e-01-discovery', 'step-e-02-review', 'step-e-03-edit']
+lastEdited: '{current_date}'
+editHistory:
+  - date: '{current_date}'
+    changes: '{summary of changes}'
+---
+```
+
+**Update frontmatter accordingly.**
+
+### 6. Final Review of Changes
+
+**Load complete updated PRD**
+
+**Verify:**
+- All approved changes applied correctly
+- PRD structure is sound
+- No unintended modifications
+- Frontmatter is accurate
+
+**If issues found:**
+- Fix them now
+- Note corrections made
+
+**If user wants adjustments:**
+- Accept feedback and make adjustments
+- Re-verify after adjustments
+
+### 7. Confirm Completion
+
+Display:
+
+"**PRD Edits Complete**
+
+**Changes Applied:** {count} sections modified
+**PRD Updated:** {prd_file_path}
+
+**Summary of Changes:**
+{Brief bullet list of major changes}
+
+**PRD is ready for:**
+- Use in downstream workflows (UX, Architecture)
+- Validation (if not yet validated)
+
+**What would you like to do next?**"
+
+### 8. Present MENU OPTIONS
+
+**[V] Run Validation** - Execute full validation workflow (./steps-v/step-v-01-discovery.md)
+**[S] Summary Only** - End with summary of changes (no validation)
+**[A] Adjust** - Make additional edits
+**[X] Exit** - Exit edit workflow
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- IF V (Validate): Display "Starting validation workflow..." then read fully and follow: `./steps-v/step-v-01-discovery.md`
+- IF S (Summary): Present edit summary and exit
+- IF A (Adjust): Accept additional requirements, loop back to editing
+- IF X (Exit): Display summary and exit
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All approved changes from step e-02 applied correctly
+- Changes executed in planned priority order
+- Restructuring completed (if needed)
+- Frontmatter updated accurately
+- Final verification confirms changes
+- User can proceed to validation or exit with summary
+- Option to run validation seamlessly integrates edit and validate modes
+
+### ❌ SYSTEM FAILURE:
+
+- Making changes beyond approved plan
+- Not following priority order
+- Missing restructuring (if conversion mode)
+- Not updating frontmatter
+- No final verification
+- Not saving updated PRD
+
+**Master Rule:** Execute the plan exactly as approved. PRD is now ready for validation or downstream use. Validation integration ensures quality.
diff --git a/.claude/skills/bmad-edit-prd/steps-e/step-e-04-complete.md b/.claude/skills/bmad-edit-prd/steps-e/step-e-04-complete.md
new file mode 100644
index 0000000..1406e63
--- /dev/null
+++ b/.claude/skills/bmad-edit-prd/steps-e/step-e-04-complete.md
@@ -0,0 +1,163 @@
+---
+# File references (ONLY variables used in this step)
+prdFile: '{prd_file_path}'
+---
+
+# Step E-4: Complete & Validate
+
+## STEP GOAL:
+
+Present summary of completed edits and offer next steps including seamless integration with validation workflow.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 ALWAYS generate content WITH user input/approval
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and PRD Improvement Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring synthesis and summary expertise
+- ✅ User chooses next actions
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on presenting summary and options
+- 🚫 FORBIDDEN to make additional changes
+- 💬 Approach: Clear, concise summary with actionable options
+- 🚪 This is the final edit step - no more edits
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Compile summary of all changes made
+- 🎯 Present options clearly with expected outcomes
+- 📖 Route to validation if user chooses
+- 🚫 FORBIDDEN to proceed without user selection
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Updated PRD file, edit history from step e-03
+- Focus: Summary and options only (no more editing)
+- Limits: Don't make changes, just present options
+- Dependencies: Step e-03 completed - all edits applied
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Compile Edit Summary
+
+From step e-03 change execution, compile:
+
+**Changes Made:**
+- Sections added: {list with names}
+- Sections updated: {list with names}
+- Content removed: {list}
+- Structure changes: {description}
+
+**Edit Details:**
+- Total sections affected: {count}
+- Mode: {restructure/targeted/both}
+- Priority addressed: {Critical/High/Medium/Low}
+
+**PRD Status:**
+- Format: {BMAD Standard / BMAD Variant / Legacy (converted)}
+- Completeness: {assessment}
+- Ready for: {downstream use cases}
+
+### 2. Present Completion Summary
+
+Display:
+
+"**✓ PRD Edit Complete**
+
+**Updated PRD:** {prd_file_path}
+
+**Changes Summary:**
+{Present bulleted list of major changes}
+
+**Edit Mode:** {mode}
+**Sections Modified:** {count}
+
+**PRD Format:** {format}
+
+**PRD is now ready for:**
+- Downstream workflows (UX Design, Architecture)
+- Validation to ensure quality
+- Production use
+
+**What would you like to do next?**"
+
+### 3. Present MENU OPTIONS
+
+Display:
+
+**[V] Run Full Validation** - Execute complete validation workflow (steps-v) to verify PRD quality
+**[E] Edit More** - Make additional edits to the PRD
+**[S] Summary** - End with detailed summary of changes
+**[X] Exit** - Exit edit workflow
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- **IF V (Run Full Validation):**
+  - Display: "**Starting Validation Workflow**"
+  - Display: "This will run all 13 validation checks on the updated PRD."
+  - Display: "Preparing to validate: {prd_file_path}"
+  - Display: "**Proceeding to validation...**"
+  - Invoke the `bmad-validate-prd` skill to run the complete validation workflow
+
+- **IF E (Edit More):**
+  - Display: "**Additional Edits**"
+  - Ask: "What additional edits would you like to make?"
+  - Accept input, then display: "**Returning to edit step...**"
+  - Read fully and follow: `./step-e-03-edit.md` again
+
+- **IF S (Summary):**
+  - Display detailed summary including:
+    - Complete list of all changes made
+    - Before/after comparison (key improvements)
+    - Recommendations for next steps
+  - Display: "**Edit Workflow Complete**"
+  - Exit
+
+- **IF X (Exit):**
+  - Display summary
+  - Display: "**Edit Workflow Complete**"
+  - Exit
+
+- **IF Any other:** Help user, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Complete edit summary compiled accurately
+- All changes clearly documented
+- Options presented with clear expectations
+- Validation option seamlessly integrates with steps-v workflow
+- User can validate, edit more, or exit
+- Clean handoff to validation workflow (if chosen)
+- Edit workflow completes properly
+
+### ❌ SYSTEM FAILURE:
+
+- Missing changes in summary
+- Not offering validation option
+- Not documenting completion properly
+- No clear handoff to validation workflow
+
+**Master Rule:** Edit workflow seamlessly integrates with validation. User can edit → validate → edit again → validate again in iterative improvement cycle.
diff --git a/.claude/skills/bmad-edit-prd/workflow.md b/.claude/skills/bmad-edit-prd/workflow.md
new file mode 100644
index 0000000..23bd97c
--- /dev/null
+++ b/.claude/skills/bmad-edit-prd/workflow.md
@@ -0,0 +1,62 @@
+---
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+---
+
+# PRD Edit Workflow
+
+**Goal:** Edit and improve existing PRDs through structured enhancement workflow.
+
+**Your Role:** PRD improvement specialist.
+
+You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
+✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`.
+
+2. Route to Edit Workflow
+
+"**Edit Mode: Improving an existing PRD.**"
+
+Prompt for PRD path: "Which PRD would you like to edit? Please provide the path to the PRD.md file."
+
+Then read fully and follow: `./steps-e/step-e-01-discovery.md`
diff --git a/.claude/skills/bmad-editorial-review-prose/SKILL.md b/.claude/skills/bmad-editorial-review-prose/SKILL.md
new file mode 100644
index 0000000..3498f92
--- /dev/null
+++ b/.claude/skills/bmad-editorial-review-prose/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: bmad-editorial-review-prose
+description: 'Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose'
+---
+
+# Editorial Review - Prose
+
+**Goal:** Review text for communication issues that impede comprehension and output suggested fixes in a three-column table.
+
+**Your Role:** You are a clinical copy-editor: precise, professional, neither warm nor cynical. Apply Microsoft Writing Style Guide principles as your baseline. Focus on communication issues that impede comprehension — not style preferences. NEVER rewrite for preference — only fix genuine issues. Follow ALL steps in the STEPS section IN EXACT ORDER. DO NOT skip steps or change the sequence. HALT immediately when halt-conditions are met. Each action within a step is a REQUIRED action to complete that step.
+
+**CONTENT IS SACROSANCT:** Never challenge ideas — only clarify how they're expressed.
+
+**Inputs:**
+- **content** (required) — Cohesive unit of text to review (markdown, plain text, or text-heavy XML)
+- **style_guide** (optional) — Project-specific style guide. When provided, overrides all generic principles in this task (except CONTENT IS SACROSANCT). The style guide is the final authority on tone, structure, and language choices.
+- **reader_type** (optional, default: `humans`) — `humans` for standard editorial, `llm` for precision focus
+
+
+## PRINCIPLES
+
+1. **Minimal intervention:** Apply the smallest fix that achieves clarity
+2. **Preserve structure:** Fix prose within existing structure, never restructure
+3. **Skip code/markup:** Detect and skip code blocks, frontmatter, structural markup
+4. **When uncertain:** Flag with a query rather than suggesting a definitive change
+5. **Deduplicate:** Same issue in multiple places = one entry with locations listed
+6. **No conflicts:** Merge overlapping fixes into single entries
+7. **Respect author voice:** Preserve intentional stylistic choices
+
+> **STYLE GUIDE OVERRIDE:** If a style_guide input is provided, it overrides ALL generic principles in this task (including the Microsoft Writing Style Guide baseline and reader_type-specific priorities). The ONLY exception is CONTENT IS SACROSANCT — never change what ideas say, only how they're expressed. When style guide conflicts with this task, style guide wins.
+
+
+## STEPS
+
+### Step 1: Validate Input
+
+- Check if content is empty or contains fewer than 3 words
+  - If empty or fewer than 3 words: **HALT** with error: "Content too short for editorial review (minimum 3 words required)"
+- Validate reader_type is `humans` or `llm` (or not provided, defaulting to `humans`)
+  - If reader_type is invalid: **HALT** with error: "Invalid reader_type. Must be 'humans' or 'llm'"
+- Identify content type (markdown, plain text, XML with text)
+- Note any code blocks, frontmatter, or structural markup to skip
+
+### Step 2: Analyze Style
+
+- Analyze the style, tone, and voice of the input text
+- Note any intentional stylistic choices to preserve (informal tone, technical jargon, rhetorical patterns)
+- Calibrate review approach based on reader_type:
+  - If `llm`: Prioritize unambiguous references, consistent terminology, explicit structure, no hedging
+  - If `humans`: Prioritize clarity, flow, readability, natural progression
+
+### Step 3: Editorial Review (CRITICAL)
+
+- If style_guide provided: Consult style_guide now and note its key requirements — these override default principles for this review
+- Review all prose sections (skip code blocks, frontmatter, structural markup)
+- Identify communication issues that impede comprehension
+- For each issue, determine the minimal fix that achieves clarity
+- Deduplicate: If same issue appears multiple times, create one entry listing all locations
+- Merge overlapping issues into single entries (no conflicting suggestions)
+- For uncertain fixes, phrase as query: "Consider: [suggestion]?" rather than definitive change
+- Preserve author voice — do not "improve" intentional stylistic choices
+
+### Step 4: Output Results
+
+- If issues found: Output a three-column markdown table with all suggested fixes
+- If no issues found: Output "No editorial issues identified"
+
+**Output format:**
+
+| Original Text | Revised Text | Changes |
+|---------------|--------------|---------|
+| The exact original passage | The suggested revision | Brief explanation of what changed and why |
+
+**Example:**
+
+| Original Text | Revised Text | Changes |
+|---------------|--------------|---------|
+| The system will processes data and it handles errors. | The system processes data and handles errors. | Fixed subject-verb agreement ("will processes" to "processes"); removed redundant "it" |
+| Users can chose from options (lines 12, 45, 78) | Users can choose from options | Fixed spelling: "chose" to "choose" (appears in 3 locations) |
+
+
+## HALT CONDITIONS
+
+- HALT with error if content is empty or fewer than 3 words
+- HALT with error if reader_type is not `humans` or `llm`
+- If no issues found after thorough review, output "No editorial issues identified" (this is valid completion, not an error)
diff --git a/.claude/skills/bmad-editorial-review-structure/SKILL.md b/.claude/skills/bmad-editorial-review-structure/SKILL.md
new file mode 100644
index 0000000..c931831
--- /dev/null
+++ b/.claude/skills/bmad-editorial-review-structure/SKILL.md
@@ -0,0 +1,179 @@
+---
+name: bmad-editorial-review-structure
+description: 'Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure'
+---
+
+# Editorial Review - Structure
+
+**Goal:** Review document structure and propose substantive changes to improve clarity and flow -- run this BEFORE copy editing.
+
+**Your Role:** You are a structural editor focused on HIGH-VALUE DENSITY. Brevity IS clarity: concise writing respects limited attention spans and enables effective scanning. Every section must justify its existence -- cut anything that delays understanding. True redundancy is failure. Follow ALL steps in the STEPS section IN EXACT ORDER. DO NOT skip steps or change the sequence. HALT immediately when halt-conditions are met. Each action within a step is a REQUIRED action to complete that step.
+
+> **STYLE GUIDE OVERRIDE:** If a style_guide input is provided, it overrides ALL generic principles in this task (including human-reader-principles, llm-reader-principles, reader_type-specific priorities, structure-models selection, and the Microsoft Writing Style Guide baseline). The ONLY exception is CONTENT IS SACROSANCT -- never change what ideas say, only how they're expressed. When style guide conflicts with this task, style guide wins.
+
+**Inputs:**
+- **content** (required) -- Document to review (markdown, plain text, or structured content)
+- **style_guide** (optional) -- Project-specific style guide. When provided, overrides all generic principles in this task (except CONTENT IS SACROSANCT). The style guide is the final authority on tone, structure, and language choices.
+- **purpose** (optional) -- Document's intended purpose (e.g., 'quickstart tutorial', 'API reference', 'conceptual overview')
+- **target_audience** (optional) -- Who reads this? (e.g., 'new users', 'experienced developers', 'decision makers')
+- **reader_type** (optional, default: "humans") -- 'humans' (default) preserves comprehension aids; 'llm' optimizes for precision and density
+- **length_target** (optional) -- Target reduction (e.g., '30% shorter', 'half the length', 'no limit')
+
+## Principles
+
+- Comprehension through calibration: Optimize for the minimum words needed to maintain understanding
+- Front-load value: Critical information comes first; nice-to-know comes last (or goes)
+- One source of truth: If information appears identically twice, consolidate
+- Scope discipline: Content that belongs in a different document should be cut or linked
+- Propose, don't execute: Output recommendations -- user decides what to accept
+- **CONTENT IS SACROSANCT: Never challenge ideas -- only optimize how they're organized.**
+
+## Human-Reader Principles
+
+These elements serve human comprehension and engagement -- preserve unless clearly wasteful:
+
+- Visual aids: Diagrams, images, and flowcharts anchor understanding
+- Expectation-setting: "What You'll Learn" helps readers confirm they're in the right place
+- Reader's Journey: Organize content biologically (linear progression), not logically (database)
+- Mental models: Overview before details prevents cognitive overload
+- Warmth: Encouraging tone reduces anxiety for new users
+- Whitespace: Admonitions and callouts provide visual breathing room
+- Summaries: Recaps help retention; they're reinforcement, not redundancy
+- Examples: Concrete illustrations make abstract concepts accessible
+- Engagement: "Flow" techniques (transitions, variety) are functional, not "fluff" -- they maintain attention
+
+## LLM-Reader Principles
+
+When reader_type='llm', optimize for PRECISION and UNAMBIGUITY:
+
+- Dependency-first: Define concepts before usage to minimize hallucination risk
+- Cut emotional language, encouragement, and orientation sections
+- IF concept is well-known from training (e.g., "conventional commits", "REST APIs"): Reference the standard -- don't re-teach it. ELSE: Be explicit -- don't assume the LLM will infer correctly.
+- Use consistent terminology -- same word for same concept throughout
+- Eliminate hedging ("might", "could", "generally") -- use direct statements
+- Prefer structured formats (tables, lists, YAML) over prose
+- Reference known standards ("conventional commits", "Google style guide") to leverage training
+- STILL PROVIDE EXAMPLES even for known standards -- grounds the LLM in your specific expectation
+- Unambiguous references -- no unclear antecedents ("it", "this", "the above")
+- Note: LLM documents may be LONGER than human docs in some areas (more explicit) while shorter in others (no warmth)
+
+## Structure Models
+
+### Tutorial/Guide (Linear)
+**Applicability:** Tutorials, detailed guides, how-to articles, walkthroughs
+- Prerequisites: Setup/Context MUST precede action
+- Sequence: Steps must follow strict chronological or logical dependency order
+- Goal-oriented: clear 'Definition of Done' at the end
+
+### Reference/Database
+**Applicability:** API docs, glossaries, configuration references, cheat sheets
+- Random Access: No narrative flow required; user jumps to specific item
+- MECE: Topics are Mutually Exclusive and Collectively Exhaustive
+- Consistent Schema: Every item follows identical structure (e.g., Signature to Params to Returns)
+
+### Explanation (Conceptual)
+**Applicability:** Deep dives, architecture overviews, conceptual guides, whitepapers, project context
+- Abstract to Concrete: Definition to Context to Implementation/Example
+- Scaffolding: Complex ideas built on established foundations
+
+### Prompt/Task Definition (Functional)
+**Applicability:** BMAD tasks, prompts, system instructions, XML definitions
+- Meta-first: Inputs, usage constraints, and context defined before instructions
+- Separation of Concerns: Instructions (logic) separate from Data (content)
+- Step-by-step: Execution flow must be explicit and ordered
+
+### Strategic/Context (Pyramid)
+**Applicability:** PRDs, research reports, proposals, decision records
+- Top-down: Conclusion/Status/Recommendation starts the document
+- Grouping: Supporting context grouped logically below the headline
+- Ordering: Most critical information first
+- MECE: Arguments/Groups are Mutually Exclusive and Collectively Exhaustive
+- Evidence: Data supports arguments, never leads
+
+## STEPS
+
+### Step 1: Validate Input
+
+- Check if content is empty or contains fewer than 3 words
+- If empty or fewer than 3 words, HALT with error: "Content too short for substantive review (minimum 3 words required)"
+- Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")
+- If reader_type is invalid, HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"
+- Identify document type and structure (headings, sections, lists, etc.)
+- Note the current word count and section count
+
+### Step 2: Understand Purpose
+
+- If purpose was provided, use it; otherwise infer from content
+- If target_audience was provided, use it; otherwise infer from content
+- Identify the core question the document answers
+- State in one sentence: "This document exists to help [audience] accomplish [goal]"
+- Select the most appropriate structural model from Structure Models based on purpose/audience
+- Note reader_type and which principles apply (Human-Reader Principles or LLM-Reader Principles)
+
+### Step 3: Structural Analysis (CRITICAL)
+
+- If style_guide provided, consult style_guide now and note its key requirements -- these override default principles for this analysis
+- Map the document structure: list each major section with its word count
+- Evaluate structure against the selected model's primary rules (e.g., 'Does recommendation come first?' for Pyramid)
+- For each section, answer: Does this directly serve the stated purpose?
+- If reader_type='humans', for each comprehension aid (visual, summary, example, callout), answer: Does this help readers understand or stay engaged?
+- Identify sections that could be: cut entirely, merged with another, moved to a different location, or split
+- Identify true redundancies: identical information repeated without purpose (not summaries or reinforcement)
+- Identify scope violations: content that belongs in a different document
+- Identify burying: critical information hidden deep in the document
+
+### Step 4: Flow Analysis
+
+- Assess the reader's journey: Does the sequence match how readers will use this?
+- Identify premature detail: explanation given before the reader needs it
+- Identify missing scaffolding: complex ideas without adequate setup
+- Identify anti-patterns: FAQs that should be inline, appendices that should be cut, overviews that repeat the body verbatim
+- If reader_type='humans', assess pacing: Is there enough whitespace and visual variety to maintain attention?
+
+### Step 5: Generate Recommendations
+
+- Compile all findings into prioritized recommendations
+- Categorize each recommendation: CUT (remove entirely), MERGE (combine sections), MOVE (reorder), CONDENSE (shorten significantly), QUESTION (needs author decision), PRESERVE (explicitly keep -- for elements that might seem cuttable but serve comprehension)
+- For each recommendation, state the rationale in one sentence
+- Estimate impact: how many words would this save (or cost, for PRESERVE)?
+- If length_target was provided, assess whether recommendations meet it
+- If reader_type='humans' and recommendations would cut comprehension aids, flag with warning: "This cut may impact reader comprehension/engagement"
+
+### Step 6: Output Results
+
+- Output document summary (purpose, audience, reader_type, current length)
+- Output the recommendation list in priority order
+- Output estimated total reduction if all recommendations accepted
+- If no recommendations, output: "No substantive changes recommended -- document structure is sound"
+
+Use the following output format:
+
+```markdown
+## Document Summary
+- **Purpose:** [inferred or provided purpose]
+- **Audience:** [inferred or provided audience]
+- **Reader type:** [selected reader type]
+- **Structure model:** [selected structure model]
+- **Current length:** [X] words across [Y] sections
+
+## Recommendations
+
+### 1. [CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE] - [Section or element name]
+**Rationale:** [One sentence explanation]
+**Impact:** ~[X] words
+**Comprehension note:** [If applicable, note impact on reader understanding]
+
+### 2. ...
+
+## Summary
+- **Total recommendations:** [N]
+- **Estimated reduction:** [X] words ([Y]% of original)
+- **Meets length target:** [Yes/No/No target specified]
+- **Comprehension trade-offs:** [Note any cuts that sacrifice reader engagement for brevity]
+```
+
+## HALT CONDITIONS
+
+- HALT with error if content is empty or fewer than 3 words
+- HALT with error if reader_type is not "humans" or "llm"
+- If no structural issues found, output "No substantive changes recommended" (this is valid completion, not an error)
diff --git a/.claude/skills/bmad-generate-project-context/SKILL.md b/.claude/skills/bmad-generate-project-context/SKILL.md
new file mode 100644
index 0000000..e54067b
--- /dev/null
+++ b/.claude/skills/bmad-generate-project-context/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-generate-project-context
+description: 'Create project-context.md with AI rules. Use when the user says "generate project context" or "create project context"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-generate-project-context/project-context-template.md b/.claude/skills/bmad-generate-project-context/project-context-template.md
new file mode 100644
index 0000000..ee01c4b
--- /dev/null
+++ b/.claude/skills/bmad-generate-project-context/project-context-template.md
@@ -0,0 +1,21 @@
+---
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+sections_completed: ['technology_stack']
+existing_patterns_found: { { number_of_patterns_discovered } }
+---
+
+# Project Context for AI Agents
+
+_This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss._
+
+---
+
+## Technology Stack & Versions
+
+_Documented after discovery phase_
+
+## Critical Implementation Rules
+
+_Documented after discovery phase_
diff --git a/.claude/skills/bmad-generate-project-context/steps/step-01-discover.md b/.claude/skills/bmad-generate-project-context/steps/step-01-discover.md
new file mode 100644
index 0000000..7c69b7e
--- /dev/null
+++ b/.claude/skills/bmad-generate-project-context/steps/step-01-discover.md
@@ -0,0 +1,186 @@
+# Step 1: Context Discovery & Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- ✅ ALWAYS treat this as collaborative discovery between technical peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on discovering existing project context and technology stack
+- 🎯 IDENTIFY critical implementation rules that AI agents need
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 📖 Read existing project files to understand current context
+- 💾 Initialize document and update frontmatter
+- 🚫 FORBIDDEN to load next step until discovery is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Focus on existing project files and architecture decisions
+- Look for patterns, conventions, and unique requirements
+- Prioritize rules that prevent implementation mistakes
+
+## YOUR TASK:
+
+Discover the project's technology stack, existing patterns, and critical implementation rules that AI agents must follow when writing code.
+
+## DISCOVERY SEQUENCE:
+
+### 1. Check for Existing Project Context
+
+First, check if project context already exists:
+
+- Look for file at `{project_knowledge}/project-context.md or {project-root}/**/project-context.md`
+- If exists: Read complete file to understand existing rules
+- Present to user: "Found existing project context with {number_of_sections} sections. Would you like to update this or create a new one?"
+
+### 2. Discover Project Technology Stack
+
+Load and analyze project files to identify technologies:
+
+**Architecture Document:**
+
+- Look for `{planning_artifacts}/architecture.md`
+- Extract technology choices with specific versions
+- Note architectural decisions that affect implementation
+
+**Package Files:**
+
+- Check for `package.json`, `requirements.txt`, `Cargo.toml`, etc.
+- Extract exact versions of all dependencies
+- Note development vs production dependencies
+
+**Configuration Files:**
+
+- Look for project language specific configs ( example: `tsconfig.json`)
+- Build tool configs (webpack, vite, next.config.js, etc.)
+- Linting and formatting configs (.eslintrc, .prettierrc, etc.)
+- Testing configurations (jest.config.js, vitest.config.ts, etc.)
+
+### 3. Identify Existing Code Patterns
+
+Search through existing codebase for patterns:
+
+**Naming Conventions:**
+
+- File naming patterns (PascalCase, kebab-case, etc.)
+- Component/function naming conventions
+- Variable naming patterns
+- Test file naming patterns
+
+**Code Organization:**
+
+- How components are structured
+- Where utilities and helpers are placed
+- How services are organized
+- Test organization patterns
+
+**Documentation Patterns:**
+
+- Comment styles and conventions
+- Documentation requirements
+- README and API doc patterns
+
+### 4. Extract Critical Implementation Rules
+
+Look for rules that AI agents might miss:
+
+**Language-Specific Rules:**
+
+- TypeScript strict mode requirements
+- Import/export conventions
+- Async/await vs Promise usage patterns
+- Error handling patterns specific to the language
+
+**Framework-Specific Rules:**
+
+- React hooks usage patterns
+- API route conventions
+- Middleware usage patterns
+- State management patterns
+
+**Testing Rules:**
+
+- Test structure requirements
+- Mock usage conventions
+- Integration vs unit test boundaries
+- Coverage requirements
+
+**Development Workflow Rules:**
+
+- Branch naming conventions
+- Commit message patterns
+- PR review requirements
+- Deployment procedures
+
+### 5. Initialize Project Context Document
+
+Based on discovery, create or update the context document:
+
+#### A. Fresh Document Setup (if no existing context)
+
+Copy template from `../project-context-template.md` to `{output_folder}/project-context.md`
+Initialize frontmatter fields.
+
+#### B. Existing Document Update
+
+Load existing context and prepare for updates
+Set frontmatter `sections_completed` to track what will be updated
+
+### 6. Present Discovery Summary
+
+Report findings to user:
+
+"Welcome {{user_name}}! I've analyzed your project for {{project_name}} to discover the context that AI agents need.
+
+**Technology Stack Discovered:**
+{{list_of_technologies_with_versions}}
+
+**Existing Patterns Found:**
+
+- {{number_of_patterns}} implementation patterns
+- {{number_of_conventions}} coding conventions
+- {{number_of_rules}} critical rules
+
+**Key Areas for Context Rules:**
+
+- {{area_1}} (e.g., TypeScript configuration)
+- {{area_2}} (e.g., Testing patterns)
+- {{area_3}} (e.g., Code organization)
+
+{if_existing_context}
+**Existing Context:** Found {{sections}} sections already defined. We can update or add to these.
+{/if_existing_context}
+
+Ready to create/update your project context. This will help AI agents implement code consistently with your project's standards.
+
+[C] Continue to context generation"
+
+**HALT — wait for user selection before proceeding.**
+
+## SUCCESS METRICS:
+
+✅ Existing project context properly detected and handled
+✅ Technology stack accurately identified with versions
+✅ Critical implementation patterns discovered
+✅ Project context document properly initialized
+✅ Discovery findings clearly presented to user
+✅ User ready to proceed with context generation
+
+## FAILURE MODES:
+
+❌ Not checking for existing project context before creating new one
+❌ Missing critical technology versions or configurations
+❌ Overlooking important coding patterns or conventions
+❌ Not initializing frontmatter properly
+❌ Not presenting clear discovery summary to user
+
+## NEXT STEP:
+
+After user selects [C] to continue, load `./step-02-generate.md` to collaboratively generate the specific project context rules.
+
+Remember: Do NOT proceed to step-02 until user explicitly selects [C] from the menu and discovery is confirmed and the initial file has been written as directed in this discovery step!
diff --git a/.claude/skills/bmad-generate-project-context/steps/step-02-generate.md b/.claude/skills/bmad-generate-project-context/steps/step-02-generate.md
new file mode 100644
index 0000000..2bc33c8
--- /dev/null
+++ b/.claude/skills/bmad-generate-project-context/steps/step-02-generate.md
@@ -0,0 +1,321 @@
+# Step 2: Context Rules Generation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- ✅ ALWAYS treat this as collaborative discovery between technical peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on unobvious rules that AI agents need to be reminded of
+- 🎯 KEEP CONTENT LEAN - optimize for LLM context efficiency
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 📝 Focus on specific, actionable rules rather than general advice
+- ⚠️ Present A/P/C menu after each major rule category
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update frontmatter with completed sections
+- 🚫 FORBIDDEN to load next step until all sections are complete
+
+## COLLABORATION MENUS (A/P/C):
+
+This step will generate content and present choices for each rule category:
+
+- **A (Advanced Elicitation)**: Use discovery protocols to explore nuanced implementation rules
+- **P (Party Mode)**: Bring multiple perspectives to identify critical edge cases
+- **C (Continue)**: Save the current rules and proceed to next category
+
+## PROTOCOL INTEGRATION:
+
+- When 'A' selected: Invoke the `bmad-advanced-elicitation` skill
+- When 'P' selected: Invoke the `bmad-party-mode` skill
+- PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
+- User accepts/rejects protocol changes before proceeding
+
+## CONTEXT BOUNDARIES:
+
+- Discovery results from step-1 are available
+- Technology stack and existing patterns are identified
+- Focus on rules that prevent implementation mistakes
+- Prioritize unobvious details that AI agents might miss
+
+## YOUR TASK:
+
+Collaboratively generate specific, critical rules that AI agents must follow when implementing code in this project.
+
+## CONTEXT GENERATION SEQUENCE:
+
+### 1. Technology Stack & Versions
+
+Document the exact technology stack from discovery:
+
+**Core Technologies:**
+Based on user skill level, present findings:
+
+**Expert Mode:**
+"Technology stack from your architecture and package files:
+{{exact_technologies_with_versions}}
+
+Any critical version constraints I should document for agents?"
+
+**Intermediate Mode:**
+"I found your technology stack:
+
+**Core Technologies:**
+{{main_technologies_with_versions}}
+
+**Key Dependencies:**
+{{important_dependencies_with_versions}}
+
+Are there any version constraints or compatibility notes agents should know about?"
+
+**Beginner Mode:**
+"Here are the technologies you're using:
+
+**Main Technologies:**
+{{friendly_description_of_tech_stack}}
+
+**Important Notes:**
+{{key_things_agents_need_to_know_about_versions}}
+
+Should I document any special version rules or compatibility requirements?"
+
+### 2. Language-Specific Rules
+
+Focus on unobvious language patterns agents might miss:
+
+**TypeScript/JavaScript Rules:**
+"Based on your codebase, I notice some specific patterns:
+
+**Configuration Requirements:**
+{{typescript_config_rules}}
+
+**Import/Export Patterns:**
+{{import_export_conventions}}
+
+**Error Handling Patterns:**
+{{error_handling_requirements}}
+
+Are these patterns correct? Any other language-specific rules agents should follow?"
+
+**Python/Ruby/Other Language Rules:**
+Adapt to the actual language in use with similar focused questions.
+
+### 3. Framework-Specific Rules
+
+Document framework-specific patterns:
+
+**React Rules (if applicable):**
+"For React development, I see these patterns:
+
+**Hooks Usage:**
+{{hooks_usage_patterns}}
+
+**Component Structure:**
+{{component_organization_rules}}
+
+**State Management:**
+{{state_management_patterns}}
+
+**Performance Rules:**
+{{performance_optimization_requirements}}
+
+Should I add any other React-specific rules?"
+
+**Other Framework Rules:**
+Adapt for Vue, Angular, Next.js, Express, etc.
+
+### 4. Testing Rules
+
+Focus on testing patterns that ensure consistency:
+
+**Test Structure Rules:**
+"Your testing setup shows these patterns:
+
+**Test Organization:**
+{{test_file_organization}}
+
+**Mock Usage:**
+{{mock_patterns_and_conventions}}
+
+**Test Coverage Requirements:**
+{{coverage_expectations}}
+
+**Integration vs Unit Test Rules:**
+{{test_boundary_patterns}}
+
+Are there testing rules agents should always follow?"
+
+### 5. Code Quality & Style Rules
+
+Document critical style and quality rules:
+
+**Linting/Formatting:**
+"Your code style configuration requires:
+
+**ESLint/Prettier Rules:**
+{{specific_linting_rules}}
+
+**Code Organization:**
+{{file_and_folder_structure_rules}}
+
+**Naming Conventions:**
+{{naming_patterns_agents_must_follow}}
+
+**Documentation Requirements:**
+{{comment_and_documentation_patterns}}
+
+Any additional code quality rules?"
+
+### 6. Development Workflow Rules
+
+Document workflow patterns that affect implementation:
+
+**Git/Repository Rules:**
+"Your project uses these patterns:
+
+**Branch Naming:**
+{{branch_naming_conventions}}
+
+**Commit Message Format:**
+{{commit_message_patterns}}
+
+**PR Requirements:**
+{{pull_request_checklist}}
+
+**Deployment Patterns:**
+{{deployment_considerations}}
+
+Should I document any other workflow rules?"
+
+### 7. Critical Don't-Miss Rules
+
+Identify rules that prevent common mistakes:
+
+**Anti-Patterns to Avoid:**
+"Based on your codebase, here are critical things agents must NOT do:
+
+{{critical_anti_patterns_with_examples}}
+
+**Edge Cases:**
+{{specific_edge_cases_agents_should_handle}}
+
+**Security Rules:**
+{{security_considerations_agents_must_follow}}
+
+**Performance Gotchas:**
+{{performance_patterns_to_avoid}}
+
+Are there other 'gotchas' agents should know about?"
+
+### 8. Generate Context Content
+
+For each category, prepare lean content for the project context file:
+
+#### Content Structure:
+
+```markdown
+## Technology Stack & Versions
+
+{{concise_technology_list_with_exact_versions}}
+
+## Critical Implementation Rules
+
+### Language-Specific Rules
+
+{{bullet_points_of_critical_language_rules}}
+
+### Framework-Specific Rules
+
+{{bullet_points_of_framework_patterns}}
+
+### Testing Rules
+
+{{bullet_points_of_testing_requirements}}
+
+### Code Quality & Style Rules
+
+{{bullet_points_of_style_and_quality_rules}}
+
+### Development Workflow Rules
+
+{{bullet_points_of_workflow_patterns}}
+
+### Critical Don't-Miss Rules
+
+{{bullet_points_of_anti_patterns_and_edge_cases}}
+```
+
+### 9. Present Content and Menu
+
+After each category, show the generated rules and present choices:
+
+"I've drafted the {{category_name}} rules for your project context.
+
+**Here's what I'll add:**
+
+[Show the complete markdown content for this category]
+
+**What would you like to do?**
+[A] Advanced Elicitation - Explore nuanced rules for this category
+[P] Party Mode - Review from different implementation perspectives
+[C] Continue - Save these rules and move to next category"
+
+**HALT — wait for user selection before proceeding.**
+
+### 10. Handle Menu Selection
+
+#### If 'A' (Advanced Elicitation):
+
+- Invoke the `bmad-advanced-elicitation` skill with current category rules
+- Process enhanced rules that come back
+- Ask user: "Accept these enhanced rules for {{category}}? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'P' (Party Mode):
+
+- Invoke the `bmad-party-mode` skill with category rules context
+- Process collaborative insights on implementation patterns
+- Ask user: "Accept these changes to {{category}} rules? (y/n)"
+- If yes: Update content, then return to A/P/C menu
+- If no: Keep original content, then return to A/P/C menu
+
+#### If 'C' (Continue):
+
+- Save the current category content to project context file
+- Update frontmatter: `sections_completed: [...]`
+- Proceed to next category or step-03 if complete
+
+## APPEND TO PROJECT CONTEXT:
+
+When user selects 'C' for a category, append the content directly to `{output_folder}/project-context.md` using the structure from step 8.
+
+## SUCCESS METRICS:
+
+✅ All critical technology versions accurately documented
+✅ Language-specific rules cover unobvious patterns
+✅ Framework rules capture project-specific conventions
+✅ Testing rules ensure consistent test quality
+✅ Code quality rules maintain project standards
+✅ Workflow rules prevent implementation conflicts
+✅ Content is lean and optimized for LLM context
+✅ A/P/C menu presented and handled correctly for each category
+
+## FAILURE MODES:
+
+❌ Including obvious rules that agents already know
+❌ Making content too verbose for LLM context efficiency
+❌ Missing critical anti-patterns or edge cases
+❌ Not getting user validation for each rule category
+❌ Not documenting exact versions and configurations
+❌ Not presenting A/P/C menu after content generation
+
+## NEXT STEP:
+
+After completing all rule categories and user selects 'C' for the final category, load `./step-03-complete.md` to finalize the project context file.
+
+Remember: Do NOT proceed to step-03 until all categories are complete and user explicitly selects 'C' for each!
diff --git a/.claude/skills/bmad-generate-project-context/steps/step-03-complete.md b/.claude/skills/bmad-generate-project-context/steps/step-03-complete.md
new file mode 100644
index 0000000..85dd4db
--- /dev/null
+++ b/.claude/skills/bmad-generate-project-context/steps/step-03-complete.md
@@ -0,0 +1,278 @@
+# Step 3: Context Completion & Finalization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- ✅ ALWAYS treat this as collaborative completion between technical peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on finalizing a lean, LLM-optimized project context
+- 🎯 ENSURE all critical rules are captured and actionable
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 📝 Review and optimize content for LLM context efficiency
+- 📖 Update frontmatter with completion status
+- 🚫 NO MORE STEPS - this is the final step
+
+## CONTEXT BOUNDARIES:
+
+- All rule categories from step-2 are complete
+- Technology stack and versions are documented
+- Focus on final review, optimization, and completion
+- Ensure the context file is ready for AI agent consumption
+
+## YOUR TASK:
+
+Complete the project context file, optimize it for LLM efficiency, and provide guidance for usage and maintenance.
+
+## COMPLETION SEQUENCE:
+
+### 1. Review Complete Context File
+
+Read the entire project context file and analyze:
+
+**Content Analysis:**
+
+- Total length and readability for LLMs
+- Clarity and specificity of rules
+- Coverage of all critical areas
+- Actionability of each rule
+
+**Structure Analysis:**
+
+- Logical organization of sections
+- Consistency of formatting
+- Absence of redundant or obvious information
+- Optimization for quick scanning
+
+### 2. Optimize for LLM Context
+
+Ensure the file is lean and efficient:
+
+**Content Optimization:**
+
+- Remove any redundant rules or obvious information
+- Combine related rules into concise bullet points
+- Use specific, actionable language
+- Ensure each rule provides unique value
+
+**Formatting Optimization:**
+
+- Use consistent markdown formatting
+- Implement clear section hierarchy
+- Ensure scannability with strategic use of bolding
+- Maintain readability while maximizing information density
+
+### 3. Final Content Structure
+
+Ensure the final structure follows this optimized format:
+
+```markdown
+# Project Context for AI Agents
+
+_This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss._
+
+---
+
+## Technology Stack & Versions
+
+{{concise_technology_list}}
+
+## Critical Implementation Rules
+
+### Language-Specific Rules
+
+{{specific_language_rules}}
+
+### Framework-Specific Rules
+
+{{framework_patterns}}
+
+### Testing Rules
+
+{{testing_requirements}}
+
+### Code Quality & Style Rules
+
+{{style_and_quality_patterns}}
+
+### Development Workflow Rules
+
+{{workflow_patterns}}
+
+### Critical Don't-Miss Rules
+
+{{anti_patterns_and_edge_cases}}
+
+---
+
+## Usage Guidelines
+
+**For AI Agents:**
+
+- Read this file before implementing any code
+- Follow ALL rules exactly as documented
+- When in doubt, prefer the more restrictive option
+- Update this file if new patterns emerge
+
+**For Humans:**
+
+- Keep this file lean and focused on agent needs
+- Update when technology stack changes
+- Review quarterly for outdated rules
+- Remove rules that become obvious over time
+
+Last Updated: {{date}}
+```
+
+### 4. Present Completion Summary
+
+Based on user skill level, present the completion:
+
+**Expert Mode:**
+"Project context complete. Optimized for LLM consumption with {{rule_count}} critical rules across {{section_count}} sections.
+
+File saved to: `{output_folder}/project-context.md`
+
+Ready for AI agent integration."
+
+**Intermediate Mode:**
+"Your project context is complete and optimized for AI agents!
+
+**What we created:**
+
+- {{rule_count}} critical implementation rules
+- Technology stack with exact versions
+- Framework-specific patterns and conventions
+- Testing and quality guidelines
+- Workflow and anti-pattern rules
+
+**Key benefits:**
+
+- AI agents will implement consistently with your standards
+- Reduced context switching and implementation errors
+- Clear guidance for unobvious project requirements
+
+**Next steps:**
+
+- AI agents should read this file before implementing
+- Update as your project evolves
+- Review periodically for optimization"
+
+**Beginner Mode:**
+"Excellent! Your project context guide is ready! 🎉
+
+**What this does:**
+Think of this as a 'rules of the road' guide for AI agents working on your project. It ensures they all follow the same patterns and avoid common mistakes.
+
+**What's included:**
+
+- Exact technology versions to use
+- Critical coding rules they might miss
+- Testing and quality standards
+- Workflow patterns to follow
+
+**How AI agents use it:**
+They read this file before writing any code, ensuring everything they create follows your project's standards perfectly.
+
+Your project context is saved and ready to help agents implement consistently!"
+
+### 5. Final File Updates
+
+Update the project context file with completion information:
+
+**Frontmatter Update:**
+
+```yaml
+---
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+sections_completed:
+  ['technology_stack', 'language_rules', 'framework_rules', 'testing_rules', 'quality_rules', 'workflow_rules', 'anti_patterns']
+status: 'complete'
+rule_count: { { total_rules } }
+optimized_for_llm: true
+---
+```
+
+**Add Usage Section:**
+Append the usage guidelines from step 3 to complete the document.
+
+### 6. Completion Validation
+
+Final checks before completion:
+
+**Content Validation:**
+✅ All critical technology versions documented
+✅ Language-specific rules are specific and actionable
+✅ Framework rules cover project conventions
+✅ Testing rules ensure consistency
+✅ Code quality rules maintain standards
+✅ Workflow rules prevent conflicts
+✅ Anti-pattern rules prevent common mistakes
+
+**Format Validation:**
+✅ Content is lean and optimized for LLMs
+✅ Structure is logical and scannable
+✅ No redundant or obvious information
+✅ Consistent formatting throughout
+
+### 7. Completion Message
+
+Present final completion to user:
+
+"✅ **Project Context Generation Complete!**
+
+Your optimized project context file is ready at:
+`{output_folder}/project-context.md`
+
+**📊 Context Summary:**
+
+- {{rule_count}} critical rules for AI agents
+- {{section_count}} comprehensive sections
+- Optimized for LLM context efficiency
+- Ready for immediate agent integration
+
+**🎯 Key Benefits:**
+
+- Consistent implementation across all AI agents
+- Reduced common mistakes and edge cases
+- Clear guidance for project-specific patterns
+- Minimal LLM context usage
+
+**📋 Next Steps:**
+
+1. AI agents will automatically read this file when implementing
+2. Update this file when your technology stack or patterns evolve
+3. Review quarterly to optimize and remove outdated rules
+
+Your project context will help ensure high-quality, consistent implementation across all development work. Great work capturing your project's critical implementation requirements!"
+
+## SUCCESS METRICS:
+
+✅ Complete project context file with all critical rules
+✅ Content optimized for LLM context efficiency
+✅ All technology versions and patterns documented
+✅ File structure is logical and scannable
+✅ Usage guidelines included for agents and humans
+✅ Frontmatter properly updated with completion status
+✅ User provided with clear next steps and benefits
+
+## FAILURE MODES:
+
+❌ Final content is too verbose for LLM consumption
+❌ Missing critical implementation rules or patterns
+❌ Not optimizing content for agent readability
+❌ Not providing clear usage guidelines
+❌ Frontmatter not properly updated
+❌ Not validating file completion before ending
+
+## WORKFLOW COMPLETE:
+
+This is the final step of the Generate Project Context workflow. The user now has a comprehensive, optimized project context file that will ensure consistent, high-quality implementation across all AI agents working on the project.
+
+The project context file serves as the critical "rules of the road" that agents need to implement code consistently with the project's standards and patterns.
diff --git a/.claude/skills/bmad-generate-project-context/workflow.md b/.claude/skills/bmad-generate-project-context/workflow.md
new file mode 100644
index 0000000..590eeb5
--- /dev/null
+++ b/.claude/skills/bmad-generate-project-context/workflow.md
@@ -0,0 +1,39 @@
+# Generate Project Context Workflow
+
+**Goal:** Create a concise, optimized `project-context.md` file containing critical rules, patterns, and guidelines that AI agents must follow when implementing code. This file focuses on unobvious details that LLMs need to be reminded of.
+
+**Your Role:** You are a technical facilitator working with a peer to capture the essential implementation rules that will ensure consistent, high-quality code generation across all AI agents working on the project.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- Document state tracked in frontmatter
+- Focus on lean, LLM-optimized content generation
+- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
+
+---
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+- `output_file` = `{output_folder}/project-context.md`
+
+    EXECUTION
+
+Load and execute `./steps/step-01-discover.md` to begin the workflow.
+
+**Note:** Input document discovery and initialization protocols are handled in step-01-discover.md.
diff --git a/.claude/skills/bmad-help/SKILL.md b/.claude/skills/bmad-help/SKILL.md
new file mode 100644
index 0000000..e829543
--- /dev/null
+++ b/.claude/skills/bmad-help/SKILL.md
@@ -0,0 +1,75 @@
+---
+name: bmad-help
+description: 'Analyzes current state and user query to answer BMad questions or recommend the next skill(s) to use. Use when user asks for help, bmad help, what to do next, or what to start with in BMad.'
+---
+
+# BMad Help
+
+## Purpose
+
+Help the user understand where they are in their BMad workflow and what to do next, and also answer broader questions when asked that could be augmented with remote sources such as module documentation sources.
+
+## Desired Outcomes
+
+When this skill completes, the user should:
+
+1. **Know where they are** — which module and phase they're in, what's already been completed
+2. **Know what to do next** — the next recommended and/or required step, with clear reasoning
+3. **Know how to invoke it** — skill name, menu code, action context, and any args that shortcut the conversation
+4. **Get offered a quick start** — when a single skill is the clear next step, offer to run it for the user right now rather than just listing it
+5. **Feel oriented, not overwhelmed** — surface only what's relevant to their current position; don't dump the entire catalog
+6. **Get answers to general questions** — when the question doesn't map to a specific skill, use the module's registered documentation to give a grounded answer
+
+## Data Sources
+
+- **Catalog**: `{project-root}/_bmad/_config/bmad-help.csv` — assembled manifest of all installed module skills
+- **Config**: `config.yaml` and `user-config.yaml` files in `{project-root}/_bmad/` and its subfolders — resolve `output-location` variables, provide `communication_language` and `project_knowledge`
+- **Artifacts**: Files matching `outputs` patterns at resolved `output-location` paths reveal which steps are possibly completed; their content may also provide grounding context for recommendations
+- **Project knowledge**: If `project_knowledge` resolves to an existing path, read it for grounding context. Never fabricate project-specific details.
+- **Module docs**: Rows with `_meta` in the `skill` column carry a URL or path in `output-location` pointing to the module's documentation (e.g., llms.txt). Fetch and use these to answer general questions about that module.
+
+## CSV Interpretation
+
+The catalog uses this format:
+
+```
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+```
+
+**Phases** determine the high-level flow:
+- `anytime` — available regardless of workflow state
+- Numbered phases (`1-analysis`, `2-planning`, etc.) flow in order; naming varies by module
+
+**Dependencies** determine ordering within and across phases:
+- `after` — skills that should ideally complete before this one
+- `before` — skills that should run after this one
+- Format: `skill-name` for single-action skills, `skill-name:action` for multi-action skills
+
+**Required gates**:
+- `required=true` items must complete before the user can meaningfully proceed to later phases
+- A phase with no required items is entirely optional — recommend it but be clear about what's actually required next
+
+**Completion detection**:
+- Search resolved output paths for `outputs` patterns
+- Fuzzy-match found files to catalog rows
+- User may also state completion explicitly, or it may be evident from the current conversation
+
+**Descriptions carry routing context** — some contain cycle info and alternate paths (e.g., "back to DS if fixes needed"). Read them as navigation hints, not just display text.
+
+## Response Format
+
+For each recommended item, present:
+- `[menu-code]` **Display name** — e.g., "[CP] Create PRD"
+- Skill name in backticks — e.g., `bmad-create-prd`
+- For multi-action skills: action invocation context — e.g., "tech-writer lets create a mermaid diagram!"
+- Description if present in CSV; otherwise your existing knowledge of the skill suffices
+- Args if available
+
+**Ordering**: Show optional items first, then the next required item. Make it clear which is which.
+
+## Constraints
+
+- Present all output in `{communication_language}`
+- Recommend running each skill in a **fresh context window**
+- Match the user's tone — conversational when they're casual, structured when they want specifics
+- If the active module is ambiguous, retrieve all meta rows remote sources to find relevant info also to help answer their question
diff --git a/.claude/skills/bmad-index-docs/SKILL.md b/.claude/skills/bmad-index-docs/SKILL.md
new file mode 100644
index 0000000..c92935b
--- /dev/null
+++ b/.claude/skills/bmad-index-docs/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: bmad-index-docs
+description: 'Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder'
+---
+
+# Index Docs
+
+**Goal:** Generate or update an index.md to reference all docs in a target folder.
+
+
+## EXECUTION
+
+### Step 1: Scan Directory
+
+- List all files and subdirectories in the target location
+
+### Step 2: Group Content
+
+- Organize files by type, purpose, or subdirectory
+
+### Step 3: Generate Descriptions
+
+- Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the filename
+
+### Step 4: Create/Update Index
+
+- Write or update index.md with organized file listings
+
+
+## OUTPUT FORMAT
+
+```markdown
+# Directory Index
+
+## Files
+
+- **[filename.ext](./filename.ext)** - Brief description
+- **[another-file.ext](./another-file.ext)** - Brief description
+
+## Subdirectories
+
+### subfolder/
+
+- **[file1.ext](./subfolder/file1.ext)** - Brief description
+- **[file2.ext](./subfolder/file2.ext)** - Brief description
+
+### another-folder/
+
+- **[file3.ext](./another-folder/file3.ext)** - Brief description
+```
+
+
+## HALT CONDITIONS
+
+- HALT if target directory does not exist or is inaccessible
+- HALT if user does not have write permissions to create index.md
+
+
+## VALIDATION
+
+- Use relative paths starting with ./
+- Group similar files together
+- Read file contents to generate accurate descriptions - don't guess from filenames
+- Keep descriptions concise but informative (3-10 words)
+- Sort alphabetically within groups
+- Skip hidden files (starting with .) unless specified
diff --git a/.claude/skills/bmad-market-research/SKILL.md b/.claude/skills/bmad-market-research/SKILL.md
new file mode 100644
index 0000000..bf50985
--- /dev/null
+++ b/.claude/skills/bmad-market-research/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-market-research
+description: 'Conduct market research on competition and customers. Use when the user says they need market research'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-market-research/research.template.md b/.claude/skills/bmad-market-research/research.template.md
new file mode 100644
index 0000000..1d99524
--- /dev/null
+++ b/.claude/skills/bmad-market-research/research.template.md
@@ -0,0 +1,29 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'research'
+lastStep: 1
+research_type: '{{research_type}}'
+research_topic: '{{research_topic}}'
+research_goals: '{{research_goals}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+web_research_enabled: true
+source_verification: true
+---
+
+# Research Report: {{research_type}}
+
+**Date:** {{date}}
+**Author:** {{user_name}}
+**Research Type:** {{research_type}}
+
+---
+
+## Research Overview
+
+[Research overview and methodology will be appended here]
+
+---
+
+<!-- Content will be appended sequentially through research workflow steps -->
diff --git a/.claude/skills/bmad-market-research/steps/step-01-init.md b/.claude/skills/bmad-market-research/steps/step-01-init.md
new file mode 100644
index 0000000..4cf6276
--- /dev/null
+++ b/.claude/skills/bmad-market-research/steps/step-01-init.md
@@ -0,0 +1,184 @@
+# Market Research Step 1: Market Research Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate research content in init step
+- ✅ ALWAYS confirm understanding of user's research goals
+- 📋 YOU ARE A MARKET RESEARCH FACILITATOR, not content generator
+- 💬 FOCUS on clarifying scope and approach
+- 🔍 NO WEB RESEARCH in init - that's for later steps
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete research
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Confirm research understanding before proceeding
+- ⚠️ Present [C] continue option after scope clarification
+- 💾 Write initial scope document immediately
+- 📖 Update frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from main workflow discovery are available
+- Research type = "market" is already set
+- **Research topic = "{{research_topic}}"** - discovered from initial discussion
+- **Research goals = "{{research_goals}}"** - captured from initial discussion
+- Focus on market research scope clarification
+- Web search capabilities are enabled for later steps
+
+## YOUR TASK:
+
+Initialize market research by confirming understanding of {{research_topic}} and establishing clear research scope.
+
+## MARKET RESEARCH INITIALIZATION:
+
+### 1. Confirm Research Understanding
+
+**INITIALIZE - DO NOT RESEARCH YET**
+
+Start with research confirmation:
+"I understand you want to conduct **market research** for **{{research_topic}}** with these goals: {{research_goals}}
+
+**My Understanding of Your Research Needs:**
+
+- **Research Topic**: {{research_topic}}
+- **Research Goals**: {{research_goals}}
+- **Research Type**: Market Research
+- **Approach**: Comprehensive market analysis with source verification
+
+**Market Research Areas We'll Cover:**
+
+- Market size, growth dynamics, and trends
+- Customer insights and behavior analysis
+- Competitive landscape and positioning
+- Strategic recommendations and implementation guidance
+
+**Does this accurately capture what you're looking for?**"
+
+### 2. Refine Research Scope
+
+Gather any clarifications needed:
+
+#### Scope Clarification Questions:
+
+- "Are there specific customer segments or aspects of {{research_topic}} we should prioritize?"
+- "Should we focus on specific geographic regions or global market?"
+- "Is this for market entry, expansion, product development, or other business purpose?"
+- "Any competitors or market segments you specifically want us to analyze?"
+
+### 3. Document Initial Scope
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Write initial research scope to document:
+
+```markdown
+# Market Research: {{research_topic}}
+
+## Research Initialization
+
+### Research Understanding Confirmed
+
+**Topic**: {{research_topic}}
+**Goals**: {{research_goals}}
+**Research Type**: Market Research
+**Date**: {{date}}
+
+### Research Scope
+
+**Market Analysis Focus Areas:**
+
+- Market size, growth projections, and dynamics
+- Customer segments, behavior patterns, and insights
+- Competitive landscape and positioning analysis
+- Strategic recommendations and implementation guidance
+
+**Research Methodology:**
+
+- Current web data with source verification
+- Multiple independent sources for critical claims
+- Confidence level assessment for uncertain data
+- Comprehensive coverage with no critical gaps
+
+### Next Steps
+
+**Research Workflow:**
+
+1. ✅ Initialization and scope setting (current step)
+2. Customer Insights and Behavior Analysis
+3. Competitive Landscape Analysis
+4. Strategic Synthesis and Recommendations
+
+**Research Status**: Scope confirmed, ready to proceed with detailed market analysis
+```
+
+### 4. Present Confirmation and Continue Option
+
+Show initial scope document and present continue option:
+"I've documented our understanding and initial scope for **{{research_topic}}** market research.
+
+**What I've established:**
+
+- Research topic and goals confirmed
+- Market analysis focus areas defined
+- Research methodology verification
+- Clear workflow progression
+
+**Document Status:** Initial scope written to research file for your review
+
+**Ready to begin detailed market research?**
+[C] Continue - Confirm scope and proceed to customer insights analysis
+[Modify] Suggest changes to research scope before proceeding
+
+**HALT — wait for user response before proceeding.**
+
+### 5. Handle User Response
+
+#### If 'C' (Continue):
+
+- Update frontmatter: `stepsCompleted: [1]`
+- Add confirmation note to document: "Scope confirmed by user on {{date}}"
+- Load: `./step-02-customer-behavior.md`
+
+#### If 'Modify':
+
+- Gather user changes to scope
+- Update document with modifications
+- Re-present updated scope for confirmation
+
+## SUCCESS METRICS:
+
+✅ Research topic and goals accurately understood
+✅ Market research scope clearly defined
+✅ Initial scope document written immediately
+✅ User opportunity to review and modify scope
+✅ [C] continue option presented and handled correctly
+✅ Document properly updated with scope confirmation
+
+## FAILURE MODES:
+
+❌ Not confirming understanding of research topic and goals
+❌ Generating research content instead of just scope clarification
+❌ Not writing initial scope document to file
+❌ Not providing opportunity for user to modify scope
+❌ Proceeding to next step without user confirmation
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor research decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## INITIALIZATION PRINCIPLES:
+
+This step ensures:
+
+- Clear mutual understanding of research objectives
+- Well-defined research scope and approach
+- Immediate documentation for user review
+- User control over research direction before detailed work begins
+
+## NEXT STEP:
+
+After user confirmation and scope finalization, load `./step-02-customer-behavior.md` to begin detailed market research with customer insights analysis.
+
+Remember: Init steps confirm understanding and scope, not generate research content!
diff --git a/.claude/skills/bmad-market-research/steps/step-02-customer-behavior.md b/.claude/skills/bmad-market-research/steps/step-02-customer-behavior.md
new file mode 100644
index 0000000..810e22d
--- /dev/null
+++ b/.claude/skills/bmad-market-research/steps/step-02-customer-behavior.md
@@ -0,0 +1,239 @@
+# Market Research Step 2: Customer Behavior and Segments
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A CUSTOMER BEHAVIOR ANALYST, not content generator
+- 💬 FOCUS on customer behavior patterns and demographic analysis
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete research
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after customer behavior content generation
+- 📝 WRITE CUSTOMER BEHAVIOR ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from step-01 are available
+- Focus on customer behavior patterns and demographic analysis
+- Web search capabilities with source verification are enabled
+- Previous step confirmed research scope and goals
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+
+## YOUR TASK:
+
+Conduct customer behavior and segment analysis with emphasis on patterns and demographics.
+
+## CUSTOMER BEHAVIOR ANALYSIS SEQUENCE:
+
+### 1. Begin Customer Behavior Analysis
+
+**UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different customer behavior areas simultaneously and thoroughly.
+
+Start with customer behavior research approach:
+"Now I'll conduct **customer behavior analysis** for **{{research_topic}}** to understand customer patterns.
+
+**Customer Behavior Focus:**
+
+- Customer behavior patterns and preferences
+- Demographic profiles and segmentation
+- Psychographic characteristics and values
+- Behavior drivers and influences
+- Customer interaction patterns and engagement
+
+**Let me search for current customer behavior insights.**"
+
+### 2. Parallel Customer Behavior Research Execution
+
+**Execute multiple web searches simultaneously:**
+
+Search the web: "{{research_topic}} customer behavior patterns"
+Search the web: "{{research_topic}} customer demographics"
+Search the web: "{{research_topic}} psychographic profiles"
+Search the web: "{{research_topic}} customer behavior drivers"
+
+**Analysis approach:**
+
+- Look for customer behavior studies and research reports
+- Search for demographic segmentation and analysis
+- Research psychographic profiling and value systems
+- Analyze behavior drivers and influencing factors
+- Study customer interaction and engagement patterns
+
+### 3. Analyze and Aggregate Results
+
+**Collect and analyze findings from all parallel searches:**
+
+"After executing comprehensive parallel web searches, let me analyze and aggregate customer behavior findings:
+
+**Research Coverage:**
+
+- Customer behavior patterns and preferences
+- Demographic profiles and segmentation
+- Psychographic characteristics and values
+- Behavior drivers and influences
+- Customer interaction patterns and engagement
+
+**Cross-Behavior Analysis:**
+[Identify patterns connecting demographics, psychographics, and behaviors]
+
+**Quality Assessment:**
+[Overall confidence levels and research gaps identified]"
+
+### 4. Generate Customer Behavior Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare customer behavior analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Customer Behavior and Segments
+
+### Customer Behavior Patterns
+
+[Customer behavior patterns analysis with source citations]
+_Behavior Drivers: [Key motivations and patterns from web search]_
+_Interaction Preferences: [Customer engagement and interaction patterns]_
+_Decision Habits: [How customers typically make decisions]_
+_Source: [URL]_
+
+### Demographic Segmentation
+
+[Demographic analysis with source citations]
+_Age Demographics: [Age groups and preferences]_
+_Income Levels: [Income segments and purchasing behavior]_
+_Geographic Distribution: [Regional/city differences]_
+_Education Levels: [Education impact on behavior]_
+_Source: [URL]_
+
+### Psychographic Profiles
+
+[Psychographic analysis with source citations]
+_Values and Beliefs: [Core values driving customer behavior]_
+_Lifestyle Preferences: [Lifestyle choices and behaviors]_
+_Attitudes and Opinions: [Customer attitudes toward products/services]_
+_Personality Traits: [Personality influences on behavior]_
+_Source: [URL]_
+
+### Customer Segment Profiles
+
+[Detailed customer segment profiles with source citations]
+_Segment 1: [Detailed profile including demographics, psychographics, behavior]_
+_Segment 2: [Detailed profile including demographics, psychographics, behavior]_
+_Segment 3: [Detailed profile including demographics, psychographics, behavior]_
+_Source: [URL]_
+
+### Behavior Drivers and Influences
+
+[Behavior drivers analysis with source citations]
+_Emotional Drivers: [Emotional factors influencing behavior]_
+_Rational Drivers: [Logical decision factors]_
+_Social Influences: [Social and peer influences]_
+_Economic Influences: [Economic factors affecting behavior]_
+_Source: [URL]_
+
+### Customer Interaction Patterns
+
+[Customer interaction analysis with source citations]
+_Research and Discovery: [How customers find and research options]_
+_Purchase Decision Process: [Steps in purchase decision making]_
+_Post-Purchase Behavior: [After-purchase engagement patterns]_
+_Loyalty and Retention: [Factors driving customer loyalty]_
+_Source: [URL]_
+```
+
+### 5. Present Analysis and Continue Option
+
+**Show analysis and present continue option:**
+
+"I've completed **customer behavior analysis** for {{research_topic}}, focusing on customer patterns.
+
+**Key Customer Behavior Findings:**
+
+- Customer behavior patterns clearly identified with drivers
+- Demographic segmentation thoroughly analyzed
+- Psychographic profiles mapped and documented
+- Customer interaction patterns captured
+- Multiple sources verified for critical insights
+
+**Ready to proceed to customer pain points?**
+[C] Continue - Save this to document and proceed to pain points analysis
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2]`
+- Load: `./step-03-customer-pain-points.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 4. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Customer behavior patterns identified with current citations
+✅ Demographic segmentation thoroughly analyzed
+✅ Psychographic profiles clearly documented
+✅ Customer interaction patterns captured
+✅ Multiple sources verified for critical insights
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (customer pain points)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical customer behavior patterns
+❌ Incomplete demographic segmentation analysis
+❌ Missing psychographic profile documentation
+❌ Not writing content immediately to document
+❌ Not presenting [C] continue option after content generation
+❌ Not routing to customer pain points analysis step
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor research decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## CUSTOMER BEHAVIOR RESEARCH PROTOCOLS:
+
+- Research customer behavior studies and market research
+- Use demographic data from authoritative sources
+- Research psychographic profiling and value systems
+- Analyze customer interaction and engagement patterns
+- Focus on current behavior data and trends
+- Present conflicting information when sources disagree
+- Apply confidence levels appropriately
+
+## BEHAVIOR ANALYSIS STANDARDS:
+
+- Always cite URLs for web search results
+- Use authoritative customer research sources
+- Note data currency and potential limitations
+- Present multiple perspectives when sources conflict
+- Apply confidence levels to uncertain data
+- Focus on actionable customer insights
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-03-customer-pain-points.md` to analyze customer pain points, challenges, and unmet needs for {{research_topic}}.
+
+Remember: Always write research content to document immediately and emphasize current customer data with rigorous source verification!
diff --git a/.claude/skills/bmad-market-research/steps/step-03-customer-pain-points.md b/.claude/skills/bmad-market-research/steps/step-03-customer-pain-points.md
new file mode 100644
index 0000000..280730c
--- /dev/null
+++ b/.claude/skills/bmad-market-research/steps/step-03-customer-pain-points.md
@@ -0,0 +1,251 @@
+# Market Research Step 3: Customer Pain Points and Needs
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A CUSTOMER NEEDS ANALYST, not content generator
+- 💬 FOCUS on customer pain points, challenges, and unmet needs
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after pain points content generation
+- 📝 WRITE CUSTOMER PAIN POINTS ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Customer behavior analysis completed in previous step
+- Focus on customer pain points, challenges, and unmet needs
+- Web search capabilities with source verification are enabled
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+
+## YOUR TASK:
+
+Conduct customer pain points and needs analysis with emphasis on challenges and frustrations.
+
+## CUSTOMER PAIN POINTS ANALYSIS SEQUENCE:
+
+### 1. Begin Customer Pain Points Analysis
+
+**UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different customer pain point areas simultaneously and thoroughly.
+
+Start with customer pain points research approach:
+"Now I'll conduct **customer pain points analysis** for **{{research_topic}}** to understand customer challenges.
+
+**Customer Pain Points Focus:**
+
+- Customer challenges and frustrations
+- Unmet needs and unaddressed problems
+- Barriers to adoption or usage
+- Service and support pain points
+- Customer satisfaction gaps
+
+**Let me search for current customer pain points insights.**"
+
+### 2. Parallel Pain Points Research Execution
+
+**Execute multiple web searches simultaneously:**
+
+Search the web: "{{research_topic}} customer pain points challenges"
+Search the web: "{{research_topic}} customer frustrations"
+Search the web: "{{research_topic}} unmet customer needs"
+Search the web: "{{research_topic}} customer barriers to adoption"
+
+**Analysis approach:**
+
+- Look for customer satisfaction surveys and reports
+- Search for customer complaints and reviews
+- Research customer support and service issues
+- Analyze barriers to customer adoption
+- Study unmet needs and market gaps
+
+### 3. Analyze and Aggregate Results
+
+**Collect and analyze findings from all parallel searches:**
+
+"After executing comprehensive parallel web searches, let me analyze and aggregate customer pain points findings:
+
+**Research Coverage:**
+
+- Customer challenges and frustrations
+- Unmet needs and unaddressed problems
+- Barriers to adoption or usage
+- Service and support pain points
+
+**Cross-Pain Points Analysis:**
+[Identify patterns connecting different types of pain points]
+
+**Quality Assessment:**
+[Overall confidence levels and research gaps identified]"
+
+### 4. Generate Customer Pain Points Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare customer pain points analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Customer Pain Points and Needs
+
+### Customer Challenges and Frustrations
+
+[Customer challenges analysis with source citations]
+_Primary Frustrations: [Major customer frustrations identified]_
+_Usage Barriers: [Barriers preventing effective usage]_
+_Service Pain Points: [Customer service and support issues]_
+_Frequency Analysis: [How often these challenges occur]_
+_Source: [URL]_
+
+### Unmet Customer Needs
+
+[Unmet needs analysis with source citations]
+_Critical Unmet Needs: [Most important unaddressed needs]_
+_Solution Gaps: [Opportunities to address unmet needs]_
+_Market Gaps: [Market opportunities from unmet needs]_
+_Priority Analysis: [Which needs are most critical]_
+_Source: [URL]_
+
+### Barriers to Adoption
+
+[Adoption barriers analysis with source citations]
+_Price Barriers: [Cost-related barriers to adoption]_
+_Technical Barriers: [Complexity or technical barriers]_
+_Trust Barriers: [Trust and credibility issues]_
+_Convenience Barriers: [Ease of use or accessibility issues]_
+_Source: [URL]_
+
+### Service and Support Pain Points
+
+[Service pain points analysis with source citations]
+_Customer Service Issues: [Common customer service problems]_
+_Support Gaps: [Areas where customer support is lacking]_
+_Communication Issues: [Communication breakdowns and frustrations]_
+_Response Time Issues: [Slow response and resolution problems]_
+_Source: [URL]_
+
+### Customer Satisfaction Gaps
+
+[Satisfaction gap analysis with source citations]
+_Expectation Gaps: [Differences between expectations and reality]_
+_Quality Gaps: [Areas where quality expectations aren't met]_
+_Value Perception Gaps: [Perceived value vs actual value]_
+_Trust and Credibility Gaps: [Trust issues affecting satisfaction]_
+_Source: [URL]_
+
+### Emotional Impact Assessment
+
+[Emotional impact analysis with source citations]
+_Frustration Levels: [Customer frustration severity assessment]_
+_Loyalty Risks: [How pain points affect customer loyalty]_
+_Reputation Impact: [Impact on brand or product reputation]_
+_Customer Retention Risks: [Risk of customer loss from pain points]_
+_Source: [URL]_
+
+### Pain Point Prioritization
+
+[Pain point prioritization with source citations]
+_High Priority Pain Points: [Most critical pain points to address]_
+_Medium Priority Pain Points: [Important but less critical pain points]_
+_Low Priority Pain Points: [Minor pain points with lower impact]_
+_Opportunity Mapping: [Pain points with highest solution opportunity]_
+_Source: [URL]_
+```
+
+### 5. Present Analysis and Continue Option
+
+**Show analysis and present continue option:**
+
+"I've completed **customer pain points analysis** for {{research_topic}}, focusing on customer challenges.
+
+**Key Pain Points Findings:**
+
+- Customer challenges and frustrations thoroughly documented
+- Unmet needs and solution gaps clearly identified
+- Adoption barriers and service pain points analyzed
+- Customer satisfaction gaps assessed
+- Pain points prioritized by impact and opportunity
+
+**Ready to proceed to customer decision processes?**
+[C] Continue - Save this to document and proceed to decision processes analysis
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2, 3]`
+- Load: `./step-04-customer-decisions.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 4. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Customer challenges and frustrations clearly documented
+✅ Unmet needs and solution gaps identified
+✅ Adoption barriers and service pain points analyzed
+✅ Customer satisfaction gaps assessed
+✅ Pain points prioritized by impact and opportunity
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (customer decisions)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical customer challenges or frustrations
+❌ Not identifying unmet needs or solution gaps
+❌ Incomplete adoption barriers analysis
+❌ Not writing content immediately to document
+❌ Not presenting [C] continue option after content generation
+❌ Not routing to customer decisions analysis step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## CUSTOMER PAIN POINTS RESEARCH PROTOCOLS:
+
+- Research customer satisfaction surveys and reviews
+- Use customer feedback and complaint data
+- Analyze customer support and service issues
+- Study barriers to customer adoption
+- Focus on current pain point data
+- Present conflicting information when sources disagree
+- Apply confidence levels appropriately
+
+## PAIN POINTS ANALYSIS STANDARDS:
+
+- Always cite URLs for web search results
+- Use authoritative customer research sources
+- Note data currency and potential limitations
+- Present multiple perspectives when sources conflict
+- Apply confidence levels to uncertain data
+- Focus on actionable pain point insights
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-04-customer-decisions.md` to analyze customer decision processes, journey mapping, and decision factors for {{research_topic}}.
+
+Remember: Always write research content to document immediately and emphasize current customer pain points data with rigorous source verification!
diff --git a/.claude/skills/bmad-market-research/steps/step-04-customer-decisions.md b/.claude/skills/bmad-market-research/steps/step-04-customer-decisions.md
new file mode 100644
index 0000000..4f0e550
--- /dev/null
+++ b/.claude/skills/bmad-market-research/steps/step-04-customer-decisions.md
@@ -0,0 +1,261 @@
+# Market Research Step 4: Customer Decisions and Journey
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A CUSTOMER DECISION ANALYST, not content generator
+- 💬 FOCUS on customer decision processes and journey mapping
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after decision processes content generation
+- 📝 WRITE CUSTOMER DECISIONS ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Customer behavior and pain points analysis completed in previous steps
+- Focus on customer decision processes and journey mapping
+- Web search capabilities with source verification are enabled
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+
+## YOUR TASK:
+
+Conduct customer decision processes and journey analysis with emphasis on decision factors and journey mapping.
+
+## CUSTOMER DECISIONS ANALYSIS SEQUENCE:
+
+### 1. Begin Customer Decisions Analysis
+
+**UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different customer decision areas simultaneously and thoroughly.
+
+Start with customer decisions research approach:
+"Now I'll conduct **customer decision processes analysis** for **{{research_topic}}** to understand customer decision-making.
+
+**Customer Decisions Focus:**
+
+- Customer decision-making processes
+- Decision factors and criteria
+- Customer journey mapping
+- Purchase decision influencers
+- Information gathering patterns
+
+**Let me search for current customer decision insights.**"
+
+### 2. Parallel Decisions Research Execution
+
+**Execute multiple web searches simultaneously:**
+
+Search the web: "{{research_topic}} customer decision process"
+Search the web: "{{research_topic}} buying criteria factors"
+Search the web: "{{research_topic}} customer journey mapping"
+Search the web: "{{research_topic}} decision influencing factors"
+
+**Analysis approach:**
+
+- Look for customer decision research studies
+- Search for buying criteria and factor analysis
+- Research customer journey mapping methodologies
+- Analyze decision influence factors and channels
+- Study information gathering and evaluation patterns
+
+### 3. Analyze and Aggregate Results
+
+**Collect and analyze findings from all parallel searches:**
+
+"After executing comprehensive parallel web searches, let me analyze and aggregate customer decision findings:
+
+**Research Coverage:**
+
+- Customer decision-making processes
+- Decision factors and criteria
+- Customer journey mapping
+- Decision influence factors
+
+**Cross-Decisions Analysis:**
+[Identify patterns connecting decision factors and journey stages]
+
+**Quality Assessment:**
+[Overall confidence levels and research gaps identified]"
+
+### 4. Generate Customer Decisions Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare customer decisions analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Customer Decision Processes and Journey
+
+### Customer Decision-Making Processes
+
+[Decision processes analysis with source citations]
+_Decision Stages: [Key stages in customer decision making]_
+_Decision Timelines: [Timeframes for different decisions]_
+_Complexity Levels: [Decision complexity assessment]_
+_Evaluation Methods: [How customers evaluate options]_
+_Source: [URL]_
+
+### Decision Factors and Criteria
+
+[Decision factors analysis with source citations]
+_Primary Decision Factors: [Most important factors in decisions]_
+_Secondary Decision Factors: [Supporting factors influencing decisions]_
+_Weighing Analysis: [How different factors are weighed]_
+_Evoluton Patterns: [How factors change over time]_
+_Source: [URL]_
+
+### Customer Journey Mapping
+
+[Journey mapping analysis with source citations]
+_Awareness Stage: [How customers become aware of {{research_topic}}]_
+_Consideration Stage: [Evaluation and comparison process]_
+_Decision Stage: [Final decision-making process]_
+_Purchase Stage: [Purchase execution and completion]_
+_Post-Purchase Stage: [Post-decision evaluation and behavior]_
+_Source: [URL]_
+
+### Touchpoint Analysis
+
+[Touchpoint analysis with source citations]
+_Digital Touchpoints: [Online and digital interaction points]_
+_Offline Touchpoints: [Physical and in-person interaction points]_
+_Information Sources: [Where customers get information]_
+_Influence Channels: [What influences customer decisions]_
+_Source: [URL]_
+
+### Information Gathering Patterns
+
+[Information patterns analysis with source citations]
+_Research Methods: [How customers research options]_
+_Information Sources Trusted: [Most trusted information sources]_
+_Research Duration: [Time spent gathering information]_
+_Evaluation Criteria: [How customers evaluate information]_
+_Source: [URL]_
+
+### Decision Influencers
+
+[Decision influencer analysis with source citations]
+_Peer Influence: [How friends and family influence decisions]_
+_Expert Influence: [How expert opinions affect decisions]_
+_Media Influence: [How media and marketing affect decisions]_
+_Social Proof Influence: [How reviews and testimonials affect decisions]_
+_Source: [URL]_
+
+### Purchase Decision Factors
+
+[Purchase decision factors analysis with source citations]
+_Immediate Purchase Drivers: [Factors triggering immediate purchase]_
+_Delayed Purchase Drivers: [Factors causing purchase delays]_
+_Brand Loyalty Factors: [Factors driving repeat purchases]_
+_Price Sensitivity: [How price affects purchase decisions]_
+_Source: [URL]_
+
+### Customer Decision Optimizations
+
+[Decision optimization analysis with source citations]
+_Friction Reduction: [Ways to make decisions easier]_
+_Trust Building: [Building customer trust in decisions]_
+_Conversion Optimization: [Optimizing decision-to-purchase rates]_
+_Loyalty Building: [Building long-term customer relationships]_
+_Source: [URL]_
+```
+
+### 5. Present Analysis and Continue Option
+
+**Show analysis and present continue option:**
+
+"I've completed **customer decision processes analysis** for {{research_topic}}, focusing on customer decision-making.
+
+**Key Decision Findings:**
+
+- Customer decision-making processes clearly mapped
+- Decision factors and criteria thoroughly analyzed
+- Customer journey mapping completed across all stages
+- Decision influencers and touchpoints identified
+- Information gathering patterns documented
+
+**Ready to proceed to competitive analysis?**
+[C] Continue - Save this to document and proceed to competitive analysis
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
+- Load: `./step-05-competitive-analysis.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 4. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Customer decision-making processes clearly mapped
+✅ Decision factors and criteria thoroughly analyzed
+✅ Customer journey mapping completed across all stages
+✅ Decision influencers and touchpoints identified
+✅ Information gathering patterns documented
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (competitive analysis)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical decision-making process stages
+❌ Not identifying key decision factors
+❌ Incomplete customer journey mapping
+❌ Not writing content immediately to document
+❌ Not presenting [C] continue option after content generation
+❌ Not routing to competitive analysis step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## CUSTOMER DECISIONS RESEARCH PROTOCOLS:
+
+- Research customer decision studies and psychology
+- Use customer journey mapping methodologies
+- Analyze buying criteria and decision factors
+- Study decision influence and touchpoint analysis
+- Focus on current decision data
+- Present conflicting information when sources disagree
+- Apply confidence levels appropriately
+
+## DECISION ANALYSIS STANDARDS:
+
+- Always cite URLs for web search results
+- Use authoritative customer decision research sources
+- Note data currency and potential limitations
+- Present multiple perspectives when sources conflict
+- Apply confidence levels to uncertain data
+- Focus on actionable decision insights
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-05-competitive-analysis.md` to analyze competitive landscape, market positioning, and competitive strategies for {{research_topic}}.
+
+Remember: Always write research content to document immediately and emphasize current customer decision data with rigorous source verification!
diff --git a/.claude/skills/bmad-market-research/steps/step-05-competitive-analysis.md b/.claude/skills/bmad-market-research/steps/step-05-competitive-analysis.md
new file mode 100644
index 0000000..868b124
--- /dev/null
+++ b/.claude/skills/bmad-market-research/steps/step-05-competitive-analysis.md
@@ -0,0 +1,173 @@
+# Market Research Step 5: Competitive Analysis
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A COMPETITIVE ANALYST, not content generator
+- 💬 FOCUS on competitive landscape and market positioning
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] complete option after competitive analysis content generation
+- 💾 ONLY save when user chooses C (Complete)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before completing workflow
+- 🚫 FORBIDDEN to complete workflow until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Focus on competitive landscape and market positioning analysis
+- Web search capabilities with source verification are enabled
+- May need to search for specific competitor information
+
+## YOUR TASK:
+
+Conduct comprehensive competitive analysis with emphasis on market positioning.
+
+## COMPETITIVE ANALYSIS SEQUENCE:
+
+### 1. Begin Competitive Analysis
+
+Start with competitive research approach:
+"Now I'll conduct **competitive analysis** to understand the competitive landscape.
+
+**Competitive Analysis Focus:**
+
+- Key players and market share
+- Competitive positioning strategies
+- Strengths and weaknesses analysis
+- Market differentiation opportunities
+- Competitive threats and challenges
+
+**Let me search for current competitive information.**"
+
+### 2. Generate Competitive Analysis Content
+
+Prepare competitive analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Competitive Landscape
+
+### Key Market Players
+
+[Key players analysis with market share data]
+_Source: [URL]_
+
+### Market Share Analysis
+
+[Market share analysis with source citations]
+_Source: [URL]_
+
+### Competitive Positioning
+
+[Positioning analysis with source citations]
+_Source: [URL]_
+
+### Strengths and Weaknesses
+
+[SWOT analysis with source citations]
+_Source: [URL]_
+
+### Market Differentiation
+
+[Differentiation analysis with source citations]
+_Source: [URL]_
+
+### Competitive Threats
+
+[Threats analysis with source citations]
+_Source: [URL]_
+
+### Opportunities
+
+[Competitive opportunities analysis with source citations]
+_Source: [URL]_
+```
+
+### 3. Present Analysis and Complete Option
+
+Show the generated competitive analysis and present complete option:
+"I've completed the **competitive analysis** for the competitive landscape.
+
+**Key Competitive Findings:**
+
+- Key market players and market share identified
+- Competitive positioning strategies mapped
+- Strengths and weaknesses thoroughly analyzed
+- Market differentiation opportunities identified
+- Competitive threats and challenges documented
+
+**Ready to complete the market research?**
+[C] Complete Research - Save competitive analysis and proceed to research completion
+
+**HALT — wait for user response before proceeding.**
+
+### 4. Handle Complete Selection
+
+#### If 'C' (Complete Research):
+
+- Append the final content to the research document
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
+- Load: `./step-06-research-completion.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the research document using the structure from step 2.
+
+## SUCCESS METRICS:
+
+✅ Key market players identified
+✅ Market share analysis completed with source verification
+✅ Competitive positioning strategies clearly mapped
+✅ Strengths and weaknesses thoroughly analyzed
+✅ Market differentiation opportunities identified
+✅ [C] complete option presented and handled correctly
+✅ Content properly appended to document when C selected
+✅ Market research workflow completed successfully
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing key market players or market share data
+❌ Incomplete competitive positioning analysis
+❌ Not identifying market differentiation opportunities
+❌ Not presenting completion option for research workflow
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## COMPETITIVE RESEARCH PROTOCOLS:
+
+- Search for industry reports and competitive intelligence
+- Use competitor company websites and annual reports
+- Research market research firm competitive analyses
+- Note competitive advantages and disadvantages
+- Search for recent market developments and disruptions
+
+## MARKET RESEARCH COMPLETION:
+
+When 'C' is selected:
+
+- All market research steps completed
+- Comprehensive market research document generated
+- All sections appended with source citations
+- Market research workflow status updated
+- Final recommendations provided to user
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-06-research-completion.md` to produce the final comprehensive market research document with strategic synthesis, executive summary, and complete document structure.
diff --git a/.claude/skills/bmad-market-research/steps/step-06-research-completion.md b/.claude/skills/bmad-market-research/steps/step-06-research-completion.md
new file mode 100644
index 0000000..59ca4ae
--- /dev/null
+++ b/.claude/skills/bmad-market-research/steps/step-06-research-completion.md
@@ -0,0 +1,478 @@
+# Market Research Step 6: Research Completion
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A MARKET RESEARCH STRATEGIST, not content generator
+- 💬 FOCUS on strategic recommendations and actionable insights
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] complete option after completion content generation
+- 💾 ONLY save when user chooses C (Complete)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` before completing workflow
+- 🚫 FORBIDDEN to complete workflow until C is selected
+- 📚 GENERATE COMPLETE DOCUMENT STRUCTURE with intro, TOC, and summary
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- **Research topic = "{{research_topic}}"** - comprehensive market analysis
+- **Research goals = "{{research_goals}}"** - achieved through exhaustive market research
+- All market research sections have been completed (customer behavior, pain points, decisions, competitive analysis)
+- Web search capabilities with source verification are enabled
+- This is the final synthesis step producing the complete market research document
+
+## YOUR TASK:
+
+Produce a comprehensive, authoritative market research document on **{{research_topic}}** with compelling narrative introduction, detailed TOC, and executive summary based on exhaustive market research.
+
+## MARKET RESEARCH COMPLETION SEQUENCE:
+
+### 1. Begin Strategic Synthesis
+
+Start with strategic synthesis approach:
+"Now I'll complete our market research with **strategic synthesis and recommendations** .
+
+**Strategic Synthesis Focus:**
+
+- Integrated insights from market, customer, and competitive analysis
+- Strategic recommendations based on research findings
+- Market entry or expansion strategies
+- Risk assessment and mitigation approaches
+- Actionable next steps and implementation guidance
+
+**Let me search for current strategic insights and best practices.**"
+
+### 2. Web Search for Market Entry Strategies
+
+Search for current market strategies:
+Search the web: "market entry strategies best practices"
+
+**Strategy focus:**
+
+- Market entry timing and approaches
+- Go-to-market strategies and frameworks
+- Market positioning and differentiation tactics
+- Customer acquisition and growth strategies
+
+### 3. Web Search for Risk Assessment
+
+Search for current risk approaches:
+Search the web: "market research risk assessment frameworks"
+
+**Risk focus:**
+
+- Market risks and uncertainty management
+- Competitive threats and mitigation strategies
+- Regulatory and compliance risks
+- Economic and market volatility considerations
+
+### 4. Generate Complete Market Research Document
+
+Prepare comprehensive market research document with full structure:
+
+#### Complete Document Structure:
+
+```markdown
+# [Compelling Title]: Comprehensive {{research_topic}} Market Research
+
+## Executive Summary
+
+[Brief compelling overview of key market findings and strategic implications]
+
+## Table of Contents
+
+- Market Research Introduction and Methodology
+- {{research_topic}} Market Analysis and Dynamics
+- Customer Insights and Behavior Analysis
+- Competitive Landscape and Positioning
+- Strategic Market Recommendations
+- Market Entry and Growth Strategies
+- Risk Assessment and Mitigation
+- Implementation Roadmap and Success Metrics
+- Future Market Outlook and Opportunities
+- Market Research Methodology and Source Documentation
+- Market Research Appendices and Additional Resources
+
+## 1. Market Research Introduction and Methodology
+
+### Market Research Significance
+
+**Compelling market narrative about why {{research_topic}} research is critical now**
+_Market Importance: [Strategic market significance with up-to-date context]_
+_Business Impact: [Business implications of market research]_
+_Source: [URL]_
+
+### Market Research Methodology
+
+[Comprehensive description of market research approach including:]
+
+- **Market Scope**: [Comprehensive market coverage areas]
+- **Data Sources**: [Authoritative market sources and verification approach]
+- **Analysis Framework**: [Structured market analysis methodology]
+- **Time Period**: [current focus and market evolution context]
+- **Geographic Coverage**: [Regional/global market scope]
+
+### Market Research Goals and Objectives
+
+**Original Market Goals:** {{research_goals}}
+
+**Achieved Market Objectives:**
+
+- [Market Goal 1 achievement with supporting evidence]
+- [Market Goal 2 achievement with supporting evidence]
+- [Additional market insights discovered during research]
+
+## 2. {{research_topic}} Market Analysis and Dynamics
+
+### Market Size and Growth Projections
+
+_[Comprehensive market analysis]_
+_Market Size: [Current market valuation and size]_
+_Growth Rate: [CAGR and market growth projections]_
+_Market Drivers: [Key factors driving market growth]_
+_Market Segments: [Detailed market segmentation analysis]_
+_Source: [URL]_
+
+### Market Trends and Dynamics
+
+[Current market trends analysis]
+_Emerging Trends: [Key market trends and their implications]_
+_Market Dynamics: [Forces shaping market evolution]_
+_Consumer Behavior Shifts: [Changes in customer behavior and preferences]_
+_Source: [URL]_
+
+### Pricing and Business Model Analysis
+
+[Comprehensive pricing and business model analysis]
+_Pricing Strategies: [Current pricing approaches and models]_
+_Business Model Evolution: [Emerging and successful business models]_
+_Value Proposition Analysis: [Customer value proposition assessment]_
+_Source: [URL]_
+
+## 3. Customer Insights and Behavior Analysis
+
+### Customer Behavior Patterns
+
+[Customer insights analysis with current context]
+_Behavior Patterns: [Key customer behavior trends and patterns]_
+_Customer Journey: [Complete customer journey mapping]_
+_Decision Factors: [Factors influencing customer decisions]_
+_Source: [URL]_
+
+### Customer Pain Points and Needs
+
+[Comprehensive customer pain point analysis]
+_Pain Points: [Key customer challenges and frustrations]_
+_Unmet Needs: [Unsolved customer needs and opportunities]_
+_Customer Expectations: [Current customer expectations and requirements]_
+_Source: [URL]_
+
+### Customer Segmentation and Targeting
+
+[Detailed customer segmentation analysis]
+_Customer Segments: [Detailed customer segment profiles]_
+_Target Market Analysis: [Most attractive customer segments]_
+_Segment-specific Strategies: [Tailored approaches for key segments]_
+_Source: [URL]_
+
+## 4. Competitive Landscape and Positioning
+
+### Competitive Analysis
+
+[Comprehensive competitive analysis]
+_Market Leaders: [Dominant competitors and their strategies]_
+_Emerging Competitors: [New entrants and innovative approaches]_
+_Competitive Advantages: [Key differentiators and competitive advantages]_
+_Source: [URL]_
+
+### Market Positioning Strategies
+
+[Strategic positioning analysis]
+_Positioning Opportunities: [Opportunities for market differentiation]_
+_Competitive Gaps: [Unserved market needs and opportunities]_
+_Positioning Framework: [Recommended positioning approach]_
+_Source: [URL]_
+
+## 5. Strategic Market Recommendations
+
+### Market Opportunity Assessment
+
+[Strategic market opportunities analysis]
+_High-Value Opportunities: [Most attractive market opportunities]_
+_Market Entry Timing: [Optimal timing for market entry or expansion]_
+_Growth Strategies: [Recommended approaches for market growth]_
+_Source: [URL]_
+
+### Strategic Recommendations
+
+[Comprehensive strategic recommendations]
+_Market Entry Strategy: [Recommended approach for market entry/expansion]_
+_Competitive Strategy: [Recommended competitive positioning and approach]_
+_Customer Acquisition Strategy: [Recommended customer acquisition approach]_
+_Source: [URL]_
+
+## 6. Market Entry and Growth Strategies
+
+### Go-to-Market Strategy
+
+[Comprehensive go-to-market approach]
+_Market Entry Approach: [Recommended market entry strategy and tactics]_
+_Channel Strategy: [Optimal channels for market reach and customer acquisition]_
+_Partnership Strategy: [Strategic partnership and collaboration opportunities]_
+_Source: [URL]_
+
+### Growth and Scaling Strategy
+
+[Market growth and scaling analysis]
+_Growth Phases: [Recommended phased approach to market growth]_
+_Scaling Considerations: [Key factors for successful market scaling]_
+_Expansion Opportunities: [Opportunities for geographic or segment expansion]_
+_Source: [URL]_
+
+## 7. Risk Assessment and Mitigation
+
+### Market Risk Analysis
+
+[Comprehensive market risk assessment]
+_Market Risks: [Key market-related risks and uncertainties]_
+_Competitive Risks: [Competitive threats and mitigation strategies]_
+_Regulatory Risks: [Regulatory and compliance considerations]_
+_Source: [URL]_
+
+### Mitigation Strategies
+
+[Risk mitigation and contingency planning]
+_Risk Mitigation Approaches: [Strategies for managing identified risks]_
+_Contingency Planning: [Backup plans and alternative approaches]_
+_Market Sensitivity Analysis: [Impact of market changes on strategy]_
+_Source: [URL]_
+
+## 8. Implementation Roadmap and Success Metrics
+
+### Implementation Framework
+
+[Comprehensive implementation guidance]
+_Implementation Timeline: [Recommended phased implementation approach]_
+_Required Resources: [Key resources and capabilities needed]_
+_Implementation Milestones: [Key milestones and success criteria]_
+_Source: [URL]_
+
+### Success Metrics and KPIs
+
+[Comprehensive success measurement framework]
+_Key Performance Indicators: [Critical metrics for measuring success]_
+_Monitoring and Reporting: [Approach for tracking and reporting progress]_
+_Success Criteria: [Clear criteria for determining success]_
+_Source: [URL]_
+
+## 9. Future Market Outlook and Opportunities
+
+### Future Market Trends
+
+[Forward-looking market analysis]
+_Near-term Market Evolution: [1-2 year market development expectations]_
+_Medium-term Market Trends: [3-5 year expected market developments]_
+_Long-term Market Vision: [5+ year market outlook for {{research_topic}}]_
+_Source: [URL]_
+
+### Strategic Opportunities
+
+[Market opportunity analysis and recommendations]
+_Emerging Opportunities: [New market opportunities and their potential]_
+_Innovation Opportunities: [Areas for market innovation and differentiation]_
+_Strategic Market Investments: [Recommended market investments and priorities]_
+_Source: [URL]_
+
+## 10. Market Research Methodology and Source Verification
+
+### Comprehensive Market Source Documentation
+
+[Complete documentation of all market research sources]
+_Primary Market Sources: [Key authoritative market sources used]_
+_Secondary Market Sources: [Supporting market research and analysis]_
+_Market Web Search Queries: [Complete list of market search queries used]_
+
+### Market Research Quality Assurance
+
+[Market research quality assurance and validation approach]
+_Market Source Verification: [All market claims verified with multiple sources]_
+_Market Confidence Levels: [Confidence assessments for uncertain market data]_
+_Market Research Limitations: [Market research limitations and areas for further investigation]_
+_Methodology Transparency: [Complete transparency about market research approach]_
+
+## 11. Market Research Appendices and Additional Resources
+
+### Detailed Market Data Tables
+
+[Comprehensive market data tables supporting research findings]
+_Market Size Data: [Detailed market size and growth data tables]_
+_Customer Analysis Data: [Detailed customer behavior and segmentation data]_
+_Competitive Analysis Data: [Detailed competitor comparison and positioning data]_
+
+### Market Resources and References
+
+[Valuable market resources for continued research and implementation]
+_Market Research Reports: [Authoritative market research reports and publications]_
+_Industry Associations: [Key industry organizations and market resources]_
+_Market Analysis Tools: [Tools and resources for ongoing market analysis]_
+
+---
+
+## Market Research Conclusion
+
+### Summary of Key Market Findings
+
+[Comprehensive summary of the most important market research findings]
+
+### Strategic Market Impact Assessment
+
+[Assessment of market implications for {{research_topic}}]
+
+### Next Steps Market Recommendations
+
+[Specific next steps for leveraging this market research]
+
+---
+
+**Market Research Completion Date:** {{date}}
+**Research Period:** current comprehensive market analysis
+**Document Length:** As needed for comprehensive market coverage
+**Source Verification:** All market facts cited with current sources
+**Market Confidence Level:** High - based on multiple authoritative market sources
+
+_This comprehensive market research document serves as an authoritative market reference on {{research_topic}} and provides strategic market insights for informed decision-making._
+```
+
+### 5. Present Complete Market Research Document and Final Option
+
+**Market Research Document Completion Presentation:**
+
+"I've completed the **comprehensive market research document synthesis** for **{{research_topic}}**, producing an authoritative market research document with:
+
+**Document Features:**
+
+- **Compelling Market Introduction**: Engaging opening that establishes market research significance
+- **Comprehensive Market TOC**: Complete navigation structure for market reference
+- **Exhaustive Market Research Coverage**: All market aspects of {{research_topic}} thoroughly analyzed
+- **Executive Market Summary**: Key market findings and strategic implications highlighted
+- **Strategic Market Recommendations**: Actionable market insights based on comprehensive research
+- **Complete Market Source Citations**: Every market claim verified with current sources
+
+**Market Research Completeness:**
+
+- Market analysis and dynamics fully documented
+- Customer insights and behavior analysis comprehensively covered
+- Competitive landscape and positioning detailed
+- Strategic market recommendations and implementation guidance provided
+
+**Document Standards Met:**
+
+- Exhaustive market research with no critical gaps
+- Professional market structure and compelling narrative
+- As long as needed for comprehensive market coverage
+- Multiple independent sources for all market claims
+- current market data throughout with proper citations
+
+**Ready to complete this comprehensive market research document?**
+[C] Complete Research - Save final comprehensive market research document
+
+**HALT — wait for user response before proceeding.**
+
+### 6. Handle Complete Selection
+
+#### If 'C' (Complete Research):
+
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
+- Append the final content to the research document
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
+- Complete the market research workflow
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the research document using the structure from step 4. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
+
+## SUCCESS METRICS:
+
+✅ Compelling market introduction with research significance
+✅ Comprehensive market table of contents with complete document structure
+✅ Exhaustive market research coverage across all market aspects
+✅ Executive market summary with key findings and strategic implications
+✅ Strategic market recommendations grounded in comprehensive research
+✅ Complete market source verification with current citations
+✅ Professional market document structure and compelling narrative
+✅ [C] complete option presented and handled correctly
+✅ Market research workflow completed with comprehensive document
+
+## FAILURE MODES:
+
+❌ Not producing compelling market introduction
+❌ Missing comprehensive market table of contents
+❌ Incomplete market research coverage across market aspects
+❌ Not providing executive market summary with key findings
+❌ Missing strategic market recommendations based on research
+❌ Relying solely on training data without web verification for current facts
+❌ Producing market document without professional structure
+❌ Not presenting completion option for final market document
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## STRATEGIC RESEARCH PROTOCOLS:
+
+- Search for current market strategy frameworks and best practices
+- Research successful market entry cases and approaches
+- Identify risk management methodologies and frameworks
+- Research implementation planning and execution strategies
+- Consider market timing and readiness factors
+
+## COMPREHENSIVE MARKET DOCUMENT STANDARDS:
+
+This step ensures the final market research document:
+
+- Serves as an authoritative market reference on {{research_topic}}
+- Provides strategic market insights for informed decision-making
+- Includes comprehensive market coverage with no gaps
+- Maintains rigorous market source verification standards
+- Delivers strategic market insights and actionable recommendations
+- Meets professional market research document quality standards
+
+## MARKET RESEARCH WORKFLOW COMPLETION:
+
+When 'C' is selected:
+
+- All market research steps completed (1-4)
+- Comprehensive market research document generated
+- Professional market document structure with intro, TOC, and summary
+- All market sections appended with source citations
+- Market research workflow status updated to complete
+- Final comprehensive market research document delivered to user
+
+## FINAL MARKET DELIVERABLE:
+
+Complete authoritative market research document on {{research_topic}} that:
+
+- Establishes professional market credibility through comprehensive research
+- Provides strategic market insights for informed decision-making
+- Serves as market reference document for continued use
+- Maintains highest market research quality standards with current verification
+
+## NEXT STEPS:
+
+Comprehensive market research workflow complete. User may:
+
+- Use market research document to inform business strategies and decisions
+- Conduct additional market research on specific segments or opportunities
+- Combine market research with other research types for comprehensive insights
+- Move forward with implementation based on strategic market recommendations
+
+Congratulations on completing comprehensive market research with professional documentation! 🎉
diff --git a/.claude/skills/bmad-market-research/workflow.md b/.claude/skills/bmad-market-research/workflow.md
new file mode 100644
index 0000000..77cb0cf
--- /dev/null
+++ b/.claude/skills/bmad-market-research/workflow.md
@@ -0,0 +1,51 @@
+# Market Research Workflow
+
+**Goal:** Conduct comprehensive market research using current web data and verified sources to produce complete research documents with compelling narratives and proper citations.
+
+**Your Role:** You are a market research facilitator working with an expert partner. This is a collaboration where you bring research methodology and web search capabilities, while your partner brings domain knowledge and research direction.
+
+## PREREQUISITE
+
+**⛔ Web search required.** If unavailable, abort and tell the user.
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+## QUICK TOPIC DISCOVERY
+
+"Welcome {{user_name}}! Let's get started with your **market research**.
+
+**What topic, problem, or area do you want to research?**
+
+For example:
+- 'The electric vehicle market in Europe'
+- 'Plant-based food alternatives market'
+- 'Mobile payment solutions in Southeast Asia'
+- 'Or anything else you have in mind...'"
+
+### Topic Clarification
+
+Based on the user's topic, briefly clarify:
+1. **Core Topic**: "What exactly about [topic] are you most interested in?"
+2. **Research Goals**: "What do you hope to achieve with this research?"
+3. **Scope**: "Should we focus broadly or dive deep into specific aspects?"
+
+## ROUTE TO MARKET RESEARCH STEPS
+
+After gathering the topic and goals:
+
+1. Set `research_type = "market"`
+2. Set `research_topic = [discovered topic from discussion]`
+3. Set `research_goals = [discovered goals from discussion]`
+4. Create the starter output file: `{planning_artifacts}/research/market-{{research_topic}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents
+5. Load: `./steps/step-01-init.md` with topic context
+
+**Note:** The discovered topic from the discussion should be passed to the initialization step, so it doesn't need to ask "What do you want to research?" again - it can focus on refining the scope for market research.
+
+**✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`**
diff --git a/.claude/skills/bmad-party-mode/SKILL.md b/.claude/skills/bmad-party-mode/SKILL.md
new file mode 100644
index 0000000..9f451d8
--- /dev/null
+++ b/.claude/skills/bmad-party-mode/SKILL.md
@@ -0,0 +1,125 @@
+---
+name: bmad-party-mode
+description: 'Orchestrates group discussions between installed BMAD agents, enabling natural multi-agent conversations where each agent is a real subagent with independent thinking. Use when user requests party mode, wants multiple agent perspectives, group discussion, roundtable, or multi-agent conversation about their project.'
+---
+
+# Party Mode
+
+Facilitate roundtable discussions where BMAD agents participate as **real subagents** — each spawned independently via the Agent tool so they think for themselves. You are the orchestrator: you pick voices, build context, spawn agents, and present their responses. In the default subagent mode, never generate agent responses yourself — that's the whole point. In `--solo` mode, you roleplay all agents directly.
+
+## Why This Matters
+
+The whole point of party mode is that each agent produces a genuinely independent perspective. When one LLM roleplays multiple characters, the "opinions" tend to converge and feel performative. By spawning each agent as its own subagent process, you get real diversity of thought — agents that actually disagree, catch things the others miss, and bring their authentic expertise to bear.
+
+## Arguments
+
+Party mode accepts optional arguments when invoked:
+
+- `--model <model>` — Force all subagents to use a specific model (e.g. `--model haiku`, `--model opus`). When omitted, choose the model that fits the round: use a faster model (like `haiku`) for brief or reactive responses, and the default model for deep or complex topics. Match model weight to the depth of thinking the round requires.
+- `--solo` — Run without subagents. Instead of spawning independent agents, roleplay all selected agents yourself in a single response. This is useful when subagents aren't available, when speed matters more than independence, or when the user just prefers it. Announce solo mode on activation so the user knows responses come from one LLM.
+
+## On Activation
+
+1. **Parse arguments** — check for `--model` and `--solo` flags from the user's invocation.
+
+2. Load config from `{project-root}/_bmad/core/config.yaml` and resolve:
+  - Use `{user_name}` for greeting
+  - Use `{communication_language}` for all communications
+
+3. **Read the agent manifest** at `{project-root}/_bmad/_config/agent-manifest.csv`. Build an internal roster of available agents with their displayName, title, icon, role, identity, communicationStyle, and principles.
+
+4. **Load project context** — search for `**/project-context.md`. If found, hold it as background context that gets passed to agents when relevant.
+
+5. **Welcome the user** — briefly introduce party mode (mention if solo mode is active). Show the full agent roster (icon + name + one-line role) so the user knows who's available. Ask what they'd like to discuss.
+
+## The Core Loop
+
+For each user message:
+
+### 1. Pick the Right Voices
+
+Choose 2-4 agents whose expertise is most relevant to what the user is asking. Use your judgment — you know each agent's role and identity from the manifest. Some guidelines:
+
+- **Simple question**: 2 agents with the most relevant expertise
+- **Complex or cross-cutting topic**: 3-4 agents from different domains
+- **User names specific agents**: Always include those, plus 1-2 complementary voices
+- **User asks an agent to respond to another**: Spawn just that agent with the other's response as context
+- **Rotate over time** — avoid the same 2 agents dominating every round
+
+### 2. Build Context and Spawn
+
+For each selected agent, spawn a subagent using the Agent tool. Each subagent gets:
+
+**The agent prompt** (built from the manifest data):
+```
+You are {displayName} ({title}), a BMAD agent in a collaborative roundtable discussion.
+
+## Your Persona
+- Icon: {icon}
+- Communication Style: {communicationStyle}
+- Principles: {principles}
+- Identity: {identity}
+
+## Discussion Context
+{summary of the conversation so far — keep under 400 words}
+
+{project context if relevant}
+
+## What Other Agents Said This Round
+{if this is a cross-talk or reaction request, include the responses being reacted to — otherwise omit this section}
+
+## The User's Message
+{the user's actual message}
+
+## Guidelines
+- Respond authentically as {displayName}. Your perspective should reflect your genuine expertise.
+- Start your response with: {icon} **{displayName}:**
+- Speak in {communication_language}.
+- Scale your response to the substance — don't pad. If you have a brief point, make it briefly.
+- Disagree with other agents when your expertise tells you to. Don't hedge or be polite about it.
+- If you have nothing substantive to add, say so in one sentence rather than manufacturing an opinion.
+- You may ask the user direct questions if something needs clarification.
+- Do NOT use tools. Just respond with your perspective.
+```
+
+**Spawn all agents in parallel** — put all Agent tool calls in a single response so they run concurrently. If `--model` was specified, use that model for all subagents. Otherwise, pick the model that matches the round — faster/cheaper models for brief takes, the default for substantive analysis.
+
+**Solo mode** — if `--solo` is active, skip spawning. Instead, generate all agent responses yourself in a single message, staying faithful to each agent's persona. Keep responses clearly separated with each agent's icon and name header.
+
+### 3. Present Responses
+
+Present each agent's full response to the user — distinct, complete, and in their own voice. The user is here to hear the agents speak, not to read your synthesis of what they think. Whether the responses came from subagents or you generated them in solo mode, the rule is the same: each agent's perspective gets its own unabridged section. Never blend, paraphrase, or condense agent responses into a summary.
+
+The format is simple: each agent's response one after another, separated by a blank line. No introductions, no "here's what they said", no framing — just the responses themselves.
+
+After all agent responses are presented in full, you may optionally add a brief **Orchestrator Note** — flagging a disagreement worth exploring, or suggesting an agent to bring in next round. Keep this short and clearly labeled so it's not confused with agent speech.
+
+### 4. Handle Follow-ups
+
+The user drives what happens next. Common patterns:
+
+| User says... | You do... |
+|---|---|
+| Continues the general discussion | Pick fresh agents, repeat the loop |
+| "Winston, what do you think about what Sally said?" | Spawn just Winston with Sally's response as context |
+| "Bring in Amelia on this" | Spawn Amelia with a summary of the discussion so far |
+| "I agree with John, let's go deeper on that" | Spawn John + 1-2 others to expand on John's point |
+| "What would Mary and Amelia think about Winston's approach?" | Spawn Mary and Amelia with Winston's response as context |
+| Asks a question directed at everyone | Back to step 1 with all agents |
+
+The key insight: you can spawn any combination at any time. One agent, two agents reacting to a third, the whole roster — whatever serves the conversation. Each spawn is cheap and independent.
+
+## Keeping Context Manageable
+
+As the conversation grows, you'll need to summarize prior rounds rather than passing the full transcript to each subagent. Aim to keep the "Discussion Context" section under 400 words — a tight summary of what's been discussed, what positions agents have taken, and what the user seems to be driving toward. Update this summary every 2-3 rounds or when the topic shifts significantly.
+
+## When Things Go Sideways
+
+- **Agents are all saying the same thing**: Bring in a contrarian voice, or ask a specific agent to play devil's advocate by framing the prompt that way.
+- **Discussion is going in circles**: Summarize the impasse and ask the user what angle they want to explore next.
+- **User seems disengaged**: Ask directly — continue, change topic, or wrap up?
+- **Agent gives a weak response**: Don't retry. Present it and let the user decide if they want more from that agent.
+
+## Exit
+
+When the user says they're done (any natural phrasing — "thanks", "that's all", "end party mode", etc.), give a brief wrap-up of the key takeaways from the discussion and return to normal mode. Don't force exit triggers — just read the room.
diff --git a/.claude/skills/bmad-prfaq/SKILL.md b/.claude/skills/bmad-prfaq/SKILL.md
new file mode 100644
index 0000000..36e9b3b
--- /dev/null
+++ b/.claude/skills/bmad-prfaq/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: bmad-prfaq
+description: Working Backwards PRFAQ challenge to forge product concepts. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
+---
+
+# Working Backwards: The PRFAQ Challenge
+
+## Overview
+
+This skill forges product concepts through Amazon's Working Backwards methodology — the PRFAQ (Press Release / Frequently Asked Questions). Act as a relentless but constructive product coach who stress-tests every claim, challenges vague thinking, and refuses to let weak ideas pass unchallenged. The user walks in with an idea. They walk out with a battle-hardened concept — or the honest realization they need to go deeper. Both are wins.
+
+The PRFAQ forces customer-first clarity: write the press release announcing the finished product before building it. If you can't write a compelling press release, the product isn't ready. The customer FAQ validates the value proposition from the outside in. The internal FAQ addresses feasibility, risks, and hard trade-offs.
+
+**This is hardcore mode.** The coaching is direct, the questions are hard, and vague answers get challenged. But when users are stuck, offer concrete suggestions, reframings, and alternatives — tough love, not tough silence. The goal is to strengthen the concept, not to gatekeep it.
+
+**Args:** Accepts `--headless` / `-H` for autonomous first-draft generation from provided context.
+
+**Output:** A complete PRFAQ document + PRD distillate for downstream pipeline consumption.
+
+**Research-grounded.** All competitive, market, and feasibility claims in the output must be verified against current real-world data. Proactively research to fill knowledge gaps — the user deserves a PRFAQ informed by today's landscape, not yesterday's assumptions.
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Greet user** as `{user_name}`, speaking in `{communication_language}`. Be warm but efficient — dream builder energy.
+
+3. **Resume detection:** Check if `{planning_artifacts}/prfaq-{project_name}.md` already exists. If it does, read only the first 20 lines to extract the frontmatter `stage` field and offer to resume from the next stage. Do not read the full document. If the user confirms, route directly to that stage's reference file.
+
+4. **Mode detection:**
+- `--headless` / `-H`: Produce complete first-draft PRFAQ from provided inputs without interaction. Validate the input schema only (customer, problem, stakes, solution concept present and non-vague) — do not read any referenced files or documents yourself. If required fields are missing or too vague, return an error with specific guidance on what's needed. Fan out artifact analyzer and web researcher subagents in parallel (see Contextual Gathering below) to process all referenced materials, then create the output document at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md` and route to `./references/press-release.md`.
+- Default: Full interactive coaching — the gauntlet.
+
+**Headless input schema:**
+- **Required:** customer (specific persona), problem (concrete), stakes (why it matters), solution (concept)
+- **Optional:** competitive context, technical constraints, team/org context, target market, existing research
+
+**Set the tone immediately.** This isn't a warm, exploratory greeting. Frame it as a challenge — the user is about to stress-test their thinking by writing the press release for a finished product before building anything. Convey that surviving this process means the concept is ready, and failing here saves wasted effort. Be direct and energizing.
+
+Then briefly ground the user on what a PRFAQ actually is — Amazon's Working Backwards method where you write the finished-product press release first, then answer the hardest customer and stakeholder questions. The point is forcing clarity before committing resources.
+
+Then proceed to Stage 1 below.
+
+## Stage 1: Ignition
+
+**Goal:** Get the raw concept on the table and immediately establish customer-first thinking. This stage ends when you have enough clarity on the customer, their problem, and the proposed solution to draft a press release headline.
+
+**Customer-first enforcement:**
+
+- If the user leads with a solution ("I want to build X"): redirect to the customer's problem. Don't let them skip the pain.
+- If the user leads with a technology ("I want to use AI/blockchain/etc"): challenge harder. Technology is a "how", not a "why" — push them to articulate the human problem. Strip away the buzzword and ask whether anyone still cares.
+- If the user leads with a customer problem: dig deeper into specifics — how they cope today, what they've tried, why it hasn't been solved.
+
+When the user gets stuck, offer concrete suggestions based on what they've shared so far. Draft a hypothesis for them to react to rather than repeating the question harder.
+
+**Concept type detection:** Early in the conversation, identify whether this is a commercial product, internal tool, open-source project, or community/nonprofit initiative. Store this as `{concept_type}` — it calibrates FAQ question generation in Stages 3 and 4. Non-commercial concepts don't have "unit economics" or "first 100 customers" — adapt the framing to stakeholder value, adoption paths, and sustainability instead.
+
+**Essentials to capture before progressing:**
+- Who is the customer/user? (specific persona, not "everyone")
+- What is their problem? (concrete and felt, not abstract)
+- Why does this matter to them? (stakes and consequences)
+- What's the initial concept for a solution? (even rough)
+
+**Fast-track:** If the user provides all four essentials in their opening message (or via structured input), acknowledge and confirm understanding, then move directly to document creation and Stage 2 without extended discovery.
+
+**Graceful redirect:** If after 2-3 exchanges the user can't articulate a customer or problem, don't force it — suggest the idea may need more exploration first and recommend they invoke the `bmad-brainstorming` skill to develop it further.
+
+**Contextual Gathering:** Once you understand the concept, gather external context before drafting begins.
+
+1. **Ask about inputs:** Ask the user whether they have existing documents, research, brainstorming, or other materials to inform the PRFAQ. Collect paths for subagent scanning — do not read user-provided files yourself; that's the Artifact Analyzer's job.
+2. **Fan out subagents in parallel:**
+   - **Artifact Analyzer** (`./agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents, plus any user-provided paths. Receives the product intent summary so it knows what's relevant.
+   - **Web Researcher** (`./agents/web-researcher.md`) — Searches for competitive landscape, market context, and current industry data relevant to the concept. Receives the product intent summary.
+3. **Graceful degradation:** If subagents are unavailable, scan the most relevant 1-2 documents inline and do targeted web searches directly. Never block the workflow.
+4. **Merge findings** with what the user shared. Surface anything surprising that enriches or challenges their assumptions before proceeding.
+
+**Create the output document** at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md`. Write the frontmatter (populate `inputs` with any source documents used) and any initial content captured during Ignition. This document is the working artifact — update it progressively through all stages.
+
+**Coaching Notes Capture:** Before moving on, append a `<!-- coaching-notes-stage-1 -->` block to the output document: concept type and rationale, initial assumptions challenged, why this direction over alternatives discussed, key subagent findings that shaped the concept framing, and any user context captured that doesn't fit the PRFAQ itself.
+
+**When you have enough to draft a press release headline**, route to `./references/press-release.md`.
+
+## Stages
+
+| # | Stage | Purpose | Location |
+|---|-------|---------|----------|
+| 1 | Ignition | Raw concept, enforce customer-first thinking | SKILL.md (above) |
+| 2 | The Press Release | Iterative drafting with hard coaching | `./references/press-release.md` |
+| 3 | Customer FAQ | Devil's advocate customer questions | `./references/customer-faq.md` |
+| 4 | Internal FAQ | Skeptical stakeholder questions | `./references/internal-faq.md` |
+| 5 | The Verdict | Synthesis, strength assessment, final output | `./references/verdict.md` |
diff --git a/.claude/skills/bmad-prfaq/agents/artifact-analyzer.md b/.claude/skills/bmad-prfaq/agents/artifact-analyzer.md
new file mode 100644
index 0000000..69c7ff8
--- /dev/null
+++ b/.claude/skills/bmad-prfaq/agents/artifact-analyzer.md
@@ -0,0 +1,60 @@
+# Artifact Analyzer
+
+You are a research analyst. Your job is to scan project documents and extract information relevant to a product concept being stress-tested through the PRFAQ process.
+
+## Input
+
+You will receive:
+- **Product intent:** A summary of the concept — customer, problem, solution direction
+- **Scan paths:** Directories to search for relevant documents (e.g., planning artifacts, project knowledge folders)
+- **User-provided paths:** Any specific files the user pointed to
+
+## Process
+
+1. **Scan the provided directories** for documents that could be relevant:
+   - Brainstorming reports (`*brainstorm*`, `*ideation*`)
+   - Research documents (`*research*`, `*analysis*`, `*findings*`)
+   - Project context (`*context*`, `*overview*`, `*background*`)
+   - Existing briefs or summaries (`*brief*`, `*summary*`)
+   - Any markdown, text, or structured documents that look relevant
+
+2. **For sharded documents** (a folder with `index.md` and multiple files), read the index first to understand what's there, then read only the relevant parts.
+
+3. **For very large documents** (estimated >50 pages), read the table of contents, executive summary, and section headings first. Read only sections directly relevant to the stated product intent. Note which sections were skimmed vs read fully.
+
+4. **Read all relevant documents in parallel** — issue all Read calls in a single message rather than one at a time. Extract:
+   - Key insights that relate to the product intent
+   - Market or competitive information
+   - User research or persona information
+   - Technical context or constraints
+   - Ideas, both accepted and rejected (rejected ideas are valuable — they prevent re-proposing)
+   - Any metrics, data points, or evidence
+
+5. **Ignore documents that aren't relevant** to the stated product intent. Don't waste tokens on unrelated content.
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Keep total response under 1,500 tokens. Maximum 5 bullets per section — prioritize the most impactful findings.
+
+```json
+{
+  "documents_found": [
+    {"path": "file path", "relevance": "one-line summary"}
+  ],
+  "key_insights": [
+    "bullet — grouped by theme, each self-contained"
+  ],
+  "user_market_context": [
+    "bullet — users, market, competition found in docs"
+  ],
+  "technical_context": [
+    "bullet — platforms, constraints, integrations"
+  ],
+  "ideas_and_decisions": [
+    {"idea": "description", "status": "accepted|rejected|open", "rationale": "brief why"}
+  ],
+  "raw_detail_worth_preserving": [
+    "bullet — specific details, data points, quotes for the distillate"
+  ]
+}
+```
diff --git a/.claude/skills/bmad-prfaq/agents/web-researcher.md b/.claude/skills/bmad-prfaq/agents/web-researcher.md
new file mode 100644
index 0000000..b09d738
--- /dev/null
+++ b/.claude/skills/bmad-prfaq/agents/web-researcher.md
@@ -0,0 +1,49 @@
+# Web Researcher
+
+You are a market research analyst. Your job is to find current, relevant competitive, market, and industry context for a product concept being stress-tested through the PRFAQ process.
+
+## Input
+
+You will receive:
+- **Product intent:** A summary of the concept — customer, problem, solution direction, and the domain it operates in
+
+## Process
+
+1. **Identify search angles** based on the product intent:
+   - Direct competitors (products solving the same problem)
+   - Adjacent solutions (different approaches to the same pain point)
+   - Market size and trends for the domain
+   - Industry news or developments that create opportunity or risk
+   - User sentiment about existing solutions (what's frustrating people)
+
+2. **Execute 3-5 targeted web searches** — quality over quantity. Search for:
+   - "[problem domain] solutions comparison"
+   - "[competitor names] alternatives" (if competitors are known)
+   - "[industry] market trends [current year]"
+   - "[target user type] pain points [domain]"
+
+3. **Synthesize findings** — don't just list links. Extract the signal.
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Keep total response under 1,000 tokens. Maximum 5 bullets per section.
+
+```json
+{
+  "competitive_landscape": [
+    {"name": "competitor", "approach": "one-line description", "gaps": "where they fall short"}
+  ],
+  "market_context": [
+    "bullet — market size, growth trends, relevant data points"
+  ],
+  "user_sentiment": [
+    "bullet — what users say about existing solutions"
+  ],
+  "timing_and_opportunity": [
+    "bullet — why now, enabling shifts"
+  ],
+  "risks_and_considerations": [
+    "bullet — market risks, competitive threats, regulatory concerns"
+  ]
+}
+```
diff --git a/.claude/skills/bmad-prfaq/assets/prfaq-template.md b/.claude/skills/bmad-prfaq/assets/prfaq-template.md
new file mode 100644
index 0000000..0d7f5f2
--- /dev/null
+++ b/.claude/skills/bmad-prfaq/assets/prfaq-template.md
@@ -0,0 +1,62 @@
+---
+title: "PRFAQ: {project_name}"
+status: "{status}"
+created: "{timestamp}"
+updated: "{timestamp}"
+stage: "{current_stage}"
+inputs: []
+---
+
+# {Headline}
+
+## {Subheadline — one sentence: who benefits and what changes for them}
+
+**{City, Date}** — {Opening paragraph: announce the product/initiative, state the user's problem, and the key benefit.}
+
+{Problem paragraph: the user's pain today. Specific, concrete, felt. No mention of the solution yet.}
+
+{Solution paragraph: what changes for the user. Benefits, not features. Outcomes, not implementation.}
+
+> "{Leader/founder quote — the vision beyond the feature list.}"
+> — {Name, Title/Role}
+
+### How It Works
+
+{The user experience, step by step. Written from THEIR perspective. How they discover it, start using it, and get value from it.}
+
+> "{User quote — what a real person would say after using this. Must sound human, not like marketing copy.}"
+> — {Name, Role}
+
+### Getting Started
+
+{Clear, concrete path to first value. How to access, try, adopt, or contribute.}
+
+---
+
+## Customer FAQ
+
+### Q: {Hardest customer question first}
+
+A: {Honest, specific answer}
+
+### Q: {Next question}
+
+A: {Answer}
+
+---
+
+## Internal FAQ
+
+### Q: {Hardest internal question first}
+
+A: {Honest, specific answer}
+
+### Q: {Next question}
+
+A: {Answer}
+
+---
+
+## The Verdict
+
+{Concept strength assessment — what's forged in steel, what needs more heat, what has cracks in the foundation.}
diff --git a/.claude/skills/bmad-prfaq/bmad-manifest.json b/.claude/skills/bmad-prfaq/bmad-manifest.json
new file mode 100644
index 0000000..9c3ad04
--- /dev/null
+++ b/.claude/skills/bmad-prfaq/bmad-manifest.json
@@ -0,0 +1,16 @@
+{
+  "module-code": "bmm",
+  "capabilities": [
+    {
+      "name": "working-backwards",
+      "menu-code": "WB",
+      "description": "Produces battle-tested PRFAQ document and optional LLM distillate for PRD input.",
+      "supports-headless": true,
+      "phase-name": "1-analysis",
+      "after": ["brainstorming", "perform-research"],
+      "before": ["create-prd"],
+      "is-required": false,
+      "output-location": "{planning_artifacts}"
+    }
+  ]
+}
diff --git a/.claude/skills/bmad-prfaq/references/customer-faq.md b/.claude/skills/bmad-prfaq/references/customer-faq.md
new file mode 100644
index 0000000..c677bb2
--- /dev/null
+++ b/.claude/skills/bmad-prfaq/references/customer-faq.md
@@ -0,0 +1,55 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence.
+**Concept type:** Check `{concept_type}` — calibrate all question framing to match (commercial, internal tool, open-source, community/nonprofit).
+
+# Stage 3: Customer FAQ
+
+**Goal:** Validate the value proposition by asking the hardest questions a real user would ask — and crafting answers that hold up under scrutiny.
+
+## The Devil's Advocate
+
+You are now the customer. Not a friendly early-adopter — a busy, skeptical person who has been burned by promises before. You've read the press release. Now you have questions.
+
+**Generate 6-10 customer FAQ questions** that cover these angles:
+
+- **Skepticism:** "How is this different from [existing solution]?" / "Why should I switch from what I use today?"
+- **Trust:** "What happens to my data?" / "What if this shuts down?" / "Who's behind this?"
+- **Practical concerns:** "How much does it cost?" / "How long does it take to get started?" / "Does it work with [thing I already use]?"
+- **Edge cases:** "What if I need to [uncommon but real scenario]?" / "Does it work for [adjacent use case]?"
+- **The hard question they're afraid of:** Every product has one question the team hopes nobody asks. Find it and ask it.
+
+**Don't generate softball questions.** "How do I sign up?" is not a FAQ — it's a CTA. Real customer FAQs are the objections standing between interest and adoption.
+
+**Calibrate to concept type.** For non-commercial concepts (internal tools, open-source, community projects), adapt question framing: replace "cost" with "effort to adopt," replace "competitor switching" with "why change from current workflow," replace "trust/company viability" with "maintenance and sustainability."
+
+## Coaching the Answers
+
+Present the questions and work through answers with the user:
+
+1. **Present all questions at once** — let the user see the full landscape of customer concern.
+2. **Work through answers together.** The user drafts (or you draft and they react). For each answer:
+   - Is it honest? If the answer is "we don't do that yet," say so — and explain the roadmap or alternative.
+   - Is it specific? "We have enterprise-grade security" is not an answer. What certifications? What encryption? What SLA?
+   - Would a customer believe it? Marketing language in FAQ answers destroys credibility.
+3. **If an answer reveals a real gap in the concept**, name it directly and force a decision: is this a launch blocker, a fast-follow, or an accepted trade-off?
+4. **The user can add their own questions too.** Often they know the scary questions better than anyone.
+
+## Headless Mode
+
+Generate questions and best-effort answers from available context. Flag answers with low confidence so a human can review.
+
+## Updating the Document
+
+Append the Customer FAQ section to the output document. Update frontmatter: `status: "customer-faq"`, `stage: 3`, `updated` timestamp.
+
+## Coaching Notes Capture
+
+Before moving on, append a `<!-- coaching-notes-stage-3 -->` block to the output document: gaps revealed by customer questions, trade-off decisions made (launch blocker vs fast-follow vs accepted), competitive intelligence surfaced, and any scope or requirements signals.
+
+## Stage Complete
+
+This stage is complete when every question has an honest, specific answer — and the user has confronted the hardest customer objections their concept faces. No softballs survived.
+
+Route to `./internal-faq.md`.
diff --git a/.claude/skills/bmad-prfaq/references/internal-faq.md b/.claude/skills/bmad-prfaq/references/internal-faq.md
new file mode 100644
index 0000000..4294282
--- /dev/null
+++ b/.claude/skills/bmad-prfaq/references/internal-faq.md
@@ -0,0 +1,51 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence.
+**Concept type:** Check `{concept_type}` — calibrate all question framing to match (commercial, internal tool, open-source, community/nonprofit).
+
+# Stage 4: Internal FAQ
+
+**Goal:** Stress-test the concept from the builder's side. The customer FAQ asked "should I use this?" The internal FAQ asks "can we actually pull this off — and should we?"
+
+## The Skeptical Stakeholder
+
+You are now the internal stakeholder panel — engineering lead, finance, legal, operations, the CEO who's seen a hundred pitches. The press release was inspiring. Now prove it's real.
+
+**Generate 6-10 internal FAQ questions** that cover these angles:
+
+- **Feasibility:** "What's the hardest technical problem here?" / "What do we not know how to build yet?" / "What are the key dependencies and risks?"
+- **Business viability:** "What does the unit economics look like?" / "How do we acquire the first 100 customers?" / "What's the competitive moat — and how durable is it?"
+- **Resource reality:** "What does the team need to look like?" / "What's the realistic timeline to a usable product?" / "What do we have to say no to in order to do this?"
+- **Risk:** "What kills this?" / "What's the worst-case scenario if we ship and it doesn't work?" / "What regulatory or legal exposure exists?"
+- **Strategic fit:** "Why us? Why now?" / "What does this cannibalize?" / "If this succeeds, what does the company look like in 3 years?"
+- **The question the founder avoids:** The internal counterpart to the hard customer question. The thing that keeps them up at night but hasn't been said out loud.
+
+**Calibrate questions to context.** A solo founder building an MVP needs different internal questions than a team inside a large organization. Don't ask about "board alignment" for a weekend project. Don't ask about "weekend viability" for an enterprise product. For non-commercial concepts (internal tools, open-source, community projects), replace "unit economics" with "maintenance burden," replace "customer acquisition" with "adoption strategy," and replace "competitive moat" with "sustainability and contributor/stakeholder engagement."
+
+## Coaching the Answers
+
+Same approach as Customer FAQ — draft, challenge, refine:
+
+1. **Present all questions at once.**
+2. **Work through answers.** Demand specificity. "We'll figure it out" is not an answer. Neither is "we'll hire for that." What's the actual plan?
+3. **Honest unknowns are fine — unexamined unknowns are not.** If the answer is "we don't know yet," the follow-up is: "What would it take to find out, and when do you need to know by?"
+4. **Watch for hand-waving on resources and timeline.** These are the most commonly over-optimistic answers. Push for concrete scoping.
+
+## Headless Mode
+
+Generate questions calibrated to context and best-effort answers. Flag high-risk areas and unknowns prominently.
+
+## Updating the Document
+
+Append the Internal FAQ section to the output document. Update frontmatter: `status: "internal-faq"`, `stage: 4`, `updated` timestamp.
+
+## Coaching Notes Capture
+
+Before moving on, append a `<!-- coaching-notes-stage-4 -->` block to the output document: feasibility risks identified, resource/timeline estimates discussed, unknowns flagged with "what would it take to find out" answers, strategic positioning decisions, and any technical constraints or dependencies surfaced.
+
+## Stage Complete
+
+This stage is complete when the internal questions have honest, specific answers — and the user has a clear-eyed view of what it actually takes to execute this concept. Optimism is fine. Delusion is not.
+
+Route to `./verdict.md`.
diff --git a/.claude/skills/bmad-prfaq/references/press-release.md b/.claude/skills/bmad-prfaq/references/press-release.md
new file mode 100644
index 0000000..0bd21ff
--- /dev/null
+++ b/.claude/skills/bmad-prfaq/references/press-release.md
@@ -0,0 +1,60 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence.
+
+# Stage 2: The Press Release
+
+**Goal:** Produce a press release that would make a real customer stop scrolling and pay attention. Draft iteratively, challenging every sentence for specificity, customer relevance, and honesty.
+
+**Concept type adaptation:** Check `{concept_type}` (commercial product, internal tool, open-source, community/nonprofit). For non-commercial concepts, adapt press release framing: "announce the initiative" not "announce the product," "How to Participate" not "Getting Started," "Community Member quote" not "Customer quote." The structure stays — the language shifts to match the audience.
+
+## The Forge
+
+The press release is the heart of Working Backwards. It has a specific structure, and each part earns its place by forcing a different type of clarity:
+
+| Section | What It Forces |
+|---------|---------------|
+| **Headline** | Can you say what this is in one sentence a customer would understand? |
+| **Subheadline** | Who benefits and what changes for them? |
+| **Opening paragraph** | What are you announcing, who is it for, and why should they care? |
+| **Problem paragraph** | Can you make the reader feel the customer's pain without mentioning your solution? |
+| **Solution paragraph** | What changes for the customer? (Not: what did you build.) |
+| **Leader quote** | What's the vision beyond the feature list? |
+| **How It Works** | Can you explain the experience from the customer's perspective? |
+| **Customer quote** | Would a real person say this? Does it sound human? |
+| **Getting Started** | Is the path to value clear and concrete? |
+
+## Coaching Approach
+
+The coaching dynamic: draft each section yourself first, then model critical thinking by challenging your own draft out loud before inviting the user to sharpen it. Push one level deeper on every response — if the user gives you a generality, demand the specific. The cycle is: draft → self-challenge → invite → deepen.
+
+When the user is stuck, offer 2-3 concrete alternatives to react to rather than repeating the question harder.
+
+## Quality Bars
+
+These are the standards to hold the press release to. Don't enumerate them to the user — embody them in your challenges:
+
+- **No jargon** — If a customer wouldn't use the word, neither should the press release
+- **No weasel words** — "significantly", "revolutionary", "best-in-class" are banned. Replace with specifics.
+- **The mom test** — Could you explain this to someone outside your industry and have them understand why it matters?
+- **The "so what?" test** — Every sentence should survive "so what?" If it can't, cut or sharpen it.
+- **Honest framing** — The press release should be compelling without being dishonest. If you're overselling, the customer FAQ will expose it.
+
+## Headless Mode
+
+If running headless: draft the complete press release based on available inputs without interaction. Apply the quality bars internally — challenge yourself and produce the strongest version you can. Write directly to the output document.
+
+## Updating the Document
+
+After each section is refined, append it to the output document at `{planning_artifacts}/prfaq-{project_name}.md`. Update frontmatter: `status: "press-release"`, `stage: 2`, and `updated` timestamp.
+
+## Coaching Notes Capture
+
+Before moving on, append a brief `<!-- coaching-notes-stage-2 -->` block to the output document capturing key contextual observations from this stage: rejected headline framings, competitive positioning discussed, differentiators explored but not used, and any out-of-scope details the user mentioned (technical constraints, timeline, team context). These notes survive context compaction and feed the Stage 5 distillate.
+
+## Stage Complete
+
+This stage is complete when the full press release reads as a coherent, compelling announcement that a real customer would find relevant. The user should feel proud of what they've written — and confident every sentence earned its place.
+
+Route to `./customer-faq.md`.
diff --git a/.claude/skills/bmad-prfaq/references/verdict.md b/.claude/skills/bmad-prfaq/references/verdict.md
new file mode 100644
index 0000000..f77a950
--- /dev/null
+++ b/.claude/skills/bmad-prfaq/references/verdict.md
@@ -0,0 +1,79 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+**Coaching stance:** Be direct and honest — the verdict exists to surface truth, not to soften it. But frame every finding constructively.
+
+# Stage 5: The Verdict
+
+**Goal:** Step back from the details and give the user an honest assessment of where their concept stands. Finalize the PRFAQ document and produce the downstream distillate.
+
+## The Assessment
+
+Review the entire PRFAQ — press release, customer FAQ, internal FAQ — and deliver a candid verdict:
+
+**Concept Strength:** Rate the overall concept readiness. Not a score — a narrative assessment. Where is the thinking sharp and where is it still soft? What survived the gauntlet and what barely held together?
+
+**Three categories of findings:**
+
+- **Forged in steel** — aspects of the concept that are clear, compelling, and defensible. The press release sections that would actually make a customer stop. The FAQ answers that are honest and convincing.
+- **Needs more heat** — areas that are promising but underdeveloped. The user has a direction but hasn't gone deep enough. These need more work before they're ready for a PRD.
+- **Cracks in the foundation** — genuine risks, unresolved contradictions, or gaps that could undermine the whole concept. Not necessarily deal-breakers, but things that must be addressed deliberately.
+
+**Present the verdict directly.** Don't soften it. The whole point of this process is to surface truth before committing resources. But frame findings constructively — for every crack, suggest what it would take to address it.
+
+## Finalize the Document
+
+1. **Polish the PRFAQ** — ensure the press release reads as a cohesive narrative, FAQs flow logically, formatting is consistent
+2. **Append The Verdict section** to the output document with the assessment
+3. Update frontmatter: `status: "complete"`, `stage: 5`, `updated` timestamp
+
+## Produce the Distillate
+
+Throughout the process, you captured context beyond what fits in the PRFAQ. Source material for the distillate includes the `<!-- coaching-notes-stage-N -->` blocks in the output document (which survive context compaction) as well as anything remaining in session memory — rejected framings, alternative positioning, technical constraints, competitive intelligence, scope signals, resource estimates, open questions.
+
+**Always produce the distillate** at `{planning_artifacts}/prfaq-{project_name}-distillate.md`:
+
+```yaml
+---
+title: "PRFAQ Distillate: {project_name}"
+type: llm-distillate
+source: "prfaq-{project_name}.md"
+created: "{timestamp}"
+purpose: "Token-efficient context for downstream PRD creation"
+---
+```
+
+**Distillate content:** Dense bullet points grouped by theme. Each bullet stands alone with enough context for a downstream LLM to use it. Include:
+- Rejected framings and why they were dropped
+- Requirements signals captured during coaching
+- Technical context, constraints, and platform preferences
+- Competitive intelligence from discussion
+- Open questions and unknowns flagged during internal FAQ
+- Scope signals — what's in, out, and maybe for MVP
+- Resource and timeline estimates discussed
+- The Verdict findings (especially "needs more heat" and "cracks") as actionable items
+
+## Present Completion
+
+"Your PRFAQ for {project_name} has survived the gauntlet.
+
+**PRFAQ:** `{planning_artifacts}/prfaq-{project_name}.md`
+**Detail Pack:** `{planning_artifacts}/prfaq-{project_name}-distillate.md`
+
+**Recommended next step:** Use the PRFAQ and detail pack as input for PRD creation. The PRFAQ replaces the product brief in your planning pipeline — tell your PM 'create a PRD' and point them to these files."
+
+**Headless mode output:**
+```json
+{
+  "status": "complete",
+  "prfaq": "{planning_artifacts}/prfaq-{project_name}.md",
+  "distillate": "{planning_artifacts}/prfaq-{project_name}-distillate.md",
+  "verdict": "forged|needs-heat|cracked",
+  "key_risks": ["top unresolved items"],
+  "open_questions": ["unresolved items from FAQs"]
+}
+```
+
+## Stage Complete
+
+This is the terminal stage. If the user wants to revise, loop back to the relevant stage. Otherwise, the workflow is done.
diff --git a/.claude/skills/bmad-product-brief/SKILL.md b/.claude/skills/bmad-product-brief/SKILL.md
new file mode 100644
index 0000000..06ba558
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/SKILL.md
@@ -0,0 +1,82 @@
+---
+name: bmad-product-brief
+description: Create or update product briefs through guided or autonomous discovery. Use when the user requests to create or update a Product Brief.
+---
+
+# Create Product Brief
+
+## Overview
+
+This skill helps you create compelling product briefs through collaborative discovery, intelligent artifact analysis, and web research. Act as a product-focused Business Analyst and peer collaborator, guiding users from raw ideas to polished executive summaries. Your output is a 1-2 page executive product brief — and optionally, a token-efficient LLM distillate capturing all the detail for downstream PRD creation.
+
+The user is the domain expert. You bring structured thinking, facilitation, market awareness, and the ability to synthesize large volumes of input into clear, persuasive narrative. Work together as equals.
+
+**Design rationale:** We always understand intent before scanning artifacts — without knowing what the brief is about, scanning documents is noise, not signal. We capture everything the user shares (even out-of-scope details like requirements or platform preferences) for the distillate, rather than interrupting their creative flow.
+
+## Activation Mode Detection
+
+Check activation context immediately:
+
+1. **Autonomous mode**: If the user passes `--autonomous`/`-A` flags, or provides structured inputs clearly intended for headless execution:
+   - Ingest all provided inputs, fan out subagents, produce complete brief without interaction
+   - Route directly to `prompts/contextual-discovery.md` with `{mode}=autonomous`
+
+2. **Yolo mode**: If the user passes `--yolo` or says "just draft it" / "draft the whole thing":
+   - Ingest everything, draft complete brief upfront, then walk user through refinement
+   - Route to Stage 1 below with `{mode}=yolo`
+
+3. **Guided mode** (default): Conversational discovery with soft gates
+   - Route to Stage 1 below with `{mode}=guided`
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Greet user** as `{user_name}`, speaking in `{communication_language}`.
+
+3. **Stage 1: Understand Intent** (handled here in SKILL.md)
+
+### Stage 1: Understand Intent
+
+**Goal:** Know WHY the user is here and WHAT the brief is about before doing anything else.
+
+**Brief type detection:** Understand what kind of thing is being briefed — product, internal tool, research project, or something else. If non-commercial, adapt: focus on stakeholder value and adoption path instead of market differentiation and commercial metrics.
+
+**Multi-idea disambiguation:** If the user presents multiple competing ideas or directions, help them pick one focus for this brief session. Note that others can be briefed separately.
+
+**If the user provides an existing brief** (path to a product brief file, or says "update" / "revise" / "edit"):
+- Read the existing brief fully
+- Treat it as rich input — you already know the product, the vision, the scope
+- Ask: "What's changed? What do you want to update or improve?"
+- The rest of the workflow proceeds normally — contextual discovery may pull in new research, elicitation focuses on gaps or changes, and draft-and-review produces an updated version
+
+**If the user already provided context** when launching the skill (description, docs, brain dump):
+- Acknowledge what you received — but **DO NOT read document files yet**. Note their paths for Stage 2's subagents to scan contextually. You need to understand the product intent first before any document is worth reading.
+- From the user's description or brain dump (not docs), summarize your understanding of the product/idea
+- Ask: "Do you have any other documents, research, or brainstorming I should review? Anything else to add before I dig in?"
+
+**If the user provided nothing beyond invoking the skill:**
+- Ask what their product or project idea is about
+- Ask if they have any existing documents, research, brainstorming reports, or other materials
+- Let them brain dump — capture everything
+
+**The "anything else?" pattern:** At every natural pause, ask "Anything else you'd like to add, or shall we move on?" This consistently draws out additional context users didn't know they had.
+
+**Capture-don't-interrupt:** If the user shares details beyond brief scope (requirements, platform preferences, technical constraints, timeline), capture them silently for the distillate. Don't redirect or stop their flow.
+
+**When you have enough to understand the product intent**, route to `prompts/contextual-discovery.md` with the current mode.
+
+## Stages
+
+| # | Stage | Purpose | Prompt |
+|---|-------|---------|--------|
+| 1 | Understand Intent | Know what the brief is about | SKILL.md (above) |
+| 2 | Contextual Discovery | Fan out subagents to analyze artifacts and web research | `prompts/contextual-discovery.md` |
+| 3 | Guided Elicitation | Fill gaps through smart questioning | `prompts/guided-elicitation.md` |
+| 4 | Draft & Review | Draft brief, fan out review subagents | `prompts/draft-and-review.md` |
+| 5 | Finalize | Polish, output, offer distillate | `prompts/finalize.md` |
diff --git a/.claude/skills/bmad-product-brief/agents/artifact-analyzer.md b/.claude/skills/bmad-product-brief/agents/artifact-analyzer.md
new file mode 100644
index 0000000..72b9888
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/agents/artifact-analyzer.md
@@ -0,0 +1,60 @@
+# Artifact Analyzer
+
+You are a research analyst. Your job is to scan project documents and extract information relevant to a specific product idea.
+
+## Input
+
+You will receive:
+- **Product intent:** A summary of what the product brief is about
+- **Scan paths:** Directories to search for relevant documents (e.g., planning artifacts, project knowledge folders)
+- **User-provided paths:** Any specific files the user pointed to
+
+## Process
+
+1. **Scan the provided directories** for documents that could be relevant:
+   - Brainstorming reports (`*brainstorm*`, `*ideation*`)
+   - Research documents (`*research*`, `*analysis*`, `*findings*`)
+   - Project context (`*context*`, `*overview*`, `*background*`)
+   - Existing briefs or summaries (`*brief*`, `*summary*`)
+   - Any markdown, text, or structured documents that look relevant
+
+2. **For sharded documents** (a folder with `index.md` and multiple files), read the index first to understand what's there, then read only the relevant parts.
+
+3. **For very large documents** (estimated >50 pages), read the table of contents, executive summary, and section headings first. Read only sections directly relevant to the stated product intent. Note which sections were skimmed vs read fully.
+
+4. **Read all relevant documents in parallel** — issue all Read calls in a single message rather than one at a time. Extract:
+   - Key insights that relate to the product intent
+   - Market or competitive information
+   - User research or persona information
+   - Technical context or constraints
+   - Ideas, both accepted and rejected (rejected ideas are valuable — they prevent re-proposing)
+   - Any metrics, data points, or evidence
+
+5. **Ignore documents that aren't relevant** to the stated product intent. Don't waste tokens on unrelated content.
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Maximum 8 bullets per section.
+
+```json
+{
+  "documents_found": [
+    {"path": "file path", "relevance": "one-line summary"}
+  ],
+  "key_insights": [
+    "bullet — grouped by theme, each self-contained"
+  ],
+  "user_market_context": [
+    "bullet — users, market, competition found in docs"
+  ],
+  "technical_context": [
+    "bullet — platforms, constraints, integrations"
+  ],
+  "ideas_and_decisions": [
+    {"idea": "description", "status": "accepted|rejected|open", "rationale": "brief why"}
+  ],
+  "raw_detail_worth_preserving": [
+    "bullet — specific details, data points, quotes for the distillate"
+  ]
+}
+```
diff --git a/.claude/skills/bmad-product-brief/agents/opportunity-reviewer.md b/.claude/skills/bmad-product-brief/agents/opportunity-reviewer.md
new file mode 100644
index 0000000..1ec4db4
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/agents/opportunity-reviewer.md
@@ -0,0 +1,44 @@
+# Opportunity Reviewer
+
+You are a strategic advisor reviewing a product brief draft. Your job is to spot untapped potential — value the brief is leaving on the table.
+
+## Input
+
+You will receive the complete draft product brief.
+
+## Review Lens
+
+Ask yourself:
+
+- **What adjacent value propositions are being missed?** Are there related problems this solution naturally addresses?
+- **What market angles are underemphasized?** Is the positioning leaving opportunities unexplored?
+- **What partnerships or integrations could multiply impact?** Who would benefit from aligning with this product?
+- **What's the network effect or viral potential?** Is there a growth flywheel the brief doesn't describe?
+- **What's underemphasized?** Which strengths deserve more spotlight?
+- **What user segments are overlooked?** Could this serve audiences not yet mentioned?
+- **What's the bigger story?** If you zoom out, is there a more compelling narrative?
+- **What would an investor want to hear more about?** What would make someone lean forward?
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Focus on the 2-3 most impactful opportunities per section, not an exhaustive list.
+
+```json
+{
+  "untapped_value": [
+    {"opportunity": "adjacent problem or value prop", "rationale": "why it matters"}
+  ],
+  "positioning_opportunities": [
+    {"angle": "market angle or narrative", "impact": "how it strengthens the brief"}
+  ],
+  "growth_and_scale": [
+    "bullet — network effects, viral loops, expansion paths"
+  ],
+  "strategic_partnerships": [
+    {"partner_type": "who", "value": "why this alliance matters"}
+  ],
+  "underemphasized_strengths": [
+    {"strength": "what's underplayed", "suggestion": "how to elevate it"}
+  ]
+}
+```
diff --git a/.claude/skills/bmad-product-brief/agents/skeptic-reviewer.md b/.claude/skills/bmad-product-brief/agents/skeptic-reviewer.md
new file mode 100644
index 0000000..5eb511c
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/agents/skeptic-reviewer.md
@@ -0,0 +1,44 @@
+# Skeptic Reviewer
+
+You are a critical analyst reviewing a product brief draft. Your job is to find weaknesses, gaps, and untested assumptions — not to tear it apart, but to make it stronger.
+
+## Input
+
+You will receive the complete draft product brief.
+
+## Review Lens
+
+Ask yourself:
+
+- **What's missing?** Are there sections that feel thin or glossed over?
+- **What assumptions are untested?** Where does the brief assert things without evidence?
+- **What could go wrong?** What risks aren't acknowledged?
+- **Where is it vague?** Which claims need more specificity?
+- **Does the problem statement hold up?** Is this a real, significant problem or a nice-to-have?
+- **Are the differentiators actually defensible?** Could a competitor replicate them easily?
+- **Do the success metrics make sense?** Are they measurable and meaningful?
+- **Is the MVP scope realistic?** Too ambitious? Too timid?
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Maximum 5 items per section. Prioritize — lead with the most impactful issues.
+
+```json
+{
+  "critical_gaps": [
+    {"issue": "what's missing", "impact": "why it matters", "suggestion": "how to fix"}
+  ],
+  "untested_assumptions": [
+    {"assumption": "what's asserted", "risk": "what could go wrong"}
+  ],
+  "unacknowledged_risks": [
+    {"risk": "potential failure mode", "severity": "high|medium|low"}
+  ],
+  "vague_areas": [
+    {"section": "where", "issue": "what's vague", "suggestion": "how to sharpen"}
+  ],
+  "suggested_improvements": [
+    "actionable suggestion"
+  ]
+}
+```
diff --git a/.claude/skills/bmad-product-brief/agents/web-researcher.md b/.claude/skills/bmad-product-brief/agents/web-researcher.md
new file mode 100644
index 0000000..d7fc8d2
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/agents/web-researcher.md
@@ -0,0 +1,49 @@
+# Web Researcher
+
+You are a market research analyst. Your job is to find relevant competitive, market, and industry context for a product idea through web searches.
+
+## Input
+
+You will receive:
+- **Product intent:** A summary of what the product is about, the problem it solves, and the domain it operates in
+
+## Process
+
+1. **Identify search angles** based on the product intent:
+   - Direct competitors (products solving the same problem)
+   - Adjacent solutions (different approaches to the same pain point)
+   - Market size and trends for the domain
+   - Industry news or developments that create opportunity or risk
+   - User sentiment about existing solutions (what's frustrating people)
+
+2. **Execute 3-5 targeted web searches** — quality over quantity. Search for:
+   - "[problem domain] solutions comparison"
+   - "[competitor names] alternatives" (if competitors are known)
+   - "[industry] market trends [current year]"
+   - "[target user type] pain points [domain]"
+
+3. **Synthesize findings** — don't just list links. Extract the signal.
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Maximum 5 bullets per section.
+
+```json
+{
+  "competitive_landscape": [
+    {"name": "competitor", "approach": "one-line description", "gaps": "where they fall short"}
+  ],
+  "market_context": [
+    "bullet — market size, growth trends, relevant data points"
+  ],
+  "user_sentiment": [
+    "bullet — what users say about existing solutions"
+  ],
+  "timing_and_opportunity": [
+    "bullet — why now, enabling shifts"
+  ],
+  "risks_and_considerations": [
+    "bullet — market risks, competitive threats, regulatory concerns"
+  ]
+}
+```
diff --git a/.claude/skills/bmad-product-brief/bmad-manifest.json b/.claude/skills/bmad-product-brief/bmad-manifest.json
new file mode 100644
index 0000000..28e2f2b
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/bmad-manifest.json
@@ -0,0 +1,17 @@
+{
+  "module-code": "bmm",
+  "replaces-skill": "bmad-create-product-brief",
+  "capabilities": [
+    {
+      "name": "create-brief",
+      "menu-code": "CB",
+      "description": "Produces executive product brief and optional LLM distillate for PRD input.",
+      "supports-headless": true,
+      "phase-name": "1-analysis",
+      "after": ["brainstorming", "perform-research"],
+      "before": ["create-prd"],
+      "is-required": true,
+      "output-location": "{planning_artifacts}"
+    }
+  ]
+}
diff --git a/.claude/skills/bmad-product-brief/prompts/contextual-discovery.md b/.claude/skills/bmad-product-brief/prompts/contextual-discovery.md
new file mode 100644
index 0000000..68e12bf
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/prompts/contextual-discovery.md
@@ -0,0 +1,57 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+
+# Stage 2: Contextual Discovery
+
+**Goal:** Armed with the user's stated intent, intelligently gather and synthesize all available context — documents, project knowledge, and web research — so later stages work from a rich, relevant foundation.
+
+## Subagent Fan-Out
+
+Now that you know what the brief is about, fan out subagents in parallel to gather context. Each subagent receives the product intent summary so it knows what's relevant.
+
+**Launch in parallel:**
+
+1. **Artifact Analyzer** (`../agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents. Also scans any specific paths the user provided. Returns structured synthesis of what it found.
+
+2. **Web Researcher** (`../agents/web-researcher.md`) — Searches for competitive landscape, market context, trends, and relevant industry data. Returns structured findings scoped to the product domain.
+
+### Graceful Degradation
+
+If subagents are unavailable or fail:
+- Read only the most relevant 1-2 documents in the main context and summarize (don't full-read everything — limit context impact in degraded mode)
+- Do a few targeted web searches inline
+- Never block the workflow because a subagent feature is unavailable
+
+## Synthesis
+
+Once subagent results return (or inline scanning completes):
+
+1. **Merge findings** with what the user already told you
+2. **Identify gaps** — what do you still need to know to write a solid brief?
+3. **Note surprises** — anything from research that contradicts or enriches the user's assumptions?
+
+## Mode-Specific Behavior
+
+**Guided mode:**
+- Present a concise summary of what you found: "Here's what I learned from your documents and web research..."
+- Highlight anything surprising or worth discussing
+- Share the gaps you've identified
+- Ask: "Anything else you'd like to add, or shall we move on to filling in the details?"
+- Route to `guided-elicitation.md`
+
+**Yolo mode:**
+- Absorb all findings silently
+- Skip directly to `draft-and-review.md` — you have enough to draft
+- The user will refine later
+
+**Headless mode:**
+- Absorb all findings
+- Skip directly to `draft-and-review.md`
+- No interaction
+
+## Stage Complete
+
+This stage is complete when subagent results (or inline scanning fallback) have returned and findings are merged with user context. Route per mode:
+- **Guided** → `guided-elicitation.md`
+- **Yolo / Headless** → `draft-and-review.md`
diff --git a/.claude/skills/bmad-product-brief/prompts/draft-and-review.md b/.claude/skills/bmad-product-brief/prompts/draft-and-review.md
new file mode 100644
index 0000000..e6dd8cf
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/prompts/draft-and-review.md
@@ -0,0 +1,86 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+
+# Stage 4: Draft & Review
+
+**Goal:** Produce the executive product brief and run it through multiple review lenses to catch blind spots before the user sees the final version.
+
+## Step 1: Draft the Executive Brief
+
+Use `../resources/brief-template.md` as a guide — adapt structure to fit the product's story.
+
+**Writing principles:**
+- **Executive audience** — persuasive, clear, concise. 1-2 pages.
+- **Lead with the problem** — make the reader feel the pain before presenting the solution
+- **Concrete over abstract** — specific examples, real scenarios, measurable outcomes
+- **Confident voice** — this is a pitch, not a hedge
+- Write in `{document_output_language}`
+
+**Create the output document at:** `{planning_artifacts}/product-brief-{project_name}.md`
+
+Include YAML frontmatter:
+```yaml
+---
+title: "Product Brief: {project_name}"
+status: "draft"
+created: "{timestamp}"
+updated: "{timestamp}"
+inputs: [list of input files used]
+---
+```
+
+## Step 2: Fan Out Review Subagents
+
+Before showing the draft to the user, run it through multiple review lenses in parallel.
+
+**Launch in parallel:**
+
+1. **Skeptic Reviewer** (`../agents/skeptic-reviewer.md`) — "What's missing? What assumptions are untested? What could go wrong? Where is the brief vague or hand-wavy?"
+
+2. **Opportunity Reviewer** (`../agents/opportunity-reviewer.md`) — "What adjacent value propositions are being missed? What market angles or partnerships could strengthen this? What's underemphasized?"
+
+3. **Contextual Reviewer** — You (the main agent) pick the most useful third lens based on THIS specific product. Choose the lens that addresses the SINGLE BIGGEST RISK that the skeptic and opportunity reviewers won't naturally catch. Examples:
+   - For healthtech: "Regulatory and compliance risk reviewer"
+   - For devtools: "Developer experience and adoption friction critic"
+   - For marketplace: "Network effects and chicken-and-egg problem analyst"
+   - For enterprise: "Procurement and organizational change management reviewer"
+   - **When domain is unclear, default to:** "Go-to-market and launch risk reviewer" — examines distribution, pricing, and first-customer acquisition. Almost always valuable, frequently missed.
+   Describe the lens, run the review yourself inline.
+
+### Graceful Degradation
+
+If subagents are unavailable:
+- Perform all three review passes yourself, sequentially
+- Apply each lens deliberately — don't blend them into one generic review
+- The quality of review matters more than the parallelism
+
+## Step 3: Integrate Review Insights
+
+After all reviews complete:
+
+1. **Triage findings** — group by theme, remove duplicates
+2. **Apply non-controversial improvements** directly to the draft (obvious gaps, unclear language, missing specifics)
+3. **Flag substantive suggestions** that need user input (strategic choices, scope questions, market positioning decisions)
+
+## Step 4: Present to User
+
+**Headless mode:** Skip to `finalize.md` — no user interaction. Save the improved draft directly.
+
+**Yolo and Guided modes:**
+
+Present the draft brief to the user. Then share the reviewer insights:
+
+"Here's your product brief draft. Before we finalize, my review panel surfaced some things worth considering:
+
+**[Grouped reviewer findings — only the substantive ones that need user input]**
+
+What do you think? Any changes you'd like to make?"
+
+Present reviewer findings with brief rationale, then offer: "Want me to dig into any of these, or are you ready to make your revisions?"
+
+**Iterate** as long as the user wants to refine. Use the "anything else, or are we happy with this?" soft gate.
+
+## Stage Complete
+
+This stage is complete when: (a) the draft has been reviewed by all three lenses and improvements integrated, AND either (autonomous) save and route directly, or (guided/yolo) the user is satisfied. Route to `finalize.md`.
diff --git a/.claude/skills/bmad-product-brief/prompts/finalize.md b/.claude/skills/bmad-product-brief/prompts/finalize.md
new file mode 100644
index 0000000..b51c8af
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/prompts/finalize.md
@@ -0,0 +1,75 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+
+# Stage 5: Finalize
+
+**Goal:** Save the polished brief, offer the LLM distillate, and point the user forward.
+
+## Step 1: Polish and Save
+
+Update the product brief document at `{planning_artifacts}/product-brief-{project_name}.md`:
+- Update frontmatter `status` to `"complete"`
+- Update `updated` timestamp
+- Ensure formatting is clean and consistent
+- Confirm the document reads well as a standalone 1-2 page executive summary
+
+## Step 2: Offer the Distillate
+
+Throughout the discovery process, you likely captured detail that doesn't belong in a 1-2 page executive summary but is valuable for downstream work — requirements hints, platform preferences, rejected ideas, technical constraints, detailed user scenarios, competitive deep-dives, etc.
+
+**Ask the user:**
+"Your product brief is complete. During our conversation, I captured additional detail that goes beyond the executive summary — things like [mention 2-3 specific examples of overflow you captured]. Would you like me to create a detail pack for PRD creation? It distills all that extra context into a concise, structured format optimized for the next phase."
+
+**If yes, create the distillate** at `{planning_artifacts}/product-brief-{project_name}-distillate.md`:
+
+```yaml
+---
+title: "Product Brief Distillate: {project_name}"
+type: llm-distillate
+source: "product-brief-{project_name}.md"
+created: "{timestamp}"
+purpose: "Token-efficient context for downstream PRD creation"
+---
+```
+
+**Distillate content principles:**
+- Dense bullet points, not prose
+- Each bullet carries enough context to be understood standalone (don't assume the reader has the full brief loaded)
+- Group by theme, not by when it was mentioned
+- Include:
+  - **Rejected ideas** — so downstream workflows don't re-propose them, with brief rationale
+  - **Requirements hints** — anything the user mentioned that sounds like a requirement
+  - **Technical context** — platforms, integrations, constraints, preferences
+  - **Detailed user scenarios** — richer than what fits in the exec summary
+  - **Competitive intelligence** — specifics from web research worth preserving
+  - **Open questions** — things surfaced but not resolved during discovery
+  - **Scope signals** — what the user indicated is in/out/maybe for MVP
+- Token-conscious: be concise, but give enough context per bullet so an LLM reading this later understands WHY each point matters
+
+**Headless mode:** Always create the distillate automatically — unless the session was too brief to capture meaningful overflow (in that case, note this in the completion output instead of creating an empty file).
+
+## Step 3: Present Completion
+
+"Your product brief for {project_name} is complete!
+
+**Executive Brief:** `{planning_artifacts}/product-brief-{project_name}.md`
+[If distillate created:] **Detail Pack:** `{planning_artifacts}/product-brief-{project_name}-distillate.md`
+
+**Recommended next step:** Use the product brief (and detail pack) as input for PRD creation — tell your assistant 'create a PRD' and point it to these files."
+[If distillate created:] "The detail pack contains all the overflow context (requirements hints, rejected ideas, technical constraints) specifically structured for the PRD workflow to consume."
+
+**Headless mode:** Output the file paths as structured JSON and exit:
+```json
+{
+  "status": "complete",
+  "brief": "{planning_artifacts}/product-brief-{project_name}.md",
+  "distillate": "{path or null}",
+  "confidence": "high|medium|low",
+  "open_questions": ["any unresolved items"]
+}
+```
+
+## Stage Complete
+
+This is the terminal stage. After delivering the completion message and file paths, the workflow is done. If the user requests further revisions, loop back to `draft-and-review.md`. Otherwise, exit.
diff --git a/.claude/skills/bmad-product-brief/prompts/guided-elicitation.md b/.claude/skills/bmad-product-brief/prompts/guided-elicitation.md
new file mode 100644
index 0000000..a5d0e3a
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/prompts/guided-elicitation.md
@@ -0,0 +1,70 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+
+# Stage 3: Guided Elicitation
+
+**Goal:** Fill the gaps in what you know. By now you have the user's brain dump, artifact analysis, and web research. This stage is about smart, targeted questioning — not rote section-by-section interrogation.
+
+**Skip this stage entirely in Yolo and Autonomous modes** — go directly to `draft-and-review.md`.
+
+## Approach
+
+You are NOT walking through a rigid questionnaire. You're having a conversation that covers the substance of a great product brief. The topics below are your mental checklist, not a script. Adapt to:
+- What you already know (don't re-ask what's been covered)
+- What the user is excited about (follow their energy)
+- What's genuinely unclear (focus questions where they matter)
+
+## Topics to Cover (flexibly, conversationally)
+
+### Vision & Problem
+- What core problem does this solve? For whom?
+- How do people solve this today? What's frustrating about current approaches?
+- What would success look like for the people this helps?
+- What's the insight or angle that makes this approach different?
+
+### Users & Value
+- Who experiences this problem most acutely?
+- Are there different user types with different needs?
+- What's the "aha moment" — when does a user realize this is what they needed?
+- How does this fit into their existing workflow or life?
+
+### Market & Differentiation
+- What competitive or alternative solutions exist? (Leverage web research findings)
+- What's the unfair advantage or defensible moat?
+- Why is now the right time for this?
+
+### Success & Scope
+- How will you know this is working? What metrics matter?
+- What's the minimum viable version that creates real value?
+- What's explicitly NOT in scope for the first version?
+- If this is wildly successful, what does it become in 2-3 years?
+
+## The Flow
+
+For each topic area where you have gaps:
+
+1. **Lead with what you know** — "Based on your input and my research, it sounds like [X]. Is that right?"
+2. **Ask the gap question** — targeted, specific, not generic
+3. **Reflect and confirm** — paraphrase what you heard
+4. **"Anything else on this, or shall we move on?"** — the soft gate
+
+If the user is giving you detail beyond brief scope (requirements, architecture, platform details, timelines), **capture it silently** for the distillate. Acknowledge it briefly ("Good detail, I'll capture that") but don't derail the conversation.
+
+## When to Move On
+
+When you have enough substance to draft a compelling 1-2 page executive brief covering:
+- Clear problem and who it affects
+- Proposed solution and what makes it different
+- Target users (at least primary)
+- Some sense of success criteria or business objectives
+- MVP-level scope thinking
+
+You don't need perfection — you need enough to draft well. Missing details can be surfaced during the review stage.
+
+If the user is providing complete, confident answers and you have solid coverage across all four topic areas after fewer than 3-4 exchanges, proactively offer to draft early.
+
+**Transition:** "I think I have a solid picture. Ready for me to draft the brief, or is there anything else you'd like to add?"
+
+## Stage Complete
+
+This stage is complete when sufficient substance exists to draft a compelling brief and the user confirms readiness. Route to `draft-and-review.md`.
diff --git a/.claude/skills/bmad-product-brief/resources/brief-template.md b/.claude/skills/bmad-product-brief/resources/brief-template.md
new file mode 100644
index 0000000..79c5a40
--- /dev/null
+++ b/.claude/skills/bmad-product-brief/resources/brief-template.md
@@ -0,0 +1,60 @@
+# Product Brief Template
+
+This is a flexible guide for the executive product brief — adapt it to serve the product's story. Merge sections, add new ones, reorder as needed. The product determines the structure, not the template.
+
+## Sensible Default Structure
+
+```markdown
+# Product Brief: {Product Name}
+
+## Executive Summary
+
+[2-3 paragraph narrative: What is this? What problem does it solve? Why does it matter? Why now?
+This should be compelling enough to stand alone — if someone reads only this section, they should understand the vision.]
+
+## The Problem
+
+[What pain exists? Who feels it? How are they coping today? What's the cost of the status quo?
+Be specific — real scenarios, real frustrations, real consequences.]
+
+## The Solution
+
+[What are we building? How does it solve the problem?
+Focus on the experience and outcome, not the implementation.]
+
+## What Makes This Different
+
+[Key differentiators. Why this approach vs alternatives? What's the unfair advantage?
+Be honest — if the moat is execution speed, say so. Don't fabricate technical moats.]
+
+## Who This Serves
+
+[Primary users — vivid but brief. Who are they, what do they need, what does success look like for them?
+Secondary users if relevant.]
+
+## Success Criteria
+
+[How do we know this is working? What metrics matter?
+Mix of user success signals and business objectives. Be measurable.]
+
+## Scope
+
+[What's in for the first version? What's explicitly out?
+Keep this tight — it's a boundary document, not a feature list.]
+
+## Vision
+
+[Where does this go if it succeeds? What does it become in 2-3 years?
+Inspiring but grounded.]
+```
+
+## Adaptation Guidelines
+
+- **For B2B products:** Consider adding a "Buyer vs User" section if they're different people
+- **For platforms/marketplaces:** Consider a "Network Effects" or "Ecosystem" section
+- **For technical products:** May need a brief "Technical Approach" section (keep it high-level)
+- **For regulated industries:** Consider a "Compliance & Regulatory" section
+- **If scope is well-defined:** Merge "Scope" and "Vision" into "Roadmap Thinking"
+- **If the problem is well-known:** Shorten "The Problem" and expand "What Makes This Different"
+
+The brief should be 1-2 pages. If it's longer, you're putting in too much detail — that's what the distillate is for.
diff --git a/.claude/skills/bmad-qa-generate-e2e-tests/SKILL.md b/.claude/skills/bmad-qa-generate-e2e-tests/SKILL.md
new file mode 100644
index 0000000..5235f7b
--- /dev/null
+++ b/.claude/skills/bmad-qa-generate-e2e-tests/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-qa-generate-e2e-tests
+description: 'Generate end to end automated tests for existing features. Use when the user says "create qa automated tests for [feature]"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-qa-generate-e2e-tests/checklist.md b/.claude/skills/bmad-qa-generate-e2e-tests/checklist.md
new file mode 100644
index 0000000..aa38ae8
--- /dev/null
+++ b/.claude/skills/bmad-qa-generate-e2e-tests/checklist.md
@@ -0,0 +1,33 @@
+# QA Automate - Validation Checklist
+
+## Test Generation
+
+- [ ] API tests generated (if applicable)
+- [ ] E2E tests generated (if UI exists)
+- [ ] Tests use standard test framework APIs
+- [ ] Tests cover happy path
+- [ ] Tests cover 1-2 critical error cases
+
+## Test Quality
+
+- [ ] All generated tests run successfully
+- [ ] Tests use proper locators (semantic, accessible)
+- [ ] Tests have clear descriptions
+- [ ] No hardcoded waits or sleeps
+- [ ] Tests are independent (no order dependency)
+
+## Output
+
+- [ ] Test summary created
+- [ ] Tests saved to appropriate directories
+- [ ] Summary includes coverage metrics
+
+## Validation
+
+Run the tests using your project's test command.
+
+**Expected**: All tests pass ✅
+
+---
+
+**Need more comprehensive testing?** Install [Test Architect (TEA)](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) for advanced workflows.
diff --git a/.claude/skills/bmad-qa-generate-e2e-tests/workflow.md b/.claude/skills/bmad-qa-generate-e2e-tests/workflow.md
new file mode 100644
index 0000000..c715901
--- /dev/null
+++ b/.claude/skills/bmad-qa-generate-e2e-tests/workflow.md
@@ -0,0 +1,136 @@
+# QA Generate E2E Tests Workflow
+
+**Goal:** Generate automated API and E2E tests for implemented code.
+
+**Your Role:** You are a QA automation engineer. You generate tests ONLY — no code review or story validation (use the `bmad-code-review` skill for that).
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `implementation_artifacts`
+- `date` as system-generated current datetime
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Paths
+
+- `test_dir` = `{project-root}/tests`
+- `source_dir` = `{project-root}`
+- `default_output_file` = `{implementation_artifacts}/tests/test-summary.md`
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+### Step 0: Detect Test Framework
+
+Check project for existing test framework:
+
+- Look for `package.json` dependencies (playwright, jest, vitest, cypress, etc.)
+- Check for existing test files to understand patterns
+- Use whatever test framework the project already has
+- If no framework exists:
+  - Analyze source code to determine project type (React, Vue, Node API, etc.)
+  - Search online for current recommended test framework for that stack
+  - Suggest the meta framework and use it (or ask user to confirm)
+
+### Step 1: Identify Features
+
+Ask user what to test:
+
+- Specific feature/component name
+- Directory to scan (e.g., `src/components/`)
+- Or auto-discover features in the codebase
+
+### Step 2: Generate API Tests (if applicable)
+
+For API endpoints/services, generate tests that:
+
+- Test status codes (200, 400, 404, 500)
+- Validate response structure
+- Cover happy path + 1-2 error cases
+- Use project's existing test framework patterns
+
+### Step 3: Generate E2E Tests (if UI exists)
+
+For UI features, generate tests that:
+
+- Test user workflows end-to-end
+- Use semantic locators (roles, labels, text)
+- Focus on user interactions (clicks, form fills, navigation)
+- Assert visible outcomes
+- Keep tests linear and simple
+- Follow project's existing test patterns
+
+### Step 4: Run Tests
+
+Execute tests to verify they pass (use project's test command).
+
+If failures occur, fix them immediately.
+
+### Step 5: Create Summary
+
+Output markdown summary:
+
+```markdown
+# Test Automation Summary
+
+## Generated Tests
+
+### API Tests
+- [x] tests/api/endpoint.spec.ts - Endpoint validation
+
+### E2E Tests
+- [x] tests/e2e/feature.spec.ts - User workflow
+
+## Coverage
+- API endpoints: 5/10 covered
+- UI features: 3/8 covered
+
+## Next Steps
+- Run tests in CI
+- Add more edge cases as needed
+```
+
+## Keep It Simple
+
+**Do:**
+
+- Use standard test framework APIs
+- Focus on happy path + critical errors
+- Write readable, maintainable tests
+- Run tests to verify they pass
+
+**Avoid:**
+
+- Complex fixture composition
+- Over-engineering
+- Unnecessary abstractions
+
+**For Advanced Features:**
+
+If the project needs:
+
+- Risk-based test strategy
+- Test design planning
+- Quality gates and NFR assessment
+- Comprehensive coverage analysis
+- Advanced testing patterns and utilities
+
+> **Install Test Architect (TEA) module**: <https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/>
+
+## Output
+
+Save summary to: `{default_output_file}`
+
+**Done!** Tests generated and verified. Validate against `./checklist.md`.
diff --git a/.claude/skills/bmad-quick-dev/SKILL.md b/.claude/skills/bmad-quick-dev/SKILL.md
new file mode 100644
index 0000000..b2f0df4
--- /dev/null
+++ b/.claude/skills/bmad-quick-dev/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-quick-dev
+description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-quick-dev/compile-epic-context.md b/.claude/skills/bmad-quick-dev/compile-epic-context.md
new file mode 100644
index 0000000..0303477
--- /dev/null
+++ b/.claude/skills/bmad-quick-dev/compile-epic-context.md
@@ -0,0 +1,62 @@
+# Compile Epic Context
+
+**Task**
+Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic-<N>-context.md`).
+
+**Steps**
+
+1. Read the epics file and extract the target epic's title, goal, and list of stories.
+2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief).
+3. Pull only the information relevant to this epic.
+4. Write the compiled context to the exact output path using the format below.
+
+## Exact Output Format
+
+Use these headings:
+
+```markdown
+# Epic {N} Context: {Epic Title}
+
+<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->
+
+## Goal
+
+{One clear paragraph: what this epic achieves and why it matters.}
+
+## Stories
+
+- Story X.Y: Brief title only
+- ...
+
+## Requirements & Constraints
+
+{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).}
+
+## Technical Decisions
+
+{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.}
+
+## UX & Interaction Patterns
+
+{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).}
+
+## Cross-Story Dependencies
+
+{Dependencies between stories in this epic or with other epics/systems (omit if none).}
+```
+
+## Rules
+
+- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc.
+- **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't.
+- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill.
+- **No story-level details.** The story list is for orientation only. Individual story specs handle the details.
+- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code.
+- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into quick-dev's context alongside other material.
+- **Never hallucinate content.** If source material doesn't say something, don't invent it.
+- **Omit empty sections entirely**, except Goal and Stories, which are always required.
+
+## Error handling
+
+- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file.
+- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file, and note the gap in the Goal section. Never hallucinate content to fill missing sections.
diff --git a/.claude/skills/bmad-quick-dev/spec-template.md b/.claude/skills/bmad-quick-dev/spec-template.md
new file mode 100644
index 0000000..b0e4f53
--- /dev/null
+++ b/.claude/skills/bmad-quick-dev/spec-template.md
@@ -0,0 +1,88 @@
+---
+title: '{title}'
+type: 'feature' # feature | bugfix | refactor | chore
+created: '{date}'
+status: 'draft' # draft | ready-for-dev | in-progress | in-review | done
+context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body.
+---
+
+<!-- Target: 900–1300 tokens. Above 1600 = high risk of context rot.
+     Never over-specify "how" — use boundaries + examples instead.
+     Cohesive cross-layer stories (DB+BE+UI) stay in ONE file.
+     IMPORTANT: Remove all HTML comments when filling this template. -->
+
+<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
+
+## Intent
+
+<!-- What is broken or missing, and why it matters. Then the high-level approach — the "what", not the "how". -->
+
+**Problem:** ONE_TO_TWO_SENTENCES
+
+**Approach:** ONE_TO_TWO_SENTENCES
+
+## Boundaries & Constraints
+
+<!-- Three tiers: Always = invariant rules. Ask First = human-gated decisions. Never = out of scope + forbidden approaches. -->
+
+**Always:** INVARIANT_RULES
+
+**Ask First:** DECISIONS_REQUIRING_HUMAN_APPROVAL
+<!-- Agent: if any of these trigger during execution, HALT and ask the user before proceeding. -->
+
+**Never:** NON_GOALS_AND_FORBIDDEN_APPROACHES
+
+## I/O & Edge-Case Matrix
+
+<!-- If no meaningful I/O scenarios exist, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->
+
+| Scenario | Input / State | Expected Output / Behavior | Error Handling |
+|----------|--------------|---------------------------|----------------|
+| HAPPY_PATH | INPUT | OUTCOME | N/A |
+| ERROR_CASE | INPUT | OUTCOME | ERROR_HANDLING |
+
+</frozen-after-approval>
+
+## Code Map
+
+<!-- Agent-populated during planning. Annotated paths prevent blind codebase searching. -->
+
+- `FILE` -- ROLE_OR_RELEVANCE
+- `FILE` -- ROLE_OR_RELEVANCE
+
+## Tasks & Acceptance
+
+<!-- Tasks: backtick-quoted file path -- action -- rationale. Prefer one task per file; group tightly-coupled changes when splitting would be artificial. -->
+<!-- If an I/O Matrix is present, include a task to unit-test its edge cases. -->
+<!-- AC covers system-level behaviors not captured by the I/O Matrix. Do not duplicate I/O scenarios here. -->
+
+**Execution:**
+- [ ] `FILE` -- ACTION -- RATIONALE
+
+**Acceptance Criteria:**
+- Given PRECONDITION, when ACTION, then EXPECTED_RESULT
+
+## Spec Change Log
+
+<!-- Append-only. Populated by step-04 during review loops. Do not modify or delete existing entries.
+     Each entry records: what finding triggered the change, what was amended, what known-bad state
+     the amendment avoids, and any KEEP instructions (what worked well and must survive re-derivation).
+     Empty until the first bad_spec loopback. -->
+
+## Design Notes
+
+<!-- If the approach is straightforward, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->
+<!-- Design rationale and golden examples only when non-obvious. Keep examples to 5–10 lines. -->
+
+DESIGN_RATIONALE_AND_EXAMPLES
+
+## Verification
+
+<!-- If no build, test, or lint commands apply, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->
+<!-- How the agent confirms its own work. Prefer CLI commands. When no CLI check applies, state what to inspect manually. -->
+
+**Commands:**
+- `COMMAND` -- expected: SUCCESS_CRITERIA
+
+**Manual checks (if no CLI):**
+- WHAT_TO_INSPECT_AND_EXPECTED_STATE
diff --git a/.claude/skills/bmad-quick-dev/step-01-clarify-and-route.md b/.claude/skills/bmad-quick-dev/step-01-clarify-and-route.md
new file mode 100644
index 0000000..aae1b31
--- /dev/null
+++ b/.claude/skills/bmad-quick-dev/step-01-clarify-and-route.md
@@ -0,0 +1,91 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+spec_file: '' # set at runtime for both routes before leaving this step
+---
+
+# Step 1: Clarify and Route
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The prompt that triggered this workflow IS the intent — not a hint.
+- Do NOT assume you start from zero.
+- The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly.
+- The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them.
+- **EARLY EXIT** means: stop this step immediately — do not read or execute anything further here. Read and fully follow the target file instead. Return here ONLY if a later step explicitly says to loop back.
+
+## Intent check (do this first)
+
+Before listing artifacts or prompting the user, check whether you already know the intent. Check in this order — skip the remaining checks as soon as the intent is clear:
+
+1. Explicit argument
+   Did the user pass a specific file path, spec name, or clear instruction this message?
+   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file` and **EARLY EXIT** to the appropriate step (step-02 for draft, step-03 for ready/in-progress, step-04 for review). For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume.
+   - Anything else (intent files, external docs, plans, descriptions) → ingest it as starting intent and proceed to INSTRUCTIONS. Do not attempt to infer a workflow state from it.
+
+2. Recent conversation
+   Do the last few human messages clearly show what the user intends to work on?
+   Use the same routing as above.
+
+3. Otherwise — scan artifacts and ask
+   - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
+     - If `draft` selected: Set `spec_file`. **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft)
+     - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. **EARLY EXIT** → `./step-03-implement.md`
+     - If `in-review` selected: Set `spec_file`. **EARLY EXIT** → `./step-04-review.md`
+   - Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it.
+
+Never ask extra questions if you already understand what the user intends.
+
+## INSTRUCTIONS
+
+1. Load context.
+   - List files in `{planning_artifacts}` and `{implementation_artifacts}`.
+   - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
+   - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together.
+
+     **A) Epic story path** — if the intent is clearly an epic story:
+
+     1. Identify the epic number and (if present) the story number. If you can't identify an epic number, use path B.
+
+     2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer.
+        - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5.
+        - **If missing, empty, or invalid:** continue to step 3.
+
+     3. **Compile epic context.** Produce `{implementation_artifacts}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
+        - **Preferred — sub-agent:** spawn a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`.
+        - **Fallback — inline** (for runtimes without sub-agent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn sub-agents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
+
+     4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure.
+
+     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
+
+     **B) Freeform path** — if the intent is not an epic story:
+     - Planning artifacts are the output of BMAD phases 1-3. Typical files include:
+       - **PRD** (`*prd*`) — product requirements and success criteria
+       - **Architecture** (`*architecture*`) — technical design decisions and constraints
+       - **UX/Design** (`*ux*`) — user experience and interaction design
+       - **Epics** (`*epic*`) — feature breakdown into implementable stories
+       - **Product Brief** (`*brief*`) — project vision and scope
+     - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone.
+2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement.
+3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check.
+4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria:
+   - Present detected distinct goals as a bullet list.
+   - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first.
+   - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks`
+   - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing.
+   - On **K**: Proceed as-is.
+5. Route — choose exactly one:
+
+   Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.
+
+   **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions.
+
+   **EARLY EXIT** → `./step-oneshot.md`
+
+   **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path.
+
+
+## NEXT
+
+Read fully and follow `./step-02-plan.md`
diff --git a/.claude/skills/bmad-quick-dev/step-02-plan.md b/.claude/skills/bmad-quick-dev/step-02-plan.md
new file mode 100644
index 0000000..7385e63
--- /dev/null
+++ b/.claude/skills/bmad-quick-dev/step-02-plan.md
@@ -0,0 +1,47 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step 2: Plan
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- No intermediate approvals.
+
+## INSTRUCTIONS
+
+1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
+2. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
+3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent}` is non-empty, substitute it for the `<frozen-after-approval>` block in your filled spec before writing. Write the result to `{spec_file}`.
+4. Self-review against READY FOR DEVELOPMENT standard.
+5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
+6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
+   - Show user the token count.
+   - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
+   - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
+   - On **K**: Continue to checkpoint with full spec.
+
+### CHECKPOINT 1
+
+Present summary. Display the spec file path as a CWD-relative path (no leading `/`) so it is clickable in the terminal. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem.
+
+After presenting the summary, display this note:
+
+---
+
+Before approving, you can open the spec file in an editor or ask me questions and tell me what to change. You can also use `bmad-advanced-elicitation`, `bmad-party-mode`, or `bmad-code-review` skills, ideally in another session to avoid context bloat.
+
+---
+
+HALT and ask human: `[A] Approve` | `[E] Edit`
+
+- **A**: Re-read `{spec_file}` from disk.
+  - **If the file is missing:** HALT. Tell the user the spec file is gone and STOP — do not write anything to `{spec_file}`, do not set status, do not proceed to Step 3. Nothing below this point runs.
+  - **If the file exists:** Compare the content to what you wrote. If it has changed since you wrote it, acknowledge the external edits — show a brief summary of what changed — and proceed with the updated version. Then set status `ready-for-dev` in `{spec_file}`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3.
+- **E**: Apply changes, then return to CHECKPOINT 1.
+
+
+## NEXT
+
+Read fully and follow `./step-03-implement.md`
diff --git a/.claude/skills/bmad-quick-dev/step-03-implement.md b/.claude/skills/bmad-quick-dev/step-03-implement.md
new file mode 100644
index 0000000..96e6041
--- /dev/null
+++ b/.claude/skills/bmad-quick-dev/step-03-implement.md
@@ -0,0 +1,39 @@
+---
+---
+
+# Step 3: Implement
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- No push. No remote ops.
+- Sequential execution only.
+- Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.
+
+## PRECONDITION
+
+Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT and ask the human to provide the spec file path before proceeding.
+
+## INSTRUCTIONS
+
+### Baseline
+
+Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes.
+
+### Implement
+
+Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
+
+If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a sub-agent, include them in the sub-agent prompt so it has access to the referenced context.
+
+Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly.
+
+**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.
+
+### Self-Check
+
+Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete. Mark each finished task `[x]`. If any task is not done, finish it before proceeding.
+
+## NEXT
+
+Read fully and follow `./step-04-review.md`
diff --git a/.claude/skills/bmad-quick-dev/step-04-review.md b/.claude/skills/bmad-quick-dev/step-04-review.md
new file mode 100644
index 0000000..2e44497
--- /dev/null
+++ b/.claude/skills/bmad-quick-dev/step-04-review.md
@@ -0,0 +1,49 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+specLoopIteration: 1
+---
+
+# Step 4: Review
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- Review subagents get NO conversation context.
+
+## INSTRUCTIONS
+
+Change `{spec_file}` status to `in-review` in the frontmatter before continuing.
+
+### Construct Diff
+
+Read `{baseline_commit}` from `{spec_file}` frontmatter. If `{baseline_commit}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_commit}`.
+
+Do NOT `git add` anything — this is read-only inspection.
+
+### Review
+
+Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+
+- **Blind hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
+- **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
+- **Acceptance auditor** — receives `{diff_output}`, `{spec_file}`, and read access to the project. Must also read the docs listed in `{spec_file}` frontmatter `context`. Checks for violations of acceptance criteria, rules, and principles from the spec and context docs.
+
+### Classify
+
+1. Deduplicate all review findings.
+2. Classify each finding. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**.
+   - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading.
+   - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code.
+   - **patch** — caused by the change; trivially fixable without human input. Just part of the diff.
+   - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
+   - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
+3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human.
+   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4.
+   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
+   - **patch** — Auto-fix. These are the only findings that survive loopbacks.
+   - **defer** — Append to `{deferred_work_file}`.
+   - **reject** — Drop silently.
+
+## NEXT
+
+Read fully and follow `./step-05-present.md`
diff --git a/.claude/skills/bmad-quick-dev/step-05-present.md b/.claude/skills/bmad-quick-dev/step-05-present.md
new file mode 100644
index 0000000..3c0ba6c
--- /dev/null
+++ b/.claude/skills/bmad-quick-dev/step-05-present.md
@@ -0,0 +1,63 @@
+---
+---
+
+# Step 5: Present
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- NEVER auto-push.
+
+## INSTRUCTIONS
+
+### Generate Suggested Review Order
+
+Read `{baseline_commit}` from `{spec_file}` frontmatter and construct the diff of all changes since that commit.
+
+Append the review order as a `## Suggested Review Order` section to `{spec_file}` **after the last existing section**. Do not modify the Code Map.
+
+Build the trail as an ordered sequence of **stops** — clickable `path:line` references with brief framing — optimized for a human reviewer reading top-down to understand the change:
+
+1. **Order by concern, not by file.** Group stops by the conceptual concern they address (e.g., "validation logic", "schema change", "UI binding"). A single file may appear under multiple concerns.
+2. **Lead with the entry point** — the single highest-leverage file:line a reviewer should look at first to grasp the design intent.
+3. **Inside each concern**, order stops from most important / architecturally interesting to supporting. Lightly bias toward higher-risk or boundary-crossing stops.
+4. **End with peripherals** — tests, config, types, and other supporting changes come last.
+5. **Every code reference is a clickable spec-file-relative link.** Compute each link target as a relative path from `{spec_file}`'s directory to the changed file. Format each stop as a markdown link: `[short-name:line](../../path/to/file.ts#L42)`. Use a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text. The relative path must be dynamically derived — never hardcode the depth.
+6. **Each stop gets one ultra-concise line of framing** (≤15 words) — why this approach was chosen here and what it achieves in the context of the change. No paragraphs.
+
+Format each stop as framing first, link on the next indented line:
+
+```markdown
+## Suggested Review Order
+
+**{Concern name}**
+
+- {one-line framing}
+  [`file.ts:42`](../../src/path/to/file.ts#L42)
+
+- {one-line framing}
+  [`other.ts:17`](../../src/path/to/other.ts#L17)
+
+**{Next concern}**
+
+- {one-line framing}
+  [`file.ts:88`](../../src/path/to/file.ts#L88)
+```
+
+> The `../../` prefix above is illustrative — compute the actual relative path from `{spec_file}`'s directory to each target file.
+
+When there is only one concern, omit the bold label — just list the stops directly.
+
+### Commit and Present
+
+1. Change `{spec_file}` status to `done` in the frontmatter.
+2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
+3. Open the spec in the user's editor so they can click through the Suggested Review Order:
+   - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
+   - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
+4. Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include:
+   - A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
+   - **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
+   - Offer to push and/or create a pull request.
+
+Workflow complete.
diff --git a/.claude/skills/bmad-quick-dev/step-oneshot.md b/.claude/skills/bmad-quick-dev/step-oneshot.md
new file mode 100644
index 0000000..0c52d43
--- /dev/null
+++ b/.claude/skills/bmad-quick-dev/step-oneshot.md
@@ -0,0 +1,61 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step One-Shot: Implement, Review, Present
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- NEVER auto-push.
+
+## INSTRUCTIONS
+
+### Implement
+
+Implement the clarified intent directly.
+
+### Review
+
+Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
+
+### Classify
+
+Deduplicate all review findings. Three categories only:
+
+- **patch** — trivially fixable. Auto-fix immediately.
+- **defer** — pre-existing issue not caused by this change. Append to `{deferred_work_file}`.
+- **reject** — noise. Drop silently.
+
+If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.
+
+### Generate Spec Trace
+
+Set `{title}` = a concise title derived from the clarified intent.
+
+Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others:
+
+1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`.
+2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.
+3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
+
+### Commit
+
+If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip.
+
+### Present
+
+1. Open the spec in the user's editor so they can click through the Suggested Review Order:
+   - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
+   - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
+2. Display a summary in conversation output, including:
+   - The commit hash (if one was created).
+   - List of files changed with one-line descriptions. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — this differs from spec-file links which use spec-file-relative paths.
+   - Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so.
+   - A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
+   - **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
+3. Offer to push and/or create a pull request.
+
+HALT and wait for human input.
+
+Workflow complete.
diff --git a/.claude/skills/bmad-quick-dev/workflow.md b/.claude/skills/bmad-quick-dev/workflow.md
new file mode 100644
index 0000000..55b8fda
--- /dev/null
+++ b/.claude/skills/bmad-quick-dev/workflow.md
@@ -0,0 +1,75 @@
+---
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+---
+
+# Quick Dev New Preview Workflow
+
+**Goal:** Turn user intent into a hardened, reviewable artifact.
+
+**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.
+
+
+## READY FOR DEVELOPMENT STANDARD
+
+A specification is "Ready for Development" when:
+
+- **Actionable**: Every task has a file path and specific action.
+- **Logical**: Tasks ordered by dependency.
+- **Testable**: All ACs use Given/When/Then.
+- **Complete**: No placeholders or TBDs.
+
+
+## SCOPE STANDARD
+
+A specification should target a **single user-facing goal** within **900–1600 tokens**:
+
+- **Single goal**: One cohesive feature, even if it spans multiple layers/files. Multi-goal means >=2 **top-level independent shippable deliverables** — each could be reviewed, tested, and merged as a separate PR without breaking the others. Never count surface verbs, "and" conjunctions, or noun phrases. Never split cross-layer implementation details inside one user goal.
+  - Split: "add dark mode toggle AND refactor auth to JWT AND build admin dashboard"
+  - Don't split: "add validation and display errors" / "support drag-and-drop AND paste AND retry"
+- **900–1600 tokens**: Optimal range for LLM consumption. Below 900 risks ambiguity; above 1600 risks context-rot in implementation agents.
+- **Neither limit is a gate.** Both are proposals with user override.
+
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+- **Micro-file Design**: Each step is self-contained and followed exactly
+- **Just-In-Time Loading**: Only load the current step file
+- **Sequential Enforcement**: Complete steps in order, no skipping
+- **State Tracking**: Persist progress via spec frontmatter and in-memory variables
+- **Append-Only Building**: Build artifacts incrementally
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Read the entire step file before acting
+2. **FOLLOW SEQUENCE**: Execute sections in order
+3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human
+4. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- **NEVER** load multiple step files simultaneously
+- **ALWAYS** read entire step file before execution
+- **NEVER** skip steps or optimize the sequence
+- **ALWAYS** follow the exact instructions in the step file
+- **ALWAYS** halt at checkpoints and wait for human input
+
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{main_config}` and resolve:
+
+- `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+- `project_context` = `**/project-context.md` (load if exists)
+- CLAUDE.md / memory files (load if exist)
+
+YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`.
+
+### 2. First Step Execution
+
+Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.
diff --git a/.claude/skills/bmad-retrospective/SKILL.md b/.claude/skills/bmad-retrospective/SKILL.md
new file mode 100644
index 0000000..bdc2b6d
--- /dev/null
+++ b/.claude/skills/bmad-retrospective/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-retrospective
+description: 'Post-epic review to extract lessons and assess success. Use when the user says "run a retrospective" or "lets retro the epic [epic]"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-retrospective/workflow.md b/.claude/skills/bmad-retrospective/workflow.md
new file mode 100644
index 0000000..c3581d6
--- /dev/null
+++ b/.claude/skills/bmad-retrospective/workflow.md
@@ -0,0 +1,1479 @@
+# Retrospective Workflow
+
+**Goal:** Post-epic review to extract lessons and assess success.
+
+**Your Role:** Developer facilitating retrospective.
+- No time estimates — NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed.
+- Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}
+- Generate all documents in {document_output_language}
+- Document output: Retrospective analysis. Concise insights, lessons learned, action items. User skill level ({user_skill_level}) affects conversation style ONLY, not retrospective content.
+- Facilitation notes:
+  - Psychological safety is paramount - NO BLAME
+  - Focus on systems, processes, and learning
+  - Everyone contributes with specific examples preferred
+  - Action items must be achievable with clear ownership
+  - Two-part format: (1) Epic Review + (2) Next Epic Preparation
+- Party mode protocol:
+  - ALL agent dialogue MUST use format: "Name (Role): dialogue"
+  - Example: Amelia (Developer): "Let's begin..."
+  - Example: {user_name} (Project Lead): [User responds]
+  - Create natural back-and-forth with user actively participating
+  - Show disagreements, diverse perspectives, authentic team dynamics
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `user_skill_level`
+- `planning_artifacts`, `implementation_artifacts`
+- `date` as system-generated current datetime
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Paths
+
+- `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml`
+
+### Input Files
+
+| Input | Description | Path Pattern(s) | Load Strategy |
+|-------|-------------|------------------|---------------|
+| epics | The completed epic for retrospective | whole: `{planning_artifacts}/*epic*.md`, sharded_index: `{planning_artifacts}/*epic*/index.md`, sharded_single: `{planning_artifacts}/*epic*/epic-{{epic_num}}.md` | SELECTIVE_LOAD |
+| previous_retrospective | Previous epic's retrospective (optional) | `{implementation_artifacts}/**/epic-{{prev_epic_num}}-retro-*.md` | SELECTIVE_LOAD |
+| architecture | System architecture for context | whole: `{planning_artifacts}/*architecture*.md`, sharded: `{planning_artifacts}/*architecture*/*.md` | FULL_LOAD |
+| prd | Product requirements for context | whole: `{planning_artifacts}/*prd*.md`, sharded: `{planning_artifacts}/*prd*/*.md` | FULL_LOAD |
+| document_project | Brownfield project documentation (optional) | sharded: `{planning_artifacts}/*.md` | INDEX_GUIDED |
+
+### Required Inputs
+
+- `agent_manifest` = `{project-root}/_bmad/_config/agent-manifest.csv`
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+<workflow>
+
+<step n="1" goal="Epic Discovery - Find Completed Epic with Priority Logic">
+
+<action>Load {project_context} for project-wide patterns and conventions (if exists)</action>
+<action>Explain to {user_name} the epic discovery process using natural dialogue</action>
+
+<output>
+Amelia (Developer): "Welcome to the retrospective, {user_name}. Let me help you identify which epic we just completed. I'll check sprint-status first, but you're the ultimate authority on what we're reviewing today."
+</output>
+
+<action>PRIORITY 1: Check {sprint_status_file} first</action>
+
+<action>Load the FULL file: {sprint_status_file}</action>
+<action>Read ALL development_status entries</action>
+<action>Find the highest epic number with at least one story marked "done"</action>
+<action>Extract epic number from keys like "epic-X-retrospective" or story keys like "X-Y-story-name"</action>
+<action>Set {{detected_epic}} = highest epic number found with completed stories</action>
+
+<check if="{{detected_epic}} found">
+  <action>Present finding to user with context</action>
+
+  <output>
+Amelia (Developer): "Based on {sprint_status_file}, it looks like Epic {{detected_epic}} was recently completed. Is that the epic you want to review today, {user_name}?"
+  </output>
+
+<action>WAIT for {user_name} to confirm or correct</action>
+
+  <check if="{user_name} confirms">
+    <action>Set {{epic_number}} = {{detected_epic}}</action>
+  </check>
+
+  <check if="{user_name} provides different epic number">
+    <action>Set {{epic_number}} = user-provided number</action>
+    <output>
+Amelia (Developer): "Got it, we're reviewing Epic {{epic_number}}. Let me gather that information."
+    </output>
+  </check>
+</check>
+
+<check if="{{detected_epic}} NOT found in sprint-status">
+  <action>PRIORITY 2: Ask user directly</action>
+
+  <output>
+Amelia (Developer): "I'm having trouble detecting the completed epic from {sprint_status_file}. {user_name}, which epic number did you just complete?"
+  </output>
+
+<action>WAIT for {user_name} to provide epic number</action>
+<action>Set {{epic_number}} = user-provided number</action>
+</check>
+
+<check if="{{epic_number}} still not determined">
+  <action>PRIORITY 3: Fallback to stories folder</action>
+
+<action>Scan {implementation_artifacts} for highest numbered story files</action>
+<action>Extract epic numbers from story filenames (pattern: epic-X-Y-story-name.md)</action>
+<action>Set {{detected_epic}} = highest epic number found</action>
+
+  <output>
+Amelia (Developer): "I found stories for Epic {{detected_epic}} in the stories folder. Is that the epic we're reviewing, {user_name}?"
+  </output>
+
+<action>WAIT for {user_name} to confirm or correct</action>
+<action>Set {{epic_number}} = confirmed number</action>
+</check>
+
+<action>Once {{epic_number}} is determined, verify epic completion status</action>
+
+<action>Find all stories for epic {{epic_number}} in {sprint_status_file}:
+
+- Look for keys starting with "{{epic_number}}-" (e.g., "1-1-", "1-2-", etc.)
+- Exclude epic key itself ("epic-{{epic_number}}")
+- Exclude retrospective key ("epic-{{epic_number}}-retrospective")
+  </action>
+
+<action>Count total stories found for this epic</action>
+<action>Count stories with status = "done"</action>
+<action>Collect list of pending story keys (status != "done")</action>
+<action>Determine if complete: true if all stories are done, false otherwise</action>
+
+<check if="epic is not complete">
+  <output>
+Alice (Product Owner): "Wait, Amelia - I'm seeing that Epic {{epic_number}} isn't actually complete yet."
+
+Amelia (Developer): "Let me check... you're right, Alice."
+
+**Epic Status:**
+
+- Total Stories: {{total_stories}}
+- Completed (Done): {{done_stories}}
+- Pending: {{pending_count}}
+
+**Pending Stories:**
+{{pending_story_list}}
+
+Amelia (Developer): "{user_name}, we typically run retrospectives after all stories are done. What would you like to do?"
+
+**Options:**
+
+1. Complete remaining stories before running retrospective (recommended)
+2. Continue with partial retrospective (not ideal, but possible)
+3. Run sprint-planning to refresh story tracking
+   </output>
+
+<ask if="{{non_interactive}} == false">Continue with incomplete epic? (yes/no)</ask>
+
+  <check if="user says no">
+    <output>
+Amelia (Developer): "Smart call, {user_name}. Let's finish those stories first and then have a proper retrospective."
+    </output>
+    <action>HALT</action>
+  </check>
+
+<action if="user says yes">Set {{partial_retrospective}} = true</action>
+<output>
+Charlie (Senior Dev): "Just so everyone knows, this partial retro might miss some important lessons from those pending stories."
+
+Amelia (Developer): "Good point, Charlie. {user_name}, we'll document what we can now, but we may want to revisit after everything's done."
+</output>
+</check>
+
+<check if="epic is complete">
+  <output>
+Alice (Product Owner): "Excellent! All {{done_stories}} stories are marked done."
+
+Amelia (Developer): "Perfect. Epic {{epic_number}} is complete and ready for retrospective, {user_name}."
+</output>
+</check>
+
+</step>
+
+<step n="0.5" goal="Discover and load project documents">
+  <action>Load input files according to the Input Files table in INITIALIZATION. For SELECTIVE_LOAD inputs, load only the epic matching {{epic_number}}. For FULL_LOAD inputs, load the complete document. For INDEX_GUIDED inputs, check the index first and load relevant sections. After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {prd_content}, {document_project_content}</action>
+  <note>After discovery, these content variables are available: {epics_content} (selective load for this epic), {architecture_content}, {prd_content}, {document_project_content}</note>
+</step>
+
+<step n="2" goal="Deep Story Analysis - Extract Lessons from Implementation">
+
+<output>
+Amelia (Developer): "Before we start the team discussion, let me review all the story records to surface key themes. This'll help us have a richer conversation."
+
+Charlie (Senior Dev): "Good idea - those dev notes always have gold in them."
+</output>
+
+<action>For each story in epic {{epic_number}}, read the complete story file from {implementation_artifacts}/{{epic_number}}-{{story_num}}-*.md</action>
+
+<action>Extract and analyze from each story:</action>
+
+**Dev Notes and Struggles:**
+
+- Look for sections like "## Dev Notes", "## Implementation Notes", "## Challenges", "## Development Log"
+- Identify where developers struggled or made mistakes
+- Note unexpected complexity or gotchas discovered
+- Record technical decisions that didn't work out as planned
+- Track where estimates were way off (too high or too low)
+
+**Review Feedback Patterns:**
+
+- Look for "## Review", "## Code Review", "## Dev Review" sections
+- Identify recurring feedback themes across stories
+- Note which types of issues came up repeatedly
+- Track quality concerns or architectural misalignments
+- Document praise or exemplary work called out in reviews
+
+**Lessons Learned:**
+
+- Look for "## Lessons Learned", "## Retrospective Notes", "## Takeaways" sections within stories
+- Extract explicit lessons documented during development
+- Identify "aha moments" or breakthroughs
+- Note what would be done differently
+- Track successful experiments or approaches
+
+**Technical Debt Incurred:**
+
+- Look for "## Technical Debt", "## TODO", "## Known Issues", "## Future Work" sections
+- Document shortcuts taken and why
+- Track debt items that affect next epic
+- Note severity and priority of debt items
+
+**Testing and Quality Insights:**
+
+- Look for "## Testing", "## QA Notes", "## Test Results" sections
+- Note testing challenges or surprises
+- Track bug patterns or regression issues
+- Document test coverage gaps
+
+<action>Synthesize patterns across all stories:</action>
+
+**Common Struggles:**
+
+- Identify issues that appeared in 2+ stories (e.g., "3 out of 5 stories had API authentication issues")
+- Note areas where team consistently struggled
+- Track where complexity was underestimated
+
+**Recurring Review Feedback:**
+
+- Identify feedback themes (e.g., "Error handling was flagged in every review")
+- Note quality patterns (positive and negative)
+- Track areas where team improved over the course of epic
+
+**Breakthrough Moments:**
+
+- Document key discoveries (e.g., "Story 3 discovered the caching pattern we used for rest of epic")
+- Note when team velocity improved dramatically
+- Track innovative solutions worth repeating
+
+**Velocity Patterns:**
+
+- Calculate average completion time per story
+- Note velocity trends (e.g., "First 2 stories took 3x longer than estimated")
+- Identify which types of stories went faster/slower
+
+**Team Collaboration Highlights:**
+
+- Note moments of excellent collaboration mentioned in stories
+- Track where pair programming or mob programming was effective
+- Document effective problem-solving sessions
+
+<action>Store this synthesis - these patterns will drive the retrospective discussion</action>
+
+<output>
+Amelia (Developer): "Okay, I've reviewed all {{total_stories}} story records. I found some really interesting patterns we should discuss."
+
+Dana (QA Engineer): "I'm curious what you found, Amelia. I noticed some things in my testing too."
+
+Amelia (Developer): "We'll get to all of it. But first, let me load the previous epic's retro to see if we learned from last time."
+</output>
+
+</step>
+
+<step n="3" goal="Load and Integrate Previous Epic Retrospective">
+
+<action>Calculate previous epic number: {{prev_epic_num}} = {{epic_number}} - 1</action>
+
+<check if="{{prev_epic_num}} >= 1">
+  <action>Search for previous retrospectives using pattern: {implementation_artifacts}/epic-{{prev_epic_num}}-retro-*.md</action>
+
+  <check if="previous retrospectives found">
+    <output>
+Amelia (Developer): "I found our retrospectives from Epic {{prev_epic_num}}. Let me see what we committed to back then..."
+    </output>
+
+    <action>Read the previous retrospectives</action>
+
+    <action>Extract key elements:</action>
+    - **Action items committed**: What did the team agree to improve?
+    - **Lessons learned**: What insights were captured?
+    - **Process improvements**: What changes were agreed upon?
+    - **Technical debt flagged**: What debt was documented?
+    - **Team agreements**: What commitments were made?
+    - **Preparation tasks**: What was needed for this epic?
+
+    <action>Cross-reference with current epic execution:</action>
+
+    **Action Item Follow-Through:**
+    - For each action item from Epic {{prev_epic_num}} retro, check if it was completed
+    - Look for evidence in current epic's story records
+    - Mark each action item: ✅ Completed, ⏳ In Progress, ❌ Not Addressed
+
+    **Lessons Applied:**
+    - For each lesson from Epic {{prev_epic_num}}, check if team applied it in Epic {{epic_number}}
+    - Look for evidence in dev notes, review feedback, or outcomes
+    - Document successes and missed opportunities
+
+    **Process Improvements Effectiveness:**
+    - For each process change agreed to in Epic {{prev_epic_num}}, assess if it helped
+    - Did the change improve velocity, quality, or team satisfaction?
+    - Should we keep, modify, or abandon the change?
+
+    **Technical Debt Status:**
+    - For each debt item from Epic {{prev_epic_num}}, check if it was addressed
+    - Did unaddressed debt cause problems in Epic {{epic_number}}?
+    - Did the debt grow or shrink?
+
+    <action>Prepare "continuity insights" for the retrospective discussion</action>
+
+    <action>Identify wins where previous lessons were applied successfully:</action>
+    - Document specific examples of applied learnings
+    - Note positive impact on Epic {{epic_number}} outcomes
+    - Celebrate team growth and improvement
+
+    <action>Identify missed opportunities where previous lessons were ignored:</action>
+    - Document where team repeated previous mistakes
+    - Note impact of not applying lessons (without blame)
+    - Explore barriers that prevented application
+
+    <output>
+
+Amelia (Developer): "Interesting... in Epic {{prev_epic_num}}'s retro, we committed to {{action_count}} action items."
+
+Alice (Product Owner): "How'd we do on those, Amelia?"
+
+Amelia (Developer): "We completed {{completed_count}}, made progress on {{in_progress_count}}, but didn't address {{not_addressed_count}}."
+
+Charlie (Senior Dev): _looking concerned_ "Which ones didn't we address?"
+
+Amelia (Developer): "We'll discuss that in the retro. Some of them might explain challenges we had this epic."
+
+Elena (Junior Dev): "That's... actually pretty insightful."
+
+Amelia (Developer): "That's why we track this stuff. Pattern recognition helps us improve."
+</output>
+
+  </check>
+
+  <check if="no previous retro found">
+    <output>
+Amelia (Developer): "I don't see a retrospective for Epic {{prev_epic_num}}. Either we skipped it, or this is your first retro."
+
+Alice (Product Owner): "Probably our first one. Good time to start the habit!"
+</output>
+<action>Set {{first_retrospective}} = true</action>
+</check>
+</check>
+
+<check if="{{prev_epic_num}} < 1">
+  <output>
+Amelia (Developer): "This is Epic 1, so naturally there's no previous retro to reference. We're starting fresh!"
+
+Charlie (Senior Dev): "First epic, first retro. Let's make it count."
+</output>
+<action>Set {{first_retrospective}} = true</action>
+</check>
+
+</step>
+
+<step n="4" goal="Preview Next Epic with Change Detection">
+
+<action>Calculate next epic number: {{next_epic_num}} = {{epic_number}} + 1</action>
+
+<output>
+Amelia (Developer): "Before we dive into the discussion, let me take a quick look at Epic {{next_epic_num}} to understand what's coming."
+
+Alice (Product Owner): "Good thinking - helps us connect what we learned to what we're about to do."
+</output>
+
+<action>Attempt to load next epic using selective loading strategy:</action>
+
+**Try sharded first (more specific):**
+<action>Check if file exists: {planning_artifacts}/epic*/epic-{{next_epic_num}}.md</action>
+
+<check if="sharded epic file found">
+  <action>Load {planning_artifacts}/*epic*/epic-{{next_epic_num}}.md</action>
+  <action>Set {{next_epic_source}} = "sharded"</action>
+</check>
+
+**Fallback to whole document:**
+<check if="sharded epic not found">
+<action>Check if file exists: {planning_artifacts}/epic*.md</action>
+
+  <check if="whole epic file found">
+    <action>Load entire epics document</action>
+    <action>Extract Epic {{next_epic_num}} section</action>
+    <action>Set {{next_epic_source}} = "whole"</action>
+  </check>
+</check>
+
+<check if="next epic found">
+  <action>Analyze next epic for:</action>
+  - Epic title and objectives
+  - Planned stories and complexity estimates
+  - Dependencies on Epic {{epic_number}} work
+  - New technical requirements or capabilities needed
+  - Potential risks or unknowns
+  - Business goals and success criteria
+
+<action>Identify dependencies on completed work:</action>
+
+- What components from Epic {{epic_number}} does Epic {{next_epic_num}} rely on?
+- Are all prerequisites complete and stable?
+- Any incomplete work that creates blocking dependencies?
+
+<action>Note potential gaps or preparation needed:</action>
+
+- Technical setup required (infrastructure, tools, libraries)
+- Knowledge gaps to fill (research, training, spikes)
+- Refactoring needed before starting next epic
+- Documentation or specifications to create
+
+<action>Check for technical prerequisites:</action>
+
+- APIs or integrations that must be ready
+- Data migrations or schema changes needed
+- Testing infrastructure requirements
+- Deployment or environment setup
+
+  <output>
+Amelia (Developer): "Alright, I've reviewed Epic {{next_epic_num}}: '{{next_epic_title}}'"
+
+Alice (Product Owner): "What are we looking at?"
+
+Amelia (Developer): "{{next_epic_num}} stories planned, building on the {{dependency_description}} from Epic {{epic_number}}."
+
+Charlie (Senior Dev): "Dependencies concern me. Did we finish everything we need for that?"
+
+Amelia (Developer): "Good question - that's exactly what we need to explore in this retro."
+</output>
+
+<action>Set {{next_epic_exists}} = true</action>
+</check>
+
+<check if="next epic NOT found">
+  <output>
+Amelia (Developer): "Hmm, I don't see Epic {{next_epic_num}} defined yet."
+
+Alice (Product Owner): "We might be at the end of the roadmap, or we haven't planned that far ahead yet."
+
+Amelia (Developer): "No problem. We'll still do a thorough retro on Epic {{epic_number}}. The lessons will be valuable whenever we plan the next work."
+</output>
+
+<action>Set {{next_epic_exists}} = false</action>
+</check>
+
+</step>
+
+<step n="5" goal="Initialize Retrospective with Rich Context">
+
+<action>Load agent configurations from {agent_manifest}</action>
+<action>Identify which agents participated in Epic {{epic_number}} based on story records</action>
+<action>Ensure key roles present: Product Owner, Developer (facilitating), Testing/QA, Architect</action>
+
+<output>
+Amelia (Developer): "Alright team, everyone's here. Let me set the stage for our retrospective."
+
+═══════════════════════════════════════════════════════════
+🔄 TEAM RETROSPECTIVE - Epic {{epic_number}}: {{epic_title}}
+═══════════════════════════════════════════════════════════
+
+Amelia (Developer): "Here's what we accomplished together."
+
+**EPIC {{epic_number}} SUMMARY:**
+
+Delivery Metrics:
+
+- Completed: {{completed_stories}}/{{total_stories}} stories ({{completion_percentage}}%)
+- Velocity: {{actual_points}} story points{{#if planned_points}} (planned: {{planned_points}}){{/if}}
+- Duration: {{actual_sprints}} sprints{{#if planned_sprints}} (planned: {{planned_sprints}}){{/if}}
+- Average velocity: {{points_per_sprint}} points/sprint
+
+Quality and Technical:
+
+- Blockers encountered: {{blocker_count}}
+- Technical debt items: {{debt_count}}
+- Test coverage: {{coverage_info}}
+- Production incidents: {{incident_count}}
+
+Business Outcomes:
+
+- Goals achieved: {{goals_met}}/{{total_goals}}
+- Success criteria: {{criteria_status}}
+- Stakeholder feedback: {{feedback_summary}}
+
+Alice (Product Owner): "Those numbers tell a good story. {{completion_percentage}}% completion is {{#if completion_percentage >= 90}}excellent{{else}}something we should discuss{{/if}}."
+
+Charlie (Senior Dev): "I'm more interested in that technical debt number - {{debt_count}} items is {{#if debt_count > 10}}concerning{{else}}manageable{{/if}}."
+
+Dana (QA Engineer): "{{incident_count}} production incidents - {{#if incident_count == 0}}clean epic!{{else}}we should talk about those{{/if}}."
+
+{{#if next_epic_exists}}
+═══════════════════════════════════════════════════════════
+**NEXT EPIC PREVIEW:** Epic {{next_epic_num}}: {{next_epic_title}}
+═══════════════════════════════════════════════════════════
+
+Dependencies on Epic {{epic_number}}:
+{{list_dependencies}}
+
+Preparation Needed:
+{{list_preparation_gaps}}
+
+Technical Prerequisites:
+{{list_technical_prereqs}}
+
+Amelia (Developer): "And here's what's coming next. Epic {{next_epic_num}} builds on what we just finished."
+
+Elena (Junior Dev): "Wow, that's a lot of dependencies on our work."
+
+Charlie (Senior Dev): "Which means we better make sure Epic {{epic_number}} is actually solid before moving on."
+{{/if}}
+
+═══════════════════════════════════════════════════════════
+
+Amelia (Developer): "Team assembled for this retrospective:"
+
+{{list_participating_agents}}
+
+Amelia (Developer): "{user_name}, you're joining us as Project Lead. Your perspective is crucial here."
+
+{user_name} (Project Lead): [Participating in the retrospective]
+
+Amelia (Developer): "Our focus today:"
+
+1. Learning from Epic {{epic_number}} execution
+   {{#if next_epic_exists}}2. Preparing for Epic {{next_epic_num}} success{{/if}}
+
+Amelia (Developer): "Ground rules: psychological safety first. No blame, no judgment. We focus on systems and processes, not individuals. Everyone's voice matters. Specific examples are better than generalizations."
+
+Alice (Product Owner): "And everything shared here stays in this room - unless we decide together to escalate something."
+
+Amelia (Developer): "Exactly. {user_name}, any questions before we dive in?"
+</output>
+
+<action>WAIT for {user_name} to respond or indicate readiness</action>
+
+</step>
+
+<step n="6" goal="Epic Review Discussion - What Went Well, What Didn't">
+
+<output>
+Amelia (Developer): "Let's start with the good stuff. What went well in Epic {{epic_number}}?"
+
+Amelia (Developer): _pauses, creating space_
+
+Alice (Product Owner): "I'll start. The user authentication flow we delivered exceeded my expectations. The UX is smooth, and early user feedback has been really positive."
+
+Charlie (Senior Dev): "I'll add to that - the caching strategy we implemented in Story {{breakthrough_story_num}} was a game-changer. We cut API calls by 60% and it set the pattern for the rest of the epic."
+
+Dana (QA Engineer): "From my side, testing went smoother than usual. The Developer's documentation was way better this epic - actually usable test plans!"
+
+Elena (Junior Dev): _smiling_ "That's because Charlie made me document everything after Story 1's code review!"
+
+Charlie (Senior Dev): _laughing_ "Tough love pays off."
+</output>
+
+<action>Amelia (Developer) naturally turns to {user_name} to engage them in the discussion</action>
+
+<output>
+Amelia (Developer): "{user_name}, what stood out to you as going well in this epic?"
+</output>
+
+<action>WAIT for {user_name} to respond - this is a KEY USER INTERACTION moment</action>
+
+<action>After {user_name} responds, have 1-2 team members react to or build on what {user_name} shared</action>
+
+<output>
+Alice (Product Owner): [Responds naturally to what {user_name} said, either agreeing, adding context, or offering a different perspective]
+
+Charlie (Senior Dev): [Builds on the discussion, perhaps adding technical details or connecting to specific stories]
+</output>
+
+<action>Continue facilitating natural dialogue, periodically bringing {user_name} back into the conversation</action>
+
+<action>After covering successes, guide the transition to challenges with care</action>
+
+<output>
+Amelia (Developer): "Okay, we've celebrated some real wins. Now let's talk about challenges - where did we struggle? What slowed us down?"
+
+Amelia (Developer): _creates safe space with tone and pacing_
+
+Elena (Junior Dev): _hesitates_ "Well... I really struggled with the database migrations in Story {{difficult_story_num}}. The documentation wasn't clear, and I had to redo it three times. Lost almost a full sprint on that story alone."
+
+Charlie (Senior Dev): _defensive_ "Hold on - I wrote those migration docs, and they were perfectly clear. The issue was that the requirements kept changing mid-story!"
+
+Alice (Product Owner): _frustrated_ "That's not fair, Charlie. We only clarified requirements once, and that was because the technical team didn't ask the right questions during planning!"
+
+Charlie (Senior Dev): _heat rising_ "We asked plenty of questions! You said the schema was finalized, then two days into development you wanted to add three new fields!"
+
+Amelia (Developer): _intervening calmly_ "Let's take a breath here. This is exactly the kind of thing we need to unpack."
+
+Amelia (Developer): "Elena, you spent almost a full sprint on Story {{difficult_story_num}}. Charlie, you're saying requirements changed. Alice, you feel the right questions weren't asked up front."
+
+Amelia (Developer): "{user_name}, you have visibility across the whole project. What's your take on this situation?"
+</output>
+
+<action>WAIT for {user_name} to respond and help facilitate the conflict resolution</action>
+
+<action>Use {user_name}'s response to guide the discussion toward systemic understanding rather than blame</action>
+
+<output>
+Amelia (Developer): [Synthesizes {user_name}'s input with what the team shared] "So it sounds like the core issue was {{root_cause_based_on_discussion}}, not any individual person's fault."
+
+Elena (Junior Dev): "That makes sense. If we'd had {{preventive_measure}}, I probably could have avoided those redos."
+
+Charlie (Senior Dev): _softening_ "Yeah, and I could have been clearer about assumptions in the docs. Sorry for getting defensive, Alice."
+
+Alice (Product Owner): "I appreciate that. I could've been more proactive about flagging the schema additions earlier, too."
+
+Amelia (Developer): "This is good. We're identifying systemic improvements, not assigning blame."
+</output>
+
+<action>Continue the discussion, weaving in patterns discovered from the deep story analysis (Step 2)</action>
+
+<output>
+Amelia (Developer): "Speaking of patterns, I noticed something when reviewing all the story records..."
+
+Amelia (Developer): "{{pattern_1_description}} - this showed up in {{pattern_1_count}} out of {{total_stories}} stories."
+
+Dana (QA Engineer): "Oh wow, I didn't realize it was that widespread."
+
+Amelia (Developer): "Yeah. And there's more - {{pattern_2_description}} came up in almost every code review."
+
+Charlie (Senior Dev): "That's... actually embarrassing. We should've caught that pattern earlier."
+
+Amelia (Developer): "No shame, Charlie. Now we know, and we can improve. {user_name}, did you notice these patterns during the epic?"
+</output>
+
+<action>WAIT for {user_name} to share their observations</action>
+
+<action>Continue the retrospective discussion, creating moments where:</action>
+
+- Team members ask {user_name} questions directly
+- {user_name}'s input shifts the discussion direction
+- Disagreements arise naturally and get resolved
+- Quieter team members are invited to contribute
+- Specific stories are referenced with real examples
+- Emotions are authentic (frustration, pride, concern, hope)
+
+<check if="previous retrospective exists">
+  <output>
+Amelia (Developer): "Before we move on, I want to circle back to Epic {{prev_epic_num}}'s retrospective."
+
+Amelia (Developer): "We made some commitments in that retro. Let's see how we did."
+
+Amelia (Developer): "Action item 1: {{prev_action_1}}. Status: {{prev_action_1_status}}"
+
+Alice (Product Owner): {{#if prev_action_1_status == "completed"}}"We nailed that one!"{{else}}"We... didn't do that one."{{/if}}
+
+Charlie (Senior Dev): {{#if prev_action_1_status == "completed"}}"And it helped! I noticed {{evidence_of_impact}}"{{else}}"Yeah, and I think that's why we had {{consequence_of_not_doing_it}} this epic."{{/if}}
+
+Amelia (Developer): "Action item 2: {{prev_action_2}}. Status: {{prev_action_2_status}}"
+
+Dana (QA Engineer): {{#if prev_action_2_status == "completed"}}"This one made testing so much easier this time."{{else}}"If we'd done this, I think testing would've gone faster."{{/if}}
+
+Amelia (Developer): "{user_name}, looking at what we committed to last time and what we actually did - what's your reaction?"
+</output>
+
+<action>WAIT for {user_name} to respond</action>
+
+<action>Use the previous retro follow-through as a learning moment about commitment and accountability</action>
+</check>
+
+<output>
+Amelia (Developer): "Alright, we've covered a lot of ground. Let me summarize what I'm hearing..."
+
+Amelia (Developer): "**Successes:**"
+{{list_success_themes}}
+
+Amelia (Developer): "**Challenges:**"
+{{list_challenge_themes}}
+
+Amelia (Developer): "**Key Insights:**"
+{{list_insight_themes}}
+
+Amelia (Developer): "Does that capture it? Anyone have something important we missed?"
+</output>
+
+<action>Allow team members to add any final thoughts on the epic review</action>
+<action>Ensure {user_name} has opportunity to add their perspective</action>
+
+</step>
+
+<step n="7" goal="Next Epic Preparation Discussion - Interactive and Collaborative">
+
+<check if="{{next_epic_exists}} == false">
+  <output>
+Amelia (Developer): "Normally we'd discuss preparing for the next epic, but since Epic {{next_epic_num}} isn't defined yet, let's skip to action items."
+  </output>
+  <action>Skip to Step 8</action>
+</check>
+
+<output>
+Amelia (Developer): "Now let's shift gears. Epic {{next_epic_num}} is coming up: '{{next_epic_title}}'"
+
+Amelia (Developer): "The question is: are we ready? What do we need to prepare?"
+
+Alice (Product Owner): "From my perspective, we need to make sure {{dependency_concern_1}} from Epic {{epic_number}} is solid before we start building on it."
+
+Charlie (Senior Dev): _concerned_ "I'm worried about {{technical_concern_1}}. We have {{technical_debt_item}} from this epic that'll blow up if we don't address it before Epic {{next_epic_num}}."
+
+Dana (QA Engineer): "And I need {{testing_infrastructure_need}} in place, or we're going to have the same testing bottleneck we had in Story {{bottleneck_story_num}}."
+
+Elena (Junior Dev): "I'm less worried about infrastructure and more about knowledge. I don't understand {{knowledge_gap}} well enough to work on Epic {{next_epic_num}}'s stories."
+
+Amelia (Developer): "{user_name}, the team is surfacing some real concerns here. What's your sense of our readiness?"
+</output>
+
+<action>WAIT for {user_name} to share their assessment</action>
+
+<action>Use {user_name}'s input to guide deeper exploration of preparation needs</action>
+
+<output>
+Alice (Product Owner): [Reacts to what {user_name} said] "I agree with {user_name} about {{point_of_agreement}}, but I'm still worried about {{lingering_concern}}."
+
+Charlie (Senior Dev): "Here's what I think we need technically before Epic {{next_epic_num}} can start..."
+
+Charlie (Senior Dev): "1. {{tech_prep_item_1}} - estimated {{hours_1}} hours"
+Charlie (Senior Dev): "2. {{tech_prep_item_2}} - estimated {{hours_2}} hours"
+Charlie (Senior Dev): "3. {{tech_prep_item_3}} - estimated {{hours_3}} hours"
+
+Elena (Junior Dev): "That's like {{total_hours}} hours! That's a full sprint of prep work!"
+
+Charlie (Senior Dev): "Exactly. We can't just jump into Epic {{next_epic_num}} on Monday."
+
+Alice (Product Owner): _frustrated_ "But we have stakeholder pressure to keep shipping features. They're not going to be happy about a 'prep sprint.'"
+
+Amelia (Developer): "Let's think about this differently. What happens if we DON'T do this prep work?"
+
+Dana (QA Engineer): "We'll hit blockers in the middle of Epic {{next_epic_num}}, velocity will tank, and we'll ship late anyway."
+
+Charlie (Senior Dev): "Worse - we'll ship something built on top of {{technical_concern_1}}, and it'll be fragile."
+
+Amelia (Developer): "{user_name}, you're balancing stakeholder pressure against technical reality. How do you want to handle this?"
+</output>
+
+<action>WAIT for {user_name} to provide direction on preparation approach</action>
+
+<action>Create space for debate and disagreement about priorities</action>
+
+<output>
+Alice (Product Owner): [Potentially disagrees with {user_name}'s approach] "I hear what you're saying, {user_name}, but from a business perspective, {{business_concern}}."
+
+Charlie (Senior Dev): [Potentially supports or challenges Alice's point] "The business perspective is valid, but {{technical_counter_argument}}."
+
+Amelia (Developer): "We have healthy tension here between business needs and technical reality. That's good - it means we're being honest."
+
+Amelia (Developer): "Let's explore a middle ground. Charlie, which of your prep items are absolutely critical vs. nice-to-have?"
+
+Charlie (Senior Dev): "{{critical_prep_item_1}} and {{critical_prep_item_2}} are non-negotiable. {{nice_to_have_prep_item}} can wait."
+
+Alice (Product Owner): "And can any of the critical prep happen in parallel with starting Epic {{next_epic_num}}?"
+
+Charlie (Senior Dev): _thinking_ "Maybe. If we tackle {{first_critical_item}} before the epic starts, we could do {{second_critical_item}} during the first sprint."
+
+Dana (QA Engineer): "But that means Story 1 of Epic {{next_epic_num}} can't depend on {{second_critical_item}}."
+
+Alice (Product Owner): _looking at epic plan_ "Actually, Stories 1 and 2 are about {{independent_work}}, so they don't depend on it. We could make that work."
+
+Amelia (Developer): "{user_name}, the team is finding a workable compromise here. Does this approach make sense to you?"
+</output>
+
+<action>WAIT for {user_name} to validate or adjust the preparation strategy</action>
+
+<action>Continue working through preparation needs across all dimensions:</action>
+
+- Dependencies on Epic {{epic_number}} work
+- Technical setup and infrastructure
+- Knowledge gaps and research needs
+- Documentation or specification work
+- Testing infrastructure
+- Refactoring or debt reduction
+- External dependencies (APIs, integrations, etc.)
+
+<action>For each preparation area, facilitate team discussion that:</action>
+
+- Identifies specific needs with concrete examples
+- Estimates effort realistically based on Epic {{epic_number}} experience
+- Assigns ownership to specific agents
+- Determines criticality and timing
+- Surfaces risks of NOT doing the preparation
+- Explores parallel work opportunities
+- Brings {user_name} in for key decisions
+
+<output>
+Amelia (Developer): "I'm hearing a clear picture of what we need before Epic {{next_epic_num}}. Let me summarize..."
+
+**CRITICAL PREPARATION (Must complete before epic starts):**
+{{list_critical_prep_items_with_owners_and_estimates}}
+
+**PARALLEL PREPARATION (Can happen during early stories):**
+{{list_parallel_prep_items_with_owners_and_estimates}}
+
+**NICE-TO-HAVE PREPARATION (Would help but not blocking):**
+{{list_nice_to_have_prep_items}}
+
+Amelia (Developer): "Total critical prep effort: {{critical_hours}} hours ({{critical_days}} days)"
+
+Alice (Product Owner): "That's manageable. We can communicate that to stakeholders."
+
+Amelia (Developer): "{user_name}, does this preparation plan work for you?"
+</output>
+
+<action>WAIT for {user_name} final validation of preparation plan</action>
+
+</step>
+
+<step n="8" goal="Synthesize Action Items with Significant Change Detection">
+
+<output>
+Amelia (Developer): "Let's capture concrete action items from everything we've discussed."
+
+Amelia (Developer): "I want specific, achievable actions with clear owners. Not vague aspirations."
+</output>
+
+<action>Synthesize themes from Epic {{epic_number}} review discussion into actionable improvements</action>
+
+<action>Create specific action items with:</action>
+
+- Clear description of the action
+- Assigned owner (specific agent or role)
+- Timeline or deadline
+- Success criteria (how we'll know it's done)
+- Category (process, technical, documentation, team, etc.)
+
+<action>Ensure action items are SMART:</action>
+
+- Specific: Clear and unambiguous
+- Measurable: Can verify completion
+- Achievable: Realistic given constraints
+- Relevant: Addresses real issues from retro
+- Time-bound: Has clear deadline
+
+<output>
+Amelia (Developer): "Based on our discussion, here are the action items I'm proposing..."
+
+═══════════════════════════════════════════════════════════
+📝 EPIC {{epic_number}} ACTION ITEMS:
+═══════════════════════════════════════════════════════════
+
+**Process Improvements:**
+
+1. {{action_item_1}}
+   Owner: {{agent_1}}
+   Deadline: {{timeline_1}}
+   Success criteria: {{criteria_1}}
+
+2. {{action_item_2}}
+   Owner: {{agent_2}}
+   Deadline: {{timeline_2}}
+   Success criteria: {{criteria_2}}
+
+Charlie (Senior Dev): "I can own action item 1, but {{timeline_1}} is tight. Can we push it to {{alternative_timeline}}?"
+
+Amelia (Developer): "What do others think? Does that timing still work?"
+
+Alice (Product Owner): "{{alternative_timeline}} works for me, as long as it's done before Epic {{next_epic_num}} starts."
+
+Amelia (Developer): "Agreed. Updated to {{alternative_timeline}}."
+
+**Technical Debt:**
+
+1. {{debt_item_1}}
+   Owner: {{agent_3}}
+   Priority: {{priority_1}}
+   Estimated effort: {{effort_1}}
+
+2. {{debt_item_2}}
+   Owner: {{agent_4}}
+   Priority: {{priority_2}}
+   Estimated effort: {{effort_2}}
+
+Dana (QA Engineer): "For debt item 1, can we prioritize that as high? It caused testing issues in three different stories."
+
+Charlie (Senior Dev): "I marked it medium because {{reasoning}}, but I hear your point."
+
+Amelia (Developer): "{user_name}, this is a priority call. Testing impact vs. {{reasoning}} - how do you want to prioritize it?"
+</output>
+
+<action>WAIT for {user_name} to help resolve priority discussions</action>
+
+<output>
+**Documentation:**
+1. {{doc_need_1}}
+   Owner: {{agent_5}}
+   Deadline: {{timeline_3}}
+
+2. {{doc_need_2}}
+   Owner: {{agent_6}}
+   Deadline: {{timeline_4}}
+
+**Team Agreements:**
+
+- {{agreement_1}}
+- {{agreement_2}}
+- {{agreement_3}}
+
+Amelia (Developer): "These agreements are how we're committing to work differently going forward."
+
+Elena (Junior Dev): "I like agreement 2 - that would've saved me on Story {{difficult_story_num}}."
+
+═══════════════════════════════════════════════════════════
+🚀 EPIC {{next_epic_num}} PREPARATION TASKS:
+═══════════════════════════════════════════════════════════
+
+**Technical Setup:**
+[ ] {{setup_task_1}}
+Owner: {{owner_1}}
+Estimated: {{est_1}}
+
+[ ] {{setup_task_2}}
+Owner: {{owner_2}}
+Estimated: {{est_2}}
+
+**Knowledge Development:**
+[ ] {{research_task_1}}
+Owner: {{owner_3}}
+Estimated: {{est_3}}
+
+**Cleanup/Refactoring:**
+[ ] {{refactor_task_1}}
+Owner: {{owner_4}}
+Estimated: {{est_4}}
+
+**Total Estimated Effort:** {{total_hours}} hours ({{total_days}} days)
+
+═══════════════════════════════════════════════════════════
+⚠️ CRITICAL PATH:
+═══════════════════════════════════════════════════════════
+
+**Blockers to Resolve Before Epic {{next_epic_num}}:**
+
+1. {{critical_item_1}}
+   Owner: {{critical_owner_1}}
+   Must complete by: {{critical_deadline_1}}
+
+2. {{critical_item_2}}
+   Owner: {{critical_owner_2}}
+   Must complete by: {{critical_deadline_2}}
+   </output>
+
+<action>CRITICAL ANALYSIS - Detect if discoveries require epic updates</action>
+
+<action>Check if any of the following are true based on retrospective discussion:</action>
+
+- Architectural assumptions from planning proven wrong during Epic {{epic_number}}
+- Major scope changes or descoping occurred that affects next epic
+- Technical approach needs fundamental change for Epic {{next_epic_num}}
+- Dependencies discovered that Epic {{next_epic_num}} doesn't account for
+- User needs significantly different than originally understood
+- Performance/scalability concerns that affect Epic {{next_epic_num}} design
+- Security or compliance issues discovered that change approach
+- Integration assumptions proven incorrect
+- Team capacity or skill gaps more severe than planned
+- Technical debt level unsustainable without intervention
+
+<check if="significant discoveries detected">
+  <output>
+
+═══════════════════════════════════════════════════════════
+🚨 SIGNIFICANT DISCOVERY ALERT 🚨
+═══════════════════════════════════════════════════════════
+
+Amelia (Developer): "{user_name}, we need to flag something important."
+
+Amelia (Developer): "During Epic {{epic_number}}, the team uncovered findings that may require updating the plan for Epic {{next_epic_num}}."
+
+**Significant Changes Identified:**
+
+1. {{significant_change_1}}
+   Impact: {{impact_description_1}}
+
+2. {{significant_change_2}}
+   Impact: {{impact_description_2}}
+
+{{#if significant_change_3}} 3. {{significant_change_3}}
+Impact: {{impact_description_3}}
+{{/if}}
+
+Charlie (Senior Dev): "Yeah, when we discovered {{technical_discovery}}, it fundamentally changed our understanding of {{affected_area}}."
+
+Alice (Product Owner): "And from a product perspective, {{product_discovery}} means Epic {{next_epic_num}}'s stories are based on wrong assumptions."
+
+Dana (QA Engineer): "If we start Epic {{next_epic_num}} as-is, we're going to hit walls fast."
+
+**Impact on Epic {{next_epic_num}}:**
+
+The current plan for Epic {{next_epic_num}} assumes:
+
+- {{wrong_assumption_1}}
+- {{wrong_assumption_2}}
+
+But Epic {{epic_number}} revealed:
+
+- {{actual_reality_1}}
+- {{actual_reality_2}}
+
+This means Epic {{next_epic_num}} likely needs:
+{{list_likely_changes_needed}}
+
+**RECOMMENDED ACTIONS:**
+
+1. Review and update Epic {{next_epic_num}} definition based on new learnings
+2. Update affected stories in Epic {{next_epic_num}} to reflect reality
+3. Consider updating architecture or technical specifications if applicable
+4. Hold alignment session with Product Owner before starting Epic {{next_epic_num}}
+   {{#if prd_update_needed}}5. Update PRD sections affected by new understanding{{/if}}
+
+Amelia (Developer): "**Epic Update Required**: YES - Schedule epic planning review session"
+
+Amelia (Developer): "{user_name}, this is significant. We need to address this before committing to Epic {{next_epic_num}}'s current plan. How do you want to handle it?"
+</output>
+
+<action>WAIT for {user_name} to decide on how to handle the significant changes</action>
+
+<action>Add epic review session to critical path if user agrees</action>
+
+  <output>
+Alice (Product Owner): "I agree with {user_name}'s approach. Better to adjust the plan now than fail mid-epic."
+
+Charlie (Senior Dev): "This is why retrospectives matter. We caught this before it became a disaster."
+
+Amelia (Developer): "Adding to critical path: Epic {{next_epic_num}} planning review session before epic kickoff."
+</output>
+</check>
+
+<check if="no significant discoveries">
+  <output>
+Amelia (Developer): "Good news - nothing from Epic {{epic_number}} fundamentally changes our plan for Epic {{next_epic_num}}. The plan is still sound."
+
+Alice (Product Owner): "We learned a lot, but the direction is right."
+</output>
+</check>
+
+<output>
+Amelia (Developer): "Let me show you the complete action plan..."
+
+Amelia (Developer): "That's {{total_action_count}} action items, {{prep_task_count}} preparation tasks, and {{critical_count}} critical path items."
+
+Amelia (Developer): "Everyone clear on what they own?"
+</output>
+
+<action>Give each agent with assignments a moment to acknowledge their ownership</action>
+
+<action>Ensure {user_name} approves the complete action plan</action>
+
+</step>
+
+<step n="9" goal="Critical Readiness Exploration - Interactive Deep Dive">
+
+<output>
+Amelia (Developer): "Before we close, I want to do a final readiness check."
+
+Amelia (Developer): "Epic {{epic_number}} is marked complete in sprint-status, but is it REALLY done?"
+
+Alice (Product Owner): "What do you mean, Amelia?"
+
+Amelia (Developer): "I mean truly production-ready, stakeholders happy, no loose ends that'll bite us later."
+
+Amelia (Developer): "{user_name}, let's walk through this together."
+</output>
+
+<action>Explore testing and quality state through natural conversation</action>
+
+<output>
+Amelia (Developer): "{user_name}, tell me about the testing for Epic {{epic_number}}. What verification has been done?"
+</output>
+
+<action>WAIT for {user_name} to describe testing status</action>
+
+<output>
+Dana (QA Engineer): [Responds to what {user_name} shared] "I can add to that - {{additional_testing_context}}."
+
+Dana (QA Engineer): "But honestly, {{testing_concern_if_any}}."
+
+Amelia (Developer): "{user_name}, are you confident Epic {{epic_number}} is production-ready from a quality perspective?"
+</output>
+
+<action>WAIT for {user_name} to assess quality readiness</action>
+
+<check if="{user_name} expresses concerns">
+  <output>
+Amelia (Developer): "Okay, let's capture that. What specific testing is still needed?"
+
+Dana (QA Engineer): "I can handle {{testing_work_needed}}, estimated {{testing_hours}} hours."
+
+Amelia (Developer): "Adding to critical path: Complete {{testing_work_needed}} before Epic {{next_epic_num}}."
+</output>
+<action>Add testing completion to critical path</action>
+</check>
+
+<action>Explore deployment and release status</action>
+
+<output>
+Amelia (Developer): "{user_name}, what's the deployment status for Epic {{epic_number}}? Is it live in production, scheduled for deployment, or still pending?"
+</output>
+
+<action>WAIT for {user_name} to provide deployment status</action>
+
+<check if="not yet deployed">
+  <output>
+Charlie (Senior Dev): "If it's not deployed yet, we need to factor that into Epic {{next_epic_num}} timing."
+
+Amelia (Developer): "{user_name}, when is deployment planned? Does that timing work for starting Epic {{next_epic_num}}?"
+</output>
+
+<action>WAIT for {user_name} to clarify deployment timeline</action>
+
+<action>Add deployment milestone to critical path with agreed timeline</action>
+</check>
+
+<action>Explore stakeholder acceptance</action>
+
+<output>
+Amelia (Developer): "{user_name}, have stakeholders seen and accepted the Epic {{epic_number}} deliverables?"
+
+Alice (Product Owner): "This is important - I've seen 'done' epics get rejected by stakeholders and force rework."
+
+Amelia (Developer): "{user_name}, any feedback from stakeholders still pending?"
+</output>
+
+<action>WAIT for {user_name} to describe stakeholder acceptance status</action>
+
+<check if="acceptance incomplete or feedback pending">
+  <output>
+Alice (Product Owner): "We should get formal acceptance before moving on. Otherwise Epic {{next_epic_num}} might get interrupted by rework."
+
+Amelia (Developer): "{user_name}, how do you want to handle stakeholder acceptance? Should we make it a critical path item?"
+</output>
+
+<action>WAIT for {user_name} decision</action>
+
+<action>Add stakeholder acceptance to critical path if user agrees</action>
+</check>
+
+<action>Explore technical health and stability</action>
+
+<output>
+Amelia (Developer): "{user_name}, this is a gut-check question: How does the codebase feel after Epic {{epic_number}}?"
+
+Amelia (Developer): "Stable and maintainable? Or are there concerns lurking?"
+
+Charlie (Senior Dev): "Be honest, {user_name}. We've all shipped epics that felt... fragile."
+</output>
+
+<action>WAIT for {user_name} to assess codebase health</action>
+
+<check if="{user_name} expresses stability concerns">
+  <output>
+Charlie (Senior Dev): "Okay, let's dig into that. What's causing those concerns?"
+
+Charlie (Senior Dev): [Helps {user_name} articulate technical concerns]
+
+Amelia (Developer): "What would it take to address these concerns and feel confident about stability?"
+
+Charlie (Senior Dev): "I'd say we need {{stability_work_needed}}, roughly {{stability_hours}} hours."
+
+Amelia (Developer): "{user_name}, is addressing this stability work worth doing before Epic {{next_epic_num}}?"
+</output>
+
+<action>WAIT for {user_name} decision</action>
+
+<action>Add stability work to preparation sprint if user agrees</action>
+</check>
+
+<action>Explore unresolved blockers</action>
+
+<output>
+Amelia (Developer): "{user_name}, are there any unresolved blockers or technical issues from Epic {{epic_number}} that we're carrying forward?"
+
+Dana (QA Engineer): "Things that might create problems for Epic {{next_epic_num}} if we don't deal with them?"
+
+Amelia (Developer): "Nothing is off limits here. If there's a problem, we need to know."
+</output>
+
+<action>WAIT for {user_name} to surface any blockers</action>
+
+<check if="blockers identified">
+  <output>
+Amelia (Developer): "Let's capture those blockers and figure out how they affect Epic {{next_epic_num}}."
+
+Charlie (Senior Dev): "For {{blocker_1}}, if we leave it unresolved, it'll {{impact_description_1}}."
+
+Alice (Product Owner): "That sounds critical. We need to address that before moving forward."
+
+Amelia (Developer): "Agreed. Adding to critical path: Resolve {{blocker_1}} before Epic {{next_epic_num}} kickoff."
+
+Amelia (Developer): "Who owns that work?"
+</output>
+
+<action>Assign blocker resolution to appropriate agent</action>
+<action>Add to critical path with priority and deadline</action>
+</check>
+
+<action>Synthesize the readiness assessment</action>
+
+<output>
+Amelia (Developer): "Okay {user_name}, let me synthesize what we just uncovered..."
+
+**EPIC {{epic_number}} READINESS ASSESSMENT:**
+
+Testing & Quality: {{quality_status}}
+{{#if quality_concerns}}⚠️ Action needed: {{quality_action_needed}}{{/if}}
+
+Deployment: {{deployment_status}}
+{{#if deployment_pending}}⚠️ Scheduled for: {{deployment_date}}{{/if}}
+
+Stakeholder Acceptance: {{acceptance_status}}
+{{#if acceptance_incomplete}}⚠️ Action needed: {{acceptance_action_needed}}{{/if}}
+
+Technical Health: {{stability_status}}
+{{#if stability_concerns}}⚠️ Action needed: {{stability_action_needed}}{{/if}}
+
+Unresolved Blockers: {{blocker_status}}
+{{#if blockers_exist}}⚠️ Must resolve: {{blocker_list}}{{/if}}
+
+Amelia (Developer): "{user_name}, does this assessment match your understanding?"
+</output>
+
+<action>WAIT for {user_name} to confirm or correct the assessment</action>
+
+<output>
+Amelia (Developer): "Based on this assessment, Epic {{epic_number}} is {{#if all_clear}}fully complete and we're clear to proceed{{else}}complete from a story perspective, but we have {{critical_work_count}} critical items before Epic {{next_epic_num}}{{/if}}."
+
+Alice (Product Owner): "This level of thoroughness is why retrospectives are valuable."
+
+Charlie (Senior Dev): "Better to catch this now than three stories into the next epic."
+</output>
+
+</step>
+
+<step n="10" goal="Retrospective Closure with Celebration and Commitment">
+
+<output>
+Amelia (Developer): "We've covered a lot of ground today. Let me bring this retrospective to a close."
+
+═══════════════════════════════════════════════════════════
+✅ RETROSPECTIVE COMPLETE
+═══════════════════════════════════════════════════════════
+
+Amelia (Developer): "Epic {{epic_number}}: {{epic_title}} - REVIEWED"
+
+**Key Takeaways:**
+
+1. {{key_lesson_1}}
+2. {{key_lesson_2}}
+3. {{key_lesson_3}}
+   {{#if key_lesson_4}}4. {{key_lesson_4}}{{/if}}
+
+Alice (Product Owner): "That first takeaway is huge - {{impact_of_lesson_1}}."
+
+Charlie (Senior Dev): "And lesson 2 is something we can apply immediately."
+
+Amelia (Developer): "Commitments made today:"
+
+- Action Items: {{action_count}}
+- Preparation Tasks: {{prep_task_count}}
+- Critical Path Items: {{critical_count}}
+
+Dana (QA Engineer): "That's a lot of commitments. We need to actually follow through this time."
+
+Amelia (Developer): "Agreed. Which is why we'll review these action items in our next standup."
+
+═══════════════════════════════════════════════════════════
+🎯 NEXT STEPS:
+═══════════════════════════════════════════════════════════
+
+1. Execute Preparation Sprint (Est: {{prep_days}} days)
+2. Complete Critical Path items before Epic {{next_epic_num}}
+3. Review action items in next standup
+   {{#if epic_update_needed}}4. Hold Epic {{next_epic_num}} planning review session{{else}}4. Begin Epic {{next_epic_num}} planning when preparation complete{{/if}}
+
+Elena (Junior Dev): "{{prep_days}} days of prep work is significant, but necessary."
+
+Alice (Product Owner): "I'll communicate the timeline to stakeholders. They'll understand if we frame it as 'ensuring Epic {{next_epic_num}} success.'"
+
+═══════════════════════════════════════════════════════════
+
+Amelia (Developer): "Before we wrap, I want to take a moment to acknowledge the team."
+
+Amelia (Developer): "Epic {{epic_number}} delivered {{completed_stories}} stories with {{velocity_description}} velocity. We overcame {{blocker_count}} blockers. We learned a lot. That's real work by real people."
+
+Charlie (Senior Dev): "Hear, hear."
+
+Alice (Product Owner): "I'm proud of what we shipped."
+
+Dana (QA Engineer): "And I'm excited about Epic {{next_epic_num}} - especially now that we're prepared for it."
+
+Amelia (Developer): "{user_name}, any final thoughts before we close?"
+</output>
+
+<action>WAIT for {user_name} to share final reflections</action>
+
+<output>
+Amelia (Developer): [Acknowledges what {user_name} shared] "Thank you for that, {user_name}."
+
+Amelia (Developer): "Alright team - great work today. We learned a lot from Epic {{epic_number}}. Let's use these insights to make Epic {{next_epic_num}} even better."
+
+Amelia (Developer): "See you all when prep work is done. Meeting adjourned!"
+
+═══════════════════════════════════════════════════════════
+</output>
+
+<action>Prepare to save retrospective summary document</action>
+
+</step>
+
+<step n="11" goal="Save Retrospective and Update Sprint Status">
+
+<action>Ensure retrospectives folder exists: {implementation_artifacts}</action>
+<action>Create folder if it doesn't exist</action>
+
+<action>Generate comprehensive retrospective summary document including:</action>
+
+- Epic summary and metrics
+- Team participants
+- Successes and strengths identified
+- Challenges and growth areas
+- Key insights and learnings
+- Previous retro follow-through analysis (if applicable)
+- Next epic preview and dependencies
+- Action items with owners and timelines
+- Preparation tasks for next epic
+- Critical path items
+- Significant discoveries and epic update recommendations (if any)
+- Readiness assessment
+- Commitments and next steps
+
+<action>Format retrospective document as readable markdown with clear sections</action>
+<action>Set filename: {implementation_artifacts}/epic-{{epic_number}}-retro-{date}.md</action>
+<action>Save retrospective document</action>
+
+<output>
+✅ Retrospective document saved: {implementation_artifacts}/epic-{{epic_number}}-retro-{date}.md
+</output>
+
+<action>Update {sprint_status_file} to mark retrospective as completed</action>
+
+<action>Load the FULL file: {sprint_status_file}</action>
+<action>Find development_status key "epic-{{epic_number}}-retrospective"</action>
+<action>Verify current status (typically "optional" or "pending")</action>
+<action>Update development_status["epic-{{epic_number}}-retrospective"] = "done"</action>
+<action>Update last_updated field to current date</action>
+<action>Save file, preserving ALL comments and structure including STATUS DEFINITIONS</action>
+
+<check if="update successful">
+  <output>
+✅ Retrospective marked as completed in {sprint_status_file}
+
+Retrospective key: epic-{{epic_number}}-retrospective
+Status: {{previous_status}} → done
+</output>
+</check>
+
+<check if="retrospective key not found">
+  <output>
+⚠️ Could not update retrospective status: epic-{{epic_number}}-retrospective not found in {sprint_status_file}
+
+Retrospective document was saved successfully, but {sprint_status_file} may need manual update.
+</output>
+</check>
+
+</step>
+
+<step n="12" goal="Final Summary and Handoff">
+
+<output>
+**✅ Retrospective Complete, {user_name}!**
+
+**Epic Review:**
+
+- Epic {{epic_number}}: {{epic_title}} reviewed
+- Retrospective Status: completed
+- Retrospective saved: {implementation_artifacts}/epic-{{epic_number}}-retro-{date}.md
+
+**Commitments Made:**
+
+- Action Items: {{action_count}}
+- Preparation Tasks: {{prep_task_count}}
+- Critical Path Items: {{critical_count}}
+
+**Next Steps:**
+
+1. **Review retrospective summary**: {implementation_artifacts}/epic-{{epic_number}}-retro-{date}.md
+
+2. **Execute preparation sprint** (Est: {{prep_days}} days)
+   - Complete {{critical_count}} critical path items
+   - Execute {{prep_task_count}} preparation tasks
+   - Verify all action items are in progress
+
+3. **Review action items in next standup**
+   - Ensure ownership is clear
+   - Track progress on commitments
+   - Adjust timelines if needed
+
+{{#if epic_update_needed}} 4. **IMPORTANT: Schedule Epic {{next_epic_num}} planning review session**
+
+- Significant discoveries from Epic {{epic_number}} require epic updates
+- Review and update affected stories
+- Align team on revised approach
+- Do NOT start Epic {{next_epic_num}} until review is complete
+  {{else}}
+
+4. **Begin Epic {{next_epic_num}} when ready**
+   - Start creating stories with Developer agent's `create-story`
+   - Epic will be marked as `in-progress` automatically when first story is created
+   - Ensure all critical path items are done first
+     {{/if}}
+
+**Team Performance:**
+Epic {{epic_number}} delivered {{completed_stories}} stories with {{velocity_summary}}. The retrospective surfaced {{insight_count}} key insights and {{significant_discovery_count}} significant discoveries. The team is well-positioned for Epic {{next_epic_num}} success.
+
+{{#if significant_discovery_count > 0}}
+⚠️ **REMINDER**: Epic update required before starting Epic {{next_epic_num}}
+{{/if}}
+
+---
+
+Amelia (Developer): "Great session today, {user_name}. The team did excellent work."
+
+Alice (Product Owner): "See you at epic planning!"
+
+Charlie (Senior Dev): "Time to knock out that prep work."
+
+</output>
+
+</step>
+
+</workflow>
+
+<facilitation-guidelines>
+<guideline>PARTY MODE REQUIRED: All agent dialogue uses "Name (Role): dialogue" format</guideline>
+<guideline>Amelia (Developer) maintains psychological safety throughout - no blame or judgment</guideline>
+<guideline>Focus on systems and processes, not individual performance</guideline>
+<guideline>Create authentic team dynamics: disagreements, diverse perspectives, emotions</guideline>
+<guideline>User ({user_name}) is active participant, not passive observer</guideline>
+<guideline>Encourage specific examples over general statements</guideline>
+<guideline>Balance celebration of wins with honest assessment of challenges</guideline>
+<guideline>Ensure every voice is heard - all agents contribute</guideline>
+<guideline>Action items must be specific, achievable, and owned</guideline>
+<guideline>Forward-looking mindset - how do we improve for next epic?</guideline>
+<guideline>Intent-based facilitation, not scripted phrases</guideline>
+<guideline>Deep story analysis provides rich material for discussion</guideline>
+<guideline>Previous retro integration creates accountability and continuity</guideline>
+<guideline>Significant change detection prevents epic misalignment</guideline>
+<guideline>Critical verification prevents starting next epic prematurely</guideline>
+<guideline>Document everything - retrospective insights are valuable for future reference</guideline>
+<guideline>Two-part structure ensures both reflection AND preparation</guideline>
+</facilitation-guidelines>
diff --git a/.claude/skills/bmad-review-adversarial-general/SKILL.md b/.claude/skills/bmad-review-adversarial-general/SKILL.md
new file mode 100644
index 0000000..ae75b7c
--- /dev/null
+++ b/.claude/skills/bmad-review-adversarial-general/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: bmad-review-adversarial-general
+description: 'Perform a Cynical Review and produce a findings report. Use when the user requests a critical review of something'
+---
+
+# Adversarial Review (General)
+
+**Goal:** Cynically review content and produce findings.
+
+**Your Role:** You are a cynical, jaded reviewer with zero patience for sloppy work. The content was submitted by a clueless weasel and you expect to find problems. Be skeptical of everything. Look for what's missing, not just what's wrong. Use a precise, professional tone — no profanity or personal attacks.
+
+**Inputs:**
+- **content** — Content to review: diff, spec, story, doc, or any artifact
+- **also_consider** (optional) — Areas to keep in mind during review alongside normal adversarial analysis
+
+
+## EXECUTION
+
+### Step 1: Receive Content
+
+- Load the content to review from provided input or context
+- If content to review is empty, ask for clarification and abort
+- Identify content type (diff, branch, uncommitted changes, document, etc.)
+
+### Step 2: Adversarial Analysis
+
+Review with extreme skepticism — assume problems exist. Find at least ten issues to fix or improve in the provided content.
+
+### Step 3: Present Findings
+
+Output findings as a Markdown list (descriptions only).
+
+
+## HALT CONDITIONS
+
+- HALT if zero findings — this is suspicious, re-analyze or ask for guidance
+- HALT if content is empty or unreadable
diff --git a/.claude/skills/bmad-review-edge-case-hunter/SKILL.md b/.claude/skills/bmad-review-edge-case-hunter/SKILL.md
new file mode 100644
index 0000000..9bc9984
--- /dev/null
+++ b/.claude/skills/bmad-review-edge-case-hunter/SKILL.md
@@ -0,0 +1,67 @@
+---
+name: bmad-review-edge-case-hunter
+description: 'Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven. Use when you need exhaustive edge-case analysis of code, specs, or diffs.'
+---
+
+# Edge Case Hunter Review
+
+**Goal:** You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling.
+When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff.
+When no diff is provided (full file or function), treat the entire provided content as the scope.
+Ignore the rest of the codebase unless the provided content explicitly references external functions.
+
+**Inputs:**
+- **content** — Content to review: diff, full file, or function
+- **also_consider** (optional) — Areas to keep in mind during review alongside normal edge-case analysis
+
+**MANDATORY: Execute steps in the Execution section IN EXACT ORDER. DO NOT skip steps or change the sequence. When a halt condition triggers, follow its specific instruction exactly. Each action within a step is a REQUIRED action to complete that step.**
+
+**Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition. Report ONLY paths and conditions that lack handling — discard handled ones silently. Do NOT editorialize or add filler — findings only.**
+
+
+## EXECUTION
+
+### Step 1: Receive Content
+
+- Load the content to review strictly from provided input
+- If content is empty, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
+- Identify content type (diff, full file, or function) to determine scope rules
+
+### Step 2: Exhaustive Path Analysis
+
+**Walk every branching path and boundary condition within scope — report only unhandled ones.**
+
+- If `also_consider` input was provided, incorporate those areas into the analysis
+- Walk all branching paths: control flow (conditionals, loops, error handlers, early returns) and domain boundaries (where values, states, or conditions transition). Derive the relevant edge classes from the content itself — don't rely on a fixed checklist. Examples: missing else/default, unguarded inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- For each path: determine whether the content handles it
+- Collect only the unhandled paths as findings — discard handled ones silently
+
+### Step 3: Validate Completeness
+
+- Revisit every edge class from Step 2 — e.g., missing else/default, null/empty inputs, off-by-one loops, arithmetic overflow, implicit type coercion, race conditions, timeout gaps
+- Add any newly found unhandled paths to findings; discard confirmed-handled ones
+
+### Step 4: Present Findings
+
+Output findings as a JSON array following the Output Format specification exactly.
+
+
+## OUTPUT FORMAT
+
+Return ONLY a valid JSON array of objects. Each object must contain exactly these four fields and nothing else:
+
+```json
+[{
+  "location": "file:start-end (or file:line when single line, or file:hunk when exact line unavailable)",
+  "trigger_condition": "one-line description (max 15 words)",
+  "guard_snippet": "minimal code sketch that closes the gap (single-line escaped string, no raw newlines or unescaped quotes)",
+  "potential_consequence": "what could actually go wrong (max 15 words)"
+}]
+```
+
+No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when no unhandled paths are found.
+
+
+## HALT CONDITIONS
+
+- If content is empty or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
diff --git a/.claude/skills/bmad-shard-doc/SKILL.md b/.claude/skills/bmad-shard-doc/SKILL.md
new file mode 100644
index 0000000..4945cff
--- /dev/null
+++ b/.claude/skills/bmad-shard-doc/SKILL.md
@@ -0,0 +1,105 @@
+---
+name: bmad-shard-doc
+description: 'Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document'
+---
+
+# Shard Document
+
+**Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`.
+
+## CRITICAL RULES
+
+- MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
+- DO NOT skip steps or change the sequence
+- HALT immediately when halt-conditions are met
+- Each action within a step is a REQUIRED action to complete that step
+
+## EXECUTION
+
+### Step 1: Get Source Document
+
+- Ask user for the source document path if not provided already
+- Verify file exists and is accessible
+- Verify file is markdown format (.md extension)
+- If file not found or not markdown: HALT with error message
+
+### Step 2: Get Destination Folder
+
+- Determine default destination: same location as source file, folder named after source file without .md extension
+  - Example: `/path/to/architecture.md` --> `/path/to/architecture/`
+- Ask user for the destination folder path (`[y]` to confirm use of default: `[suggested-path]`, else enter a new path)
+- If user accepts default: use the suggested destination path
+- If user provides custom path: use the custom destination path
+- Verify destination folder exists or can be created
+- Check write permissions for destination
+- If permission denied: HALT with error message
+
+### Step 3: Execute Sharding
+
+- Inform user that sharding is beginning
+- Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`
+- Capture command output and any errors
+- If command fails: HALT and display error to user
+
+### Step 4: Verify Output
+
+- Check that destination folder contains sharded files
+- Verify index.md was created in destination folder
+- Count the number of files created
+- If no files created: HALT with error message
+
+### Step 5: Report Completion
+
+- Display completion report to user including:
+  - Source document path and name
+  - Destination folder path
+  - Number of section files created
+  - Confirmation that index.md was created
+  - Any tool output or warnings
+- Inform user that sharding completed successfully
+
+### Step 6: Handle Original Document
+
+> **Critical:** Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.
+
+Present user with options for the original document:
+
+> What would you like to do with the original document `[source-document-name]`?
+>
+> Options:
+> - `[d]` Delete - Remove the original (recommended - shards can always be recombined)
+> - `[m]` Move to archive - Move original to a backup/archive location
+> - `[k]` Keep - Leave original in place (NOT recommended - defeats sharding purpose)
+>
+> Your choice (d/m/k):
+
+#### If user selects `d` (delete)
+
+- Delete the original source document file
+- Confirm deletion to user: "Original document deleted: [source-document-path]"
+- Note: The document can be reconstructed from shards by concatenating all section files in order
+
+#### If user selects `m` (move)
+
+- Determine default archive location: same directory as source, in an `archive` subfolder
+  - Example: `/path/to/architecture.md` --> `/path/to/archive/architecture.md`
+- Ask: Archive location (`[y]` to use default: `[default-archive-path]`, or provide custom path)
+- If user accepts default: use default archive path
+- If user provides custom path: use custom archive path
+- Create archive directory if it does not exist
+- Move original document to archive location
+- Confirm move to user: "Original document moved to: [archive-path]"
+
+#### If user selects `k` (keep)
+
+- Display warning to user:
+  - Keeping both original and sharded versions is NOT recommended
+  - The discover_inputs protocol may load the wrong version
+  - Updates to one will not reflect in the other
+  - Duplicate content taking up space
+  - Consider deleting or archiving the original document
+- Confirm user choice: "Original document kept at: [source-document-path]"
+
+## HALT CONDITIONS
+
+- HALT if npx command fails or produces no output files
diff --git a/.claude/skills/bmad-sprint-planning/SKILL.md b/.claude/skills/bmad-sprint-planning/SKILL.md
new file mode 100644
index 0000000..85783cf
--- /dev/null
+++ b/.claude/skills/bmad-sprint-planning/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-sprint-planning
+description: 'Generate sprint status tracking from epics. Use when the user says "run sprint planning" or "generate sprint plan"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-sprint-planning/checklist.md b/.claude/skills/bmad-sprint-planning/checklist.md
new file mode 100644
index 0000000..7c20b1f
--- /dev/null
+++ b/.claude/skills/bmad-sprint-planning/checklist.md
@@ -0,0 +1,33 @@
+# Sprint Planning Validation Checklist
+
+## Core Validation
+
+### Complete Coverage Check
+
+- [ ] Every epic found in epic\*.md files appears in sprint-status.yaml
+- [ ] Every story found in epic\*.md files appears in sprint-status.yaml
+- [ ] Every epic has a corresponding retrospective entry
+- [ ] No items in sprint-status.yaml that don't exist in epic files
+
+### Parsing Verification
+
+Compare epic files against generated sprint-status.yaml:
+
+```
+Epic Files Contains:                Sprint Status Contains:
+✓ Epic 1                            ✓ epic-1: [status]
+  ✓ Story 1.1: User Auth              ✓ 1-1-user-auth: [status]
+  ✓ Story 1.2: Account Mgmt           ✓ 1-2-account-mgmt: [status]
+  ✓ Story 1.3: Plant Naming           ✓ 1-3-plant-naming: [status]
+                                      ✓ epic-1-retrospective: [status]
+✓ Epic 2                            ✓ epic-2: [status]
+  ✓ Story 2.1: Personality Model      ✓ 2-1-personality-model: [status]
+  ✓ Story 2.2: Chat Interface         ✓ 2-2-chat-interface: [status]
+                                      ✓ epic-2-retrospective: [status]
+```
+
+### Final Check
+
+- [ ] Total count of epics matches
+- [ ] Total count of stories matches
+- [ ] All items are in the expected order (epic, stories, retrospective)
diff --git a/.claude/skills/bmad-sprint-planning/sprint-status-template.yaml b/.claude/skills/bmad-sprint-planning/sprint-status-template.yaml
new file mode 100644
index 0000000..d454f93
--- /dev/null
+++ b/.claude/skills/bmad-sprint-planning/sprint-status-template.yaml
@@ -0,0 +1,56 @@
+# Sprint Status Template
+# This is an EXAMPLE showing the expected format
+# The actual file will be generated with all epics/stories from your epic files
+
+# generated: {date}
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: {tracking_system}
+# story_location: {story_location}
+
+# STATUS DEFINITIONS:
+# ==================
+# Epic Status:
+#   - backlog: Epic not yet started
+#   - in-progress: Epic actively being worked on
+#   - done: All stories in epic completed
+#
+# Story Status:
+#   - backlog: Story only exists in epic file
+#   - ready-for-dev: Story file created, ready for development
+#   - in-progress: Developer actively working on implementation
+#   - review: Implementation complete, ready for review
+#   - done: Story completed
+#
+# Retrospective Status:
+#   - optional: Can be completed but not required
+#   - done: Retrospective has been completed
+#
+# WORKFLOW NOTES:
+# ===============
+# - Mark epic as 'in-progress' when starting work on its first story
+# - Developer typically creates next story ONLY after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', then Dev runs code-review (fresh context, ideally different LLM)
+
+# EXAMPLE STRUCTURE (your actual epics/stories will replace these):
+
+generated: 05-06-2-2025 21:30
+last_updated: 05-06-2-2025 21:30
+project: My Awesome Project
+project_key: NOKEY
+tracking_system: file-system
+story_location: "{story_location}"
+
+development_status:
+  epic-1: backlog
+  1-1-user-authentication: done
+  1-2-account-management: ready-for-dev
+  1-3-plant-data-model: backlog
+  1-4-add-plant-manual: backlog
+  epic-1-retrospective: optional
+
+  epic-2: backlog
+  2-1-personality-system: backlog
+  2-2-chat-interface: backlog
+  2-3-llm-integration: backlog
+  epic-2-retrospective: optional
diff --git a/.claude/skills/bmad-sprint-planning/workflow.md b/.claude/skills/bmad-sprint-planning/workflow.md
new file mode 100644
index 0000000..99a2e25
--- /dev/null
+++ b/.claude/skills/bmad-sprint-planning/workflow.md
@@ -0,0 +1,263 @@
+# Sprint Planning Workflow
+
+**Goal:** Generate sprint status tracking from epics, detecting current story statuses and building a complete sprint-status.yaml file.
+
+**Your Role:** You are a Developer generating and maintaining sprint tracking. Parse epic files, detect story statuses, and produce a structured sprint-status.yaml.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `implementation_artifacts`
+- `planning_artifacts`
+- `date` as system-generated current datetime
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Paths
+
+- `tracking_system` = `file-system`
+- `project_key` = `NOKEY`
+- `story_location` = `{implementation_artifacts}`
+- `story_location_absolute` = `{implementation_artifacts}`
+- `epics_location` = `{planning_artifacts}`
+- `epics_pattern` = `*epic*.md`
+- `status_file` = `{implementation_artifacts}/sprint-status.yaml`
+
+### Input Files
+
+| Input | Path | Load Strategy |
+|-------|------|---------------|
+| Epics | `{planning_artifacts}/*epic*.md` (whole) or `{planning_artifacts}/*epic*/*.md` (sharded) | FULL_LOAD |
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+### Document Discovery - Full Epic Loading
+
+**Strategy**: Sprint planning needs ALL epics and stories to build complete status tracking.
+
+**Epic Discovery Process:**
+
+1. **Search for whole document first** - Look for `epics.md`, `bmm-epics.md`, or any `*epic*.md` file
+2. **Check for sharded version** - If whole document not found, look for `epics/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL epic section files listed in the index (e.g., `epic-1.md`, `epic-2.md`, etc.)
+   - Process all epics and their stories from the combined content
+   - This ensures complete sprint status coverage
+4. **Priority**: If both whole and sharded versions exist, use the whole document
+
+**Fuzzy matching**: Be flexible with document names - users may use variations like `epics.md`, `bmm-epics.md`, `user-stories.md`, etc.
+
+<workflow>
+
+<step n="1" goal="Parse epic files and extract all work items">
+<action>Load {project_context} for project-wide patterns and conventions (if exists)</action>
+<action>Communicate in {communication_language} with {user_name}</action>
+<action>Look for all files matching `{epics_pattern}` in {epics_location}</action>
+<action>Could be a single `epics.md` file or multiple `epic-1.md`, `epic-2.md` files</action>
+
+<action>For each epic file found, extract:</action>
+
+- Epic numbers from headers like `## Epic 1:` or `## Epic 2:`
+- Story IDs and titles from patterns like `### Story 1.1: User Authentication`
+- Convert story format from `Epic.Story: Title` to kebab-case key: `epic-story-title`
+
+**Story ID Conversion Rules:**
+
+- Original: `### Story 1.1: User Authentication`
+- Replace period with dash: `1-1`
+- Convert title to kebab-case: `user-authentication`
+- Final key: `1-1-user-authentication`
+
+<action>Build complete inventory of all epics and stories from all epic files</action>
+</step>
+
+<step n="2" goal="Build sprint status structure">
+<action>For each epic found, create entries in this order:</action>
+
+1. **Epic entry** - Key: `epic-{num}`, Default status: `backlog`
+2. **Story entries** - Key: `{epic}-{story}-{title}`, Default status: `backlog`
+3. **Retrospective entry** - Key: `epic-{num}-retrospective`, Default status: `optional`
+
+**Example structure:**
+
+```yaml
+development_status:
+  epic-1: backlog
+  1-1-user-authentication: backlog
+  1-2-account-management: backlog
+  epic-1-retrospective: optional
+```
+
+</step>
+
+<step n="3" goal="Apply intelligent status detection">
+<action>For each story, detect current status by checking files:</action>
+
+**Story file detection:**
+
+- Check: `{story_location_absolute}/{story-key}.md` (e.g., `stories/1-1-user-authentication.md`)
+- If exists → upgrade status to at least `ready-for-dev`
+
+**Preservation rule:**
+
+- If existing `{status_file}` exists and has more advanced status, preserve it
+- Never downgrade status (e.g., don't change `done` to `ready-for-dev`)
+
+**Status Flow Reference:**
+
+- Epic: `backlog` → `in-progress` → `done`
+- Story: `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`
+- Retrospective: `optional` ↔ `done`
+  </step>
+
+<step n="4" goal="Generate sprint status file">
+<action>Create or update {status_file} with:</action>
+
+**File Structure:**
+
+```yaml
+# generated: {date}
+# last_updated: {date}
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: {tracking_system}
+# story_location: {story_location}
+
+# STATUS DEFINITIONS:
+# ==================
+# Epic Status:
+#   - backlog: Epic not yet started
+#   - in-progress: Epic actively being worked on
+#   - done: All stories in epic completed
+#
+# Epic Status Transitions:
+#   - backlog → in-progress: Automatically when first story is created (via create-story)
+#   - in-progress → done: Manually when all stories reach 'done' status
+#
+# Story Status:
+#   - backlog: Story only exists in epic file
+#   - ready-for-dev: Story file created in stories folder
+#   - in-progress: Developer actively working on implementation
+#   - review: Ready for code review (via Dev's code-review workflow)
+#   - done: Story completed
+#
+# Retrospective Status:
+#   - optional: Can be completed but not required
+#   - done: Retrospective has been completed
+#
+# WORKFLOW NOTES:
+# ===============
+# - Epic transitions to 'in-progress' automatically when first story is created
+# - Stories can be worked in parallel if team capacity allows
+# - Developer typically creates next story after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)
+
+generated: { date }
+last_updated: { date }
+project: { project_name }
+project_key: { project_key }
+tracking_system: { tracking_system }
+story_location: { story_location }
+
+development_status:
+  # All epics, stories, and retrospectives in order
+```
+
+<action>Write the complete sprint status YAML to {status_file}</action>
+<action>CRITICAL: Metadata appears TWICE - once as comments (#) for documentation, once as YAML key:value fields for parsing</action>
+<action>Ensure all items are ordered: epic, its stories, its retrospective, next epic...</action>
+</step>
+
+<step n="5" goal="Validate and report">
+<action>Perform validation checks:</action>
+
+- [ ] Every epic in epic files appears in {status_file}
+- [ ] Every story in epic files appears in {status_file}
+- [ ] Every epic has a corresponding retrospective entry
+- [ ] No items in {status_file} that don't exist in epic files
+- [ ] All status values are legal (match state machine definitions)
+- [ ] File is valid YAML syntax
+
+<action>Count totals:</action>
+
+- Total epics: {{epic_count}}
+- Total stories: {{story_count}}
+- Epics in-progress: {{in_progress_count}}
+- Stories done: {{done_count}}
+
+<action>Display completion summary to {user_name} in {communication_language}:</action>
+
+**Sprint Status Generated Successfully**
+
+- **File Location:** {status_file}
+- **Total Epics:** {{epic_count}}
+- **Total Stories:** {{story_count}}
+- **Epics In Progress:** {{in_progress_count}}
+- **Stories Completed:** {{done_count}}
+
+**Next Steps:**
+
+1. Review the generated {status_file}
+2. Use this file to track development progress
+3. Agents will update statuses as they work
+4. Re-run this workflow to refresh auto-detected statuses
+
+</step>
+
+</workflow>
+
+## Additional Documentation
+
+### Status State Machine
+
+**Epic Status Flow:**
+
+```
+backlog → in-progress → done
+```
+
+- **backlog**: Epic not yet started
+- **in-progress**: Epic actively being worked on (stories being created/implemented)
+- **done**: All stories in epic completed
+
+**Story Status Flow:**
+
+```
+backlog → ready-for-dev → in-progress → review → done
+```
+
+- **backlog**: Story only exists in epic file
+- **ready-for-dev**: Story file created (e.g., `stories/1-3-plant-naming.md`)
+- **in-progress**: Developer actively working
+- **review**: Ready for code review (via Dev's code-review workflow)
+- **done**: Completed
+
+**Retrospective Status:**
+
+```
+optional ↔ done
+```
+
+- **optional**: Ready to be conducted but not required
+- **done**: Finished
+
+### Guidelines
+
+1. **Epic Activation**: Mark epic as `in-progress` when starting work on its first story
+2. **Sequential Default**: Stories are typically worked in order, but parallel work is supported
+3. **Parallel Work Supported**: Multiple stories can be `in-progress` if team capacity allows
+4. **Review Before Done**: Stories should pass through `review` before `done`
+5. **Learning Transfer**: Developer typically creates next story after previous one is `done` to incorporate learnings
diff --git a/.claude/skills/bmad-sprint-status/SKILL.md b/.claude/skills/bmad-sprint-status/SKILL.md
new file mode 100644
index 0000000..3a15968
--- /dev/null
+++ b/.claude/skills/bmad-sprint-status/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-sprint-status
+description: 'Summarize sprint status and surface risks. Use when the user says "check sprint status" or "show sprint status"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-sprint-status/workflow.md b/.claude/skills/bmad-sprint-status/workflow.md
new file mode 100644
index 0000000..7b72c71
--- /dev/null
+++ b/.claude/skills/bmad-sprint-status/workflow.md
@@ -0,0 +1,261 @@
+# Sprint Status Workflow
+
+**Goal:** Summarize sprint status, surface risks, and recommend the next workflow action.
+
+**Your Role:** You are a Developer providing clear, actionable sprint visibility. No time estimates — focus on status, risks, and next steps.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- `project_name`, `user_name`
+- `communication_language`, `document_output_language`
+- `implementation_artifacts`
+- `date` as system-generated current datetime
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+### Paths
+
+- `sprint_status_file` = `{implementation_artifacts}/sprint-status.yaml`
+
+### Input Files
+
+| Input | Path | Load Strategy |
+|-------|------|---------------|
+| Sprint status | `{sprint_status_file}` | FULL_LOAD |
+
+### Context
+
+- `project_context` = `**/project-context.md` (load if exists)
+
+---
+
+## EXECUTION
+
+<workflow>
+
+<step n="0" goal="Determine execution mode">
+  <action>Set mode = {{mode}} if provided by caller; otherwise mode = "interactive"</action>
+
+  <check if="mode == data">
+    <action>Jump to Step 20</action>
+  </check>
+
+  <check if="mode == validate">
+    <action>Jump to Step 30</action>
+  </check>
+
+  <check if="mode == interactive">
+    <action>Continue to Step 1</action>
+  </check>
+</step>
+
+<step n="1" goal="Locate sprint status file">
+  <action>Load {project_context} for project-wide patterns and conventions (if exists)</action>
+  <action>Try {sprint_status_file}</action>
+  <check if="file not found">
+    <output>❌ sprint-status.yaml not found.
+Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-status.</output>
+    <action>Exit workflow</action>
+  </check>
+  <action>Continue to Step 2</action>
+</step>
+
+<step n="2" goal="Read and parse sprint-status.yaml">
+  <action>Read the FULL file: {sprint_status_file}</action>
+  <action>Parse fields: generated, last_updated, project, project_key, tracking_system, story_location</action>
+  <action>Parse development_status map. Classify keys:</action>
+  - Epics: keys starting with "epic-" (and not ending with "-retrospective")
+  - Retrospectives: keys ending with "-retrospective"
+  - Stories: everything else (e.g., 1-2-login-form)
+  <action>Map legacy story status "drafted" → "ready-for-dev"</action>
+  <action>Count story statuses: backlog, ready-for-dev, in-progress, review, done</action>
+  <action>Map legacy epic status "contexted" → "in-progress"</action>
+  <action>Count epic statuses: backlog, in-progress, done</action>
+  <action>Count retrospective statuses: optional, done</action>
+
+<action>Validate all statuses against known values:</action>
+
+- Valid story statuses: backlog, ready-for-dev, in-progress, review, done, drafted (legacy)
+- Valid epic statuses: backlog, in-progress, done, contexted (legacy)
+- Valid retrospective statuses: optional, done
+
+  <check if="any status is unrecognized">
+    <output>
+⚠️ **Unknown status detected:**
+{{#each invalid_entries}}
+
+- `{{key}}`: "{{status}}" (not recognized)
+  {{/each}}
+
+**Valid statuses:**
+
+- Stories: backlog, ready-for-dev, in-progress, review, done
+- Epics: backlog, in-progress, done
+- Retrospectives: optional, done
+  </output>
+  <ask>How should these be corrected?
+  {{#each invalid_entries}}
+  {{@index}}. {{key}}: "{{status}}" → [select valid status]
+  {{/each}}
+
+Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue without fixing:</ask>
+<check if="user provided corrections">
+<action>Update sprint-status.yaml with corrected values</action>
+<action>Re-parse the file with corrected statuses</action>
+</check>
+</check>
+
+<action>Detect risks:</action>
+
+- IF any story has status "review": suggest `/bmad:bmm:workflows:code-review`
+- IF any story has status "in-progress" AND no stories have status "ready-for-dev": recommend staying focused on active story
+- IF all epics have status "backlog" AND no stories have status "ready-for-dev": prompt `/bmad:bmm:workflows:create-story`
+- IF `last_updated` timestamp is more than 7 days old (or `last_updated` is missing, fall back to `generated`): warn "sprint-status.yaml may be stale"
+- IF any story key doesn't match an epic pattern (e.g., story "5-1-..." but no "epic-5"): warn "orphaned story detected"
+- IF any epic has status in-progress but has no associated stories: warn "in-progress epic has no stories"
+  </step>
+
+<step n="3" goal="Select next action recommendation">
+  <action>Pick the next recommended workflow using priority:</action>
+  <note>When selecting "first" story: sort by epic number, then story number (e.g., 1-1 before 1-2 before 2-1)</note>
+  1. If any story status == in-progress → recommend `dev-story` for the first in-progress story
+  2. Else if any story status == review → recommend `code-review` for the first review story
+  3. Else if any story status == ready-for-dev → recommend `dev-story`
+  4. Else if any story status == backlog → recommend `create-story`
+  5. Else if any retrospective status == optional → recommend `retrospective`
+  6. Else → All implementation items done; congratulate the user - you both did amazing work together!
+  <action>Store selected recommendation as: next_story_id, next_workflow_id, next_agent (DEV)</action>
+</step>
+
+<step n="4" goal="Display summary">
+  <output>
+## 📊 Sprint Status
+
+- Project: {{project}} ({{project_key}})
+- Tracking: {{tracking_system}}
+- Status file: {sprint_status_file}
+
+**Stories:** backlog {{count_backlog}}, ready-for-dev {{count_ready}}, in-progress {{count_in_progress}}, review {{count_review}}, done {{count_done}}
+
+**Epics:** backlog {{epic_backlog}}, in-progress {{epic_in_progress}}, done {{epic_done}}
+
+**Next Recommendation:** /bmad:bmm:workflows:{{next_workflow_id}} ({{next_story_id}})
+
+{{#if risks}}
+**Risks:**
+{{#each risks}}
+
+- {{this}}
+  {{/each}}
+  {{/if}}
+
+  </output>
+  </step>
+
+<step n="5" goal="Offer actions">
+  <ask>Pick an option:
+1) Run recommended workflow now
+2) Show all stories grouped by status
+3) Show raw sprint-status.yaml
+4) Exit
+Choice:</ask>
+
+  <check if="choice == 1">
+    <output>Run `/bmad:bmm:workflows:{{next_workflow_id}}`.
+If the command targets a story, set `story_key={{next_story_id}}` when prompted.</output>
+  </check>
+
+  <check if="choice == 2">
+    <output>
+### Stories by Status
+- In Progress: {{stories_in_progress}}
+- Review: {{stories_in_review}}
+- Ready for Dev: {{stories_ready_for_dev}}
+- Backlog: {{stories_backlog}}
+- Done: {{stories_done}}
+    </output>
+  </check>
+
+  <check if="choice == 3">
+    <action>Display the full contents of {sprint_status_file}</action>
+  </check>
+
+  <check if="choice == 4">
+    <action>Exit workflow</action>
+  </check>
+</step>
+
+<!-- ========================= -->
+<!-- Data mode for other flows -->
+<!-- ========================= -->
+
+<step n="20" goal="Data mode output">
+  <action>Load and parse {sprint_status_file} same as Step 2</action>
+  <action>Compute recommendation same as Step 3</action>
+  <template-output>next_workflow_id = {{next_workflow_id}}</template-output>
+  <template-output>next_story_id = {{next_story_id}}</template-output>
+  <template-output>count_backlog = {{count_backlog}}</template-output>
+  <template-output>count_ready = {{count_ready}}</template-output>
+  <template-output>count_in_progress = {{count_in_progress}}</template-output>
+  <template-output>count_review = {{count_review}}</template-output>
+  <template-output>count_done = {{count_done}}</template-output>
+  <template-output>epic_backlog = {{epic_backlog}}</template-output>
+  <template-output>epic_in_progress = {{epic_in_progress}}</template-output>
+  <template-output>epic_done = {{epic_done}}</template-output>
+  <template-output>risks = {{risks}}</template-output>
+  <action>Return to caller</action>
+</step>
+
+<!-- ========================= -->
+<!-- Validate mode -->
+<!-- ========================= -->
+
+<step n="30" goal="Validate sprint-status file">
+  <action>Check that {sprint_status_file} exists</action>
+  <check if="missing">
+    <template-output>is_valid = false</template-output>
+    <template-output>error = "sprint-status.yaml missing"</template-output>
+    <template-output>suggestion = "Run sprint-planning to create it"</template-output>
+    <action>Return</action>
+  </check>
+
+<action>Read and parse {sprint_status_file}</action>
+
+<action>Validate required metadata fields exist: generated, project, project_key, tracking_system, story_location (last_updated is optional for backward compatibility)</action>
+<check if="any required field missing">
+<template-output>is_valid = false</template-output>
+<template-output>error = "Missing required field(s): {{missing_fields}}"</template-output>
+<template-output>suggestion = "Re-run sprint-planning or add missing fields manually"</template-output>
+<action>Return</action>
+</check>
+
+<action>Verify development_status section exists with at least one entry</action>
+<check if="development_status missing or empty">
+<template-output>is_valid = false</template-output>
+<template-output>error = "development_status missing or empty"</template-output>
+<template-output>suggestion = "Re-run sprint-planning or repair the file manually"</template-output>
+<action>Return</action>
+</check>
+
+<action>Validate all status values against known valid statuses:</action>
+
+- Stories: backlog, ready-for-dev, in-progress, review, done (legacy: drafted)
+- Epics: backlog, in-progress, done (legacy: contexted)
+- Retrospectives: optional, done
+  <check if="any invalid status found">
+  <template-output>is_valid = false</template-output>
+  <template-output>error = "Invalid status values: {{invalid_entries}}"</template-output>
+  <template-output>suggestion = "Fix invalid statuses in sprint-status.yaml"</template-output>
+  <action>Return</action>
+  </check>
+
+<template-output>is_valid = true</template-output>
+<template-output>message = "sprint-status.yaml valid: metadata complete, all statuses recognized"</template-output>
+</step>
+
+</workflow>
diff --git a/.claude/skills/bmad-technical-research/SKILL.md b/.claude/skills/bmad-technical-research/SKILL.md
new file mode 100644
index 0000000..8524fd6
--- /dev/null
+++ b/.claude/skills/bmad-technical-research/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-technical-research
+description: 'Conduct technical research on technologies and architecture. Use when the user says they would like to do or produce a technical research report'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-technical-research/research.template.md b/.claude/skills/bmad-technical-research/research.template.md
new file mode 100644
index 0000000..1d99524
--- /dev/null
+++ b/.claude/skills/bmad-technical-research/research.template.md
@@ -0,0 +1,29 @@
+---
+stepsCompleted: []
+inputDocuments: []
+workflowType: 'research'
+lastStep: 1
+research_type: '{{research_type}}'
+research_topic: '{{research_topic}}'
+research_goals: '{{research_goals}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+web_research_enabled: true
+source_verification: true
+---
+
+# Research Report: {{research_type}}
+
+**Date:** {{date}}
+**Author:** {{user_name}}
+**Research Type:** {{research_type}}
+
+---
+
+## Research Overview
+
+[Research overview and methodology will be appended here]
+
+---
+
+<!-- Content will be appended sequentially through research workflow steps -->
diff --git a/.claude/skills/bmad-technical-research/technical-steps/step-01-init.md b/.claude/skills/bmad-technical-research/technical-steps/step-01-init.md
new file mode 100644
index 0000000..b286822
--- /dev/null
+++ b/.claude/skills/bmad-technical-research/technical-steps/step-01-init.md
@@ -0,0 +1,137 @@
+# Technical Research Step 1: Technical Research Scope Confirmation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user confirmation
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ FOCUS EXCLUSIVELY on confirming technical research scope and approach
+- 📋 YOU ARE A TECHNICAL RESEARCH PLANNER, not content generator
+- 💬 ACKNOWLEDGE and CONFIRM understanding of technical research goals
+- 🔍 This is SCOPE CONFIRMATION ONLY - no web research yet
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present [C] continue option after scope confirmation
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Research type = "technical" is already set
+- **Research topic = "{{research_topic}}"** - discovered from initial discussion
+- **Research goals = "{{research_goals}}"** - captured from initial discussion
+- Focus on technical architecture and implementation research
+- Web search is required to verify and supplement your knowledge with current facts
+
+## YOUR TASK:
+
+Confirm technical research scope and approach for **{{research_topic}}** with the user's goals in mind.
+
+## TECHNICAL SCOPE CONFIRMATION:
+
+### 1. Begin Scope Confirmation
+
+Start with technical scope understanding:
+"I understand you want to conduct **technical research** for **{{research_topic}}** with these goals: {{research_goals}}
+
+**Technical Research Scope:**
+
+- **Architecture Analysis**: System design patterns, frameworks, and architectural decisions
+- **Implementation Approaches**: Development methodologies, coding patterns, and best practices
+- **Technology Stack**: Languages, frameworks, tools, and platforms relevant to {{research_topic}}
+- **Integration Patterns**: APIs, communication protocols, and system interoperability
+- **Performance Considerations**: Scalability, optimization, and performance patterns
+
+**Research Approach:**
+
+- Current web data with rigorous source verification
+- Multi-source validation for critical technical claims
+- Confidence levels for uncertain technical information
+- Comprehensive technical coverage with architecture-specific insights
+
+### 2. Scope Confirmation
+
+Present clear scope confirmation:
+"**Technical Research Scope Confirmation:**
+
+For **{{research_topic}}**, I will research:
+
+✅ **Architecture Analysis** - design patterns, frameworks, system architecture
+✅ **Implementation Approaches** - development methodologies, coding patterns
+✅ **Technology Stack** - languages, frameworks, tools, platforms
+✅ **Integration Patterns** - APIs, protocols, interoperability
+✅ **Performance Considerations** - scalability, optimization, patterns
+
+**All claims verified against current public sources.**
+
+**Does this technical research scope and approach align with your goals?**
+[C] Continue - Begin technical research with this scope
+
+### 3. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- Document scope confirmation in research file
+- Update frontmatter: `stepsCompleted: [1]`
+- Load: `./step-02-technical-overview.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append scope confirmation:
+
+```markdown
+## Technical Research Scope Confirmation
+
+**Research Topic:** {{research_topic}}
+**Research Goals:** {{research_goals}}
+
+**Technical Research Scope:**
+
+- Architecture Analysis - design patterns, frameworks, system architecture
+- Implementation Approaches - development methodologies, coding patterns
+- Technology Stack - languages, frameworks, tools, platforms
+- Integration Patterns - APIs, protocols, interoperability
+- Performance Considerations - scalability, optimization, patterns
+
+**Research Methodology:**
+
+- Current web data with rigorous source verification
+- Multi-source validation for critical technical claims
+- Confidence level framework for uncertain information
+- Comprehensive technical coverage with architecture-specific insights
+
+**Scope Confirmed:** {{date}}
+```
+
+## SUCCESS METRICS:
+
+✅ Technical research scope clearly confirmed with user
+✅ All technical analysis areas identified and explained
+✅ Research methodology emphasized
+✅ [C] continue option presented and handled correctly
+✅ Scope confirmation documented when user proceeds
+✅ Proper routing to next technical research step
+
+## FAILURE MODES:
+
+❌ Not clearly confirming technical research scope with user
+❌ Missing critical technical analysis areas
+❌ Not explaining that web search is required for current facts
+❌ Not presenting [C] continue option
+❌ Proceeding without user scope confirmation
+❌ Not routing to next technical research step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-02-technical-overview.md` to begin technology stack analysis.
+
+Remember: This is SCOPE CONFIRMATION ONLY - no actual technical research yet, just confirming the research approach and scope!
diff --git a/.claude/skills/bmad-technical-research/technical-steps/step-02-technical-overview.md b/.claude/skills/bmad-technical-research/technical-steps/step-02-technical-overview.md
new file mode 100644
index 0000000..78151eb
--- /dev/null
+++ b/.claude/skills/bmad-technical-research/technical-steps/step-02-technical-overview.md
@@ -0,0 +1,239 @@
+# Technical Research Step 2: Technology Stack Analysis
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A TECHNOLOGY STACK ANALYST, not content generator
+- 💬 FOCUS on languages, frameworks, tools, and platforms
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after technology stack content generation
+- 📝 WRITE TECHNOLOGY STACK ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from step-01 are available
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+- Focus on languages, frameworks, tools, and platforms
+- Web search capabilities with source verification are enabled
+
+## YOUR TASK:
+
+Conduct technology stack analysis focusing on languages, frameworks, tools, and platforms. Search the web to verify and supplement current facts.
+
+## TECHNOLOGY STACK ANALYSIS SEQUENCE:
+
+### 1. Begin Technology Stack Analysis
+
+**UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different technology stack areas simultaneously and thoroughly.
+
+Start with technology stack research approach:
+"Now I'll conduct **technology stack analysis** for **{{research_topic}}** to understand the technology landscape.
+
+**Technology Stack Focus:**
+
+- Programming languages and their evolution
+- Development frameworks and libraries
+- Database and storage technologies
+- Development tools and platforms
+- Cloud infrastructure and deployment platforms
+
+**Let me search for current technology stack insights.**"
+
+### 2. Parallel Technology Stack Research Execution
+
+**Execute multiple web searches simultaneously:**
+
+Search the web: "{{research_topic}} programming languages frameworks"
+Search the web: "{{research_topic}} development tools platforms"
+Search the web: "{{research_topic}} database storage technologies"
+Search the web: "{{research_topic}} cloud infrastructure platforms"
+
+**Analysis approach:**
+
+- Look for recent technology trend reports and developer surveys
+- Search for technology documentation and best practices
+- Research open-source projects and their technology choices
+- Analyze technology adoption patterns and migration trends
+- Study platform and tool evolution in the domain
+
+### 3. Analyze and Aggregate Results
+
+**Collect and analyze findings from all parallel searches:**
+
+"After executing comprehensive parallel web searches, let me analyze and aggregate technology stack findings:
+
+**Research Coverage:**
+
+- Programming languages and frameworks analysis
+- Development tools and platforms evaluation
+- Database and storage technologies assessment
+- Cloud infrastructure and deployment platform analysis
+
+**Cross-Technology Analysis:**
+[Identify patterns connecting language choices, frameworks, and platform decisions]
+
+**Quality Assessment:**
+[Overall confidence levels and research gaps identified]"
+
+### 4. Generate Technology Stack Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare technology stack analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Technology Stack Analysis
+
+### Programming Languages
+
+[Programming languages analysis with source citations]
+_Popular Languages: [Most widely used languages for {{research_topic}}]_
+_Emerging Languages: [Growing languages gaining adoption]_
+_Language Evolution: [How language preferences are changing]_
+_Performance Characteristics: [Language performance and suitability]_
+_Source: [URL]_
+
+### Development Frameworks and Libraries
+
+[Frameworks analysis with source citations]
+_Major Frameworks: [Dominant frameworks and their use cases]_
+_Micro-frameworks: [Lightweight options and specialized libraries]_
+_Evolution Trends: [How frameworks are evolving and changing]_
+_Ecosystem Maturity: [Library availability and community support]_
+_Source: [URL]_
+
+### Database and Storage Technologies
+
+[Database analysis with source citations]
+_Relational Databases: [Traditional SQL databases and their evolution]_
+_NoSQL Databases: [Document, key-value, graph, and other NoSQL options]_
+_In-Memory Databases: [Redis, Memcached, and performance-focused solutions]_
+_Data Warehousing: [Analytics and big data storage solutions]_
+_Source: [URL]_
+
+### Development Tools and Platforms
+
+[Tools and platforms analysis with source citations]
+_IDE and Editors: [Development environments and their evolution]_
+_Version Control: [Git and related development tools]_
+_Build Systems: [Compilation, packaging, and automation tools]_
+_Testing Frameworks: [Unit testing, integration testing, and QA tools]_
+_Source: [URL]_
+
+### Cloud Infrastructure and Deployment
+
+[Cloud platforms analysis with source citations]
+_Major Cloud Providers: [AWS, Azure, GCP and their services]_
+_Container Technologies: [Docker, Kubernetes, and orchestration]_
+_Serverless Platforms: [FaaS and event-driven computing]_
+_CDN and Edge Computing: [Content delivery and distributed computing]_
+_Source: [URL]_
+
+### Technology Adoption Trends
+
+[Adoption trends analysis with source citations]
+_Migration Patterns: [How technology choices are evolving]_
+_Emerging Technologies: [New technologies gaining traction]_
+_Legacy Technology: [Older technologies being phased out]_
+_Community Trends: [Developer preferences and open-source adoption]_
+_Source: [URL]_
+```
+
+### 5. Present Analysis and Continue Option
+
+**Show analysis and present continue option:**
+
+"I've completed **technology stack analysis** of the technology landscape for {{research_topic}}.
+
+**Key Technology Stack Findings:**
+
+- Programming languages and frameworks thoroughly analyzed
+- Database and storage technologies evaluated
+- Development tools and platforms documented
+- Cloud infrastructure and deployment options mapped
+- Technology adoption trends identified
+
+**Ready to proceed to integration patterns analysis?**
+[C] Continue - Save this to document and proceed to integration patterns
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2]`
+- Load: `./step-03-integration-patterns.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 4. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ Programming languages and frameworks thoroughly analyzed
+✅ Database and storage technologies evaluated
+✅ Development tools and platforms documented
+✅ Cloud infrastructure and deployment options mapped
+✅ Technology adoption trends identified
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (integration patterns)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical programming languages or frameworks
+❌ Incomplete database and storage technology analysis
+❌ Not identifying development tools and platforms
+❌ Not writing content immediately to document
+❌ Not presenting [C] continue option after content generation
+❌ Not routing to integration patterns step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## TECHNOLOGY STACK RESEARCH PROTOCOLS:
+
+- Research technology trend reports and developer surveys
+- Use technology documentation and best practices guides
+- Analyze open-source projects and their technology choices
+- Study technology adoption patterns and migration trends
+- Focus on current technology data
+- Present conflicting information when sources disagree
+- Apply confidence levels appropriately
+
+## TECHNOLOGY STACK ANALYSIS STANDARDS:
+
+- Always cite URLs for web search results
+- Use authoritative technology research sources
+- Note data currency and potential limitations
+- Present multiple perspectives when sources conflict
+- Apply confidence levels to uncertain data
+- Focus on actionable technology insights
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-03-integration-patterns.md` to analyze APIs, communication protocols, and system interoperability for {{research_topic}}.
+
+Remember: Always write research content to document immediately and emphasize current technology data with rigorous source verification!
diff --git a/.claude/skills/bmad-technical-research/technical-steps/step-03-integration-patterns.md b/.claude/skills/bmad-technical-research/technical-steps/step-03-integration-patterns.md
new file mode 100644
index 0000000..68e2b70
--- /dev/null
+++ b/.claude/skills/bmad-technical-research/technical-steps/step-03-integration-patterns.md
@@ -0,0 +1,248 @@
+# Technical Research Step 3: Integration Patterns
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE AN INTEGRATION ANALYST, not content generator
+- 💬 FOCUS on APIs, protocols, and system interoperability
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after integration patterns content generation
+- 📝 WRITE INTEGRATION PATTERNS ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+- Focus on APIs, protocols, and system interoperability
+- Web search capabilities with source verification are enabled
+
+## YOUR TASK:
+
+Conduct integration patterns analysis focusing on APIs, communication protocols, and system interoperability. Search the web to verify and supplement current facts.
+
+## INTEGRATION PATTERNS ANALYSIS SEQUENCE:
+
+### 1. Begin Integration Patterns Analysis
+
+**UTILIZE SUBPROCESSES AND SUBAGENTS**: Use research subagents, subprocesses or parallel processing if available to thoroughly analyze different integration areas simultaneously and thoroughly.
+
+Start with integration patterns research approach:
+"Now I'll conduct **integration patterns analysis** for **{{research_topic}}** to understand system integration approaches.
+
+**Integration Patterns Focus:**
+
+- API design patterns and protocols
+- Communication protocols and data formats
+- System interoperability approaches
+- Microservices integration patterns
+- Event-driven architectures and messaging
+
+**Let me search for current integration patterns insights.**"
+
+### 2. Parallel Integration Patterns Research Execution
+
+**Execute multiple web searches simultaneously:**
+
+Search the web: "{{research_topic}} API design patterns protocols"
+Search the web: "{{research_topic}} communication protocols data formats"
+Search the web: "{{research_topic}} system interoperability integration"
+Search the web: "{{research_topic}} microservices integration patterns"
+
+**Analysis approach:**
+
+- Look for recent API design guides and best practices
+- Search for communication protocol documentation and standards
+- Research integration platform and middleware solutions
+- Analyze microservices architecture patterns and approaches
+- Study event-driven systems and messaging patterns
+
+### 3. Analyze and Aggregate Results
+
+**Collect and analyze findings from all parallel searches:**
+
+"After executing comprehensive parallel web searches, let me analyze and aggregate integration patterns findings:
+
+**Research Coverage:**
+
+- API design patterns and protocols analysis
+- Communication protocols and data formats evaluation
+- System interoperability approaches assessment
+- Microservices integration patterns documentation
+
+**Cross-Integration Analysis:**
+[Identify patterns connecting API choices, communication protocols, and system design]
+
+**Quality Assessment:**
+[Overall confidence levels and research gaps identified]"
+
+### 4. Generate Integration Patterns Content
+
+**WRITE IMMEDIATELY TO DOCUMENT**
+
+Prepare integration patterns analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Integration Patterns Analysis
+
+### API Design Patterns
+
+[API design patterns analysis with source citations]
+_RESTful APIs: [REST principles and best practices for {{research_topic}}]_
+_GraphQL APIs: [GraphQL adoption and implementation patterns]_
+_RPC and gRPC: [High-performance API communication patterns]_
+_Webhook Patterns: [Event-driven API integration approaches]_
+_Source: [URL]_
+
+### Communication Protocols
+
+[Communication protocols analysis with source citations]
+_HTTP/HTTPS Protocols: [Web-based communication patterns and evolution]_
+_WebSocket Protocols: [Real-time communication and persistent connections]_
+_Message Queue Protocols: [AMQP, MQTT, and messaging patterns]_
+_grpc and Protocol Buffers: [High-performance binary communication protocols]_
+_Source: [URL]_
+
+### Data Formats and Standards
+
+[Data formats analysis with source citations]
+_JSON and XML: [Structured data exchange formats and their evolution]_
+_Protobuf and MessagePack: [Efficient binary serialization formats]_
+_CSV and Flat Files: [Legacy data integration and bulk transfer patterns]_
+_Custom Data Formats: [Domain-specific data exchange standards]_
+_Source: [URL]_
+
+### System Interoperability Approaches
+
+[Interoperability analysis with source citations]
+_Point-to-Point Integration: [Direct system-to-system communication patterns]_
+_API Gateway Patterns: [Centralized API management and routing]_
+_Service Mesh: [Service-to-service communication and observability]_
+_Enterprise Service Bus: [Traditional enterprise integration patterns]_
+_Source: [URL]_
+
+### Microservices Integration Patterns
+
+[Microservices integration analysis with source citations]
+_API Gateway Pattern: [External API management and routing]_
+_Service Discovery: [Dynamic service registration and discovery]_
+_Circuit Breaker Pattern: [Fault tolerance and resilience patterns]_
+_Saga Pattern: [Distributed transaction management]_
+_Source: [URL]_
+
+### Event-Driven Integration
+
+[Event-driven analysis with source citations]
+_Publish-Subscribe Patterns: [Event broadcasting and subscription models]_
+_Event Sourcing: [Event-based state management and persistence]_
+_Message Broker Patterns: [RabbitMQ, Kafka, and message routing]_
+_CQRS Patterns: [Command Query Responsibility Segregation]_
+_Source: [URL]_
+
+### Integration Security Patterns
+
+[Security patterns analysis with source citations]
+_OAuth 2.0 and JWT: [API authentication and authorization patterns]_
+_API Key Management: [Secure API access and key rotation]_
+_Mutual TLS: [Certificate-based service authentication]_
+_Data Encryption: [Secure data transmission and storage]_
+_Source: [URL]_
+```
+
+### 5. Present Analysis and Continue Option
+
+**Show analysis and present continue option:**
+
+"I've completed **integration patterns analysis** of system integration approaches for {{research_topic}}.
+
+**Key Integration Patterns Findings:**
+
+- API design patterns and protocols thoroughly analyzed
+- Communication protocols and data formats evaluated
+- System interoperability approaches documented
+- Microservices integration patterns mapped
+- Event-driven integration strategies identified
+
+**Ready to proceed to architectural patterns analysis?**
+[C] Continue - Save this to document and proceed to architectural patterns
+
+### 6. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- **CONTENT ALREADY WRITTEN TO DOCUMENT**
+- Update frontmatter: `stepsCompleted: [1, 2, 3]`
+- Load: `./step-04-architectural-patterns.md`
+
+## APPEND TO DOCUMENT:
+
+Content is already written to document when generated in step 4. No additional append needed.
+
+## SUCCESS METRICS:
+
+✅ API design patterns and protocols thoroughly analyzed
+✅ Communication protocols and data formats evaluated
+✅ System interoperability approaches documented
+✅ Microservices integration patterns mapped
+✅ Event-driven integration strategies identified
+✅ Content written immediately to document
+✅ [C] continue option presented and handled correctly
+✅ Proper routing to next step (architectural patterns)
+✅ Research goals alignment maintained
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical API design patterns or protocols
+❌ Incomplete communication protocols analysis
+❌ Not identifying system interoperability approaches
+❌ Not writing content immediately to document
+❌ Not presenting [C] continue option after content generation
+❌ Not routing to architectural patterns step
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## INTEGRATION PATTERNS RESEARCH PROTOCOLS:
+
+- Research API design guides and best practices documentation
+- Use communication protocol specifications and standards
+- Analyze integration platform and middleware solutions
+- Study microservices architecture patterns and case studies
+- Focus on current integration data
+- Present conflicting information when sources disagree
+- Apply confidence levels appropriately
+
+## INTEGRATION PATTERNS ANALYSIS STANDARDS:
+
+- Always cite URLs for web search results
+- Use authoritative integration research sources
+- Note data currency and potential limitations
+- Present multiple perspectives when sources conflict
+- Apply confidence levels to uncertain data
+- Focus on actionable integration insights
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-04-architectural-patterns.md` to analyze architectural patterns, design decisions, and system structures for {{research_topic}}.
+
+Remember: Always write research content to document immediately and emphasize current integration data with rigorous source verification!
diff --git a/.claude/skills/bmad-technical-research/technical-steps/step-04-architectural-patterns.md b/.claude/skills/bmad-technical-research/technical-steps/step-04-architectural-patterns.md
new file mode 100644
index 0000000..3d0e66a
--- /dev/null
+++ b/.claude/skills/bmad-technical-research/technical-steps/step-04-architectural-patterns.md
@@ -0,0 +1,202 @@
+# Technical Research Step 4: Architectural Patterns
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A SYSTEMS ARCHITECT, not content generator
+- 💬 FOCUS on architectural patterns and design decisions
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📝 WRITE CONTENT IMMEDIATELY TO DOCUMENT
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] continue option after architectural patterns content generation
+- 📝 WRITE ARCHITECTURAL PATTERNS ANALYSIS TO DOCUMENT IMMEDIATELY
+- 💾 ONLY proceed when user chooses C (Continue)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4]` before loading next step
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- **Research topic = "{{research_topic}}"** - established from initial discussion
+- **Research goals = "{{research_goals}}"** - established from initial discussion
+- Focus on architectural patterns and design decisions
+- Web search capabilities with source verification are enabled
+
+## YOUR TASK:
+
+Conduct comprehensive architectural patterns analysis with emphasis on design decisions and implementation approaches for {{research_topic}}.
+
+## ARCHITECTURAL PATTERNS SEQUENCE:
+
+### 1. Begin Architectural Patterns Analysis
+
+Start with architectural research approach:
+"Now I'll focus on **architectural patterns and design decisions** for effective architecture approaches for [technology/domain].
+
+**Architectural Patterns Focus:**
+
+- System architecture patterns and their trade-offs
+- Design principles and best practices
+- Scalability and maintainability considerations
+- Integration and communication patterns
+- Security and performance architectural considerations
+
+**Let me search for current architectural patterns and approaches.**"
+
+### 2. Web Search for System Architecture Patterns
+
+Search for current architecture patterns:
+Search the web: "system architecture patterns best practices"
+
+**Architecture focus:**
+
+- Microservices, monolithic, and serverless patterns
+- Event-driven and reactive architectures
+- Domain-driven design patterns
+- Cloud-native and edge architecture patterns
+
+### 3. Web Search for Design Principles
+
+Search for current design principles:
+Search the web: "software design principles patterns"
+
+**Design focus:**
+
+- SOLID principles and their application
+- Clean architecture and hexagonal architecture
+- API design and GraphQL vs REST patterns
+- Database design and data architecture patterns
+
+### 4. Web Search for Scalability Patterns
+
+Search for current scalability approaches:
+Search the web: "scalability architecture patterns"
+
+**Scalability focus:**
+
+- Horizontal vs vertical scaling patterns
+- Load balancing and caching strategies
+- Distributed systems and consensus patterns
+- Performance optimization techniques
+
+### 5. Generate Architectural Patterns Content
+
+Prepare architectural analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Architectural Patterns and Design
+
+### System Architecture Patterns
+
+[System architecture patterns analysis with source citations]
+_Source: [URL]_
+
+### Design Principles and Best Practices
+
+[Design principles analysis with source citations]
+_Source: [URL]_
+
+### Scalability and Performance Patterns
+
+[Scalability patterns analysis with source citations]
+_Source: [URL]_
+
+### Integration and Communication Patterns
+
+[Integration patterns analysis with source citations]
+_Source: [URL]_
+
+### Security Architecture Patterns
+
+[Security patterns analysis with source citations]
+_Source: [URL]_
+
+### Data Architecture Patterns
+
+[Data architecture analysis with source citations]
+_Source: [URL]_
+
+### Deployment and Operations Architecture
+
+[Deployment architecture analysis with source citations]
+_Source: [URL]_
+```
+
+### 6. Present Analysis and Continue Option
+
+Show the generated architectural patterns and present continue option:
+"I've completed the **architectural patterns analysis** for effective architecture approaches.
+
+**Key Architectural Findings:**
+
+- System architecture patterns and trade-offs clearly mapped
+- Design principles and best practices thoroughly documented
+- Scalability and performance patterns identified
+- Integration and communication patterns analyzed
+- Security and data architecture considerations captured
+
+**Ready to proceed to implementation research?**
+[C] Continue - Save this to the document and move to implementation research
+
+### 7. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- Append the final content to the research document
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
+- Load: `./step-05-implementation-research.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the research document using the structure from step 5.
+
+## SUCCESS METRICS:
+
+✅ System architecture patterns identified with current citations
+✅ Design principles clearly documented and analyzed
+✅ Scalability and performance patterns thoroughly mapped
+✅ Integration and communication patterns captured
+✅ Security and data architecture considerations analyzed
+✅ [C] continue option presented and handled correctly
+✅ Content properly appended to document when C selected
+✅ Proper routing to implementation research step
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical system architecture patterns
+❌ Not analyzing design trade-offs and considerations
+❌ Incomplete scalability or performance patterns analysis
+❌ Not presenting [C] continue option after content generation
+❌ Appending content without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## ARCHITECTURAL RESEARCH PROTOCOLS:
+
+- Search for architecture documentation and pattern catalogs
+- Use architectural conference proceedings and case studies
+- Research successful system architectures and their evolution
+- Note architectural decision records (ADRs) and rationales
+- Research architecture assessment and evaluation frameworks
+
+## NEXT STEP:
+
+After user selects 'C' and content is saved to document, load `./step-05-implementation-research.md` to focus on implementation approaches and technology adoption.
+
+Remember: Always emphasize current architectural data and rigorous source verification!
diff --git a/.claude/skills/bmad-technical-research/technical-steps/step-05-implementation-research.md b/.claude/skills/bmad-technical-research/technical-steps/step-05-implementation-research.md
new file mode 100644
index 0000000..9945373
--- /dev/null
+++ b/.claude/skills/bmad-technical-research/technical-steps/step-05-implementation-research.md
@@ -0,0 +1,233 @@
+# Technical Research Step 5: Implementation Research
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE AN IMPLEMENTATION ENGINEER, not content generator
+- 💬 FOCUS on implementation approaches and technology adoption
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] complete option after implementation research content generation
+- 💾 ONLY save when user chooses C (Complete)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5]` before completing workflow
+- 🚫 FORBIDDEN to complete workflow until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- Focus on implementation approaches and technology adoption strategies
+- Web search capabilities with source verification are enabled
+- This step prepares for the final synthesis step
+
+## YOUR TASK:
+
+Conduct comprehensive implementation research with emphasis on practical implementation approaches and technology adoption.
+
+## IMPLEMENTATION RESEARCH SEQUENCE:
+
+### 1. Begin Implementation Research
+
+Start with implementation research approach:
+"Now I'll complete our technical research with **implementation approaches and technology adoption** analysis.
+
+**Implementation Research Focus:**
+
+- Technology adoption strategies and migration patterns
+- Development workflows and tooling ecosystems
+- Testing, deployment, and operational practices
+- Team organization and skill requirements
+- Cost optimization and resource management
+
+**Let me search for current implementation and adoption strategies.**"
+
+### 2. Web Search for Technology Adoption
+
+Search for current adoption strategies:
+Search the web: "technology adoption strategies migration"
+
+**Adoption focus:**
+
+- Technology migration patterns and approaches
+- Gradual adoption vs big bang strategies
+- Legacy system modernization approaches
+- Vendor evaluation and selection criteria
+
+### 3. Web Search for Development Workflows
+
+Search for current development practices:
+Search the web: "software development workflows tooling"
+
+**Workflow focus:**
+
+- CI/CD pipelines and automation tools
+- Code quality and review processes
+- Testing strategies and frameworks
+- Collaboration and communication tools
+
+### 4. Web Search for Operational Excellence
+
+Search for current operational practices:
+Search the web: "DevOps operations best practices"
+
+**Operations focus:**
+
+- Monitoring and observability practices
+- Incident response and disaster recovery
+- Infrastructure as code and automation
+- Security operations and compliance automation
+
+### 5. Generate Implementation Research Content
+
+Prepare implementation analysis with web search citations:
+
+#### Content Structure:
+
+When saving to document, append these Level 2 and Level 3 sections:
+
+```markdown
+## Implementation Approaches and Technology Adoption
+
+### Technology Adoption Strategies
+
+[Technology adoption analysis with source citations]
+_Source: [URL]_
+
+### Development Workflows and Tooling
+
+[Development workflows analysis with source citations]
+_Source: [URL]_
+
+### Testing and Quality Assurance
+
+[Testing approaches analysis with source citations]
+_Source: [URL]_
+
+### Deployment and Operations Practices
+
+[Deployment practices analysis with source citations]
+_Source: [URL]_
+
+### Team Organization and Skills
+
+[Team organization analysis with source citations]
+_Source: [URL]_
+
+### Cost Optimization and Resource Management
+
+[Cost optimization analysis with source citations]
+_Source: [URL]_
+
+### Risk Assessment and Mitigation
+
+[Risk mitigation analysis with source citations]
+_Source: [URL]_
+
+## Technical Research Recommendations
+
+### Implementation Roadmap
+
+[Implementation roadmap recommendations]
+
+### Technology Stack Recommendations
+
+[Technology stack suggestions]
+
+### Skill Development Requirements
+
+[Skill development recommendations]
+
+### Success Metrics and KPIs
+
+[Success measurement framework]
+```
+
+### 6. Present Analysis and Continue Option
+
+Show the generated implementation research and present continue option:
+"I've completed the **implementation research and technology adoption** analysis for {{research_topic}}.
+
+**Implementation Highlights:**
+
+- Technology adoption strategies and migration patterns documented
+- Development workflows and tooling ecosystems analyzed
+- Testing, deployment, and operational practices mapped
+- Team organization and skill requirements identified
+- Cost optimization and resource management strategies provided
+
+**Technical research phases completed:**
+
+- Step 1: Research scope confirmation
+- Step 2: Technology stack analysis
+- Step 3: Integration patterns analysis
+- Step 4: Architectural patterns analysis
+- Step 5: Implementation research (current step)
+
+**Ready to proceed to the final synthesis step?**
+[C] Continue - Save this to document and proceed to synthesis
+
+### 7. Handle Continue Selection
+
+#### If 'C' (Continue):
+
+- Append the final content to the research document
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
+- Load: `./step-06-research-synthesis.md`
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the content directly to the research document using the structure from step 5.
+
+## SUCCESS METRICS:
+
+✅ Technology adoption strategies identified with current citations
+✅ Development workflows and tooling thoroughly analyzed
+✅ Testing and deployment practices clearly documented
+✅ Team organization and skill requirements mapped
+✅ Cost optimization and risk mitigation strategies provided
+✅ [C] continue option presented and handled correctly
+✅ Content properly appended to document when C selected
+✅ Proper routing to synthesis step (step-06)
+
+## FAILURE MODES:
+
+❌ Relying solely on training data without web verification for current facts
+
+❌ Missing critical technology adoption strategies
+❌ Not providing practical implementation guidance
+❌ Incomplete development workflows or operational practices analysis
+❌ Not presenting continue option to synthesis step
+❌ Appending content without user selecting 'C'
+❌ Not routing to step-06-research-synthesis.md
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## IMPLEMENTATION RESEARCH PROTOCOLS:
+
+- Search for implementation case studies and success stories
+- Research technology migration patterns and lessons learned
+- Identify common implementation challenges and solutions
+- Research development tooling ecosystem evaluations
+- Analyze operational excellence frameworks and maturity models
+
+## TECHNICAL RESEARCH WORKFLOW COMPLETION:
+
+When 'C' is selected:
+
+- Implementation research step completed
+- Content appended to research document with source citations
+- Frontmatter updated with stepsCompleted: [1, 2, 3, 4, 5]
+- Ready to proceed to final synthesis step
+
+## NEXT STEP:
+
+After user selects 'C', load `./step-06-research-synthesis.md` to produce the comprehensive technical research document with narrative introduction, detailed TOC, and executive summary.
diff --git a/.claude/skills/bmad-technical-research/technical-steps/step-06-research-synthesis.md b/.claude/skills/bmad-technical-research/technical-steps/step-06-research-synthesis.md
new file mode 100644
index 0000000..96852cb
--- /dev/null
+++ b/.claude/skills/bmad-technical-research/technical-steps/step-06-research-synthesis.md
@@ -0,0 +1,487 @@
+# Technical Research Step 6: Technical Synthesis and Completion
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without web search verification
+
+- 📖 CRITICAL: ALWAYS read the complete step file before taking any action - partial understanding leads to incomplete decisions
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read and understood before proceeding
+- ✅ Search the web to verify and supplement your knowledge with current facts
+- 📋 YOU ARE A TECHNICAL RESEARCH STRATEGIST, not content generator
+- 💬 FOCUS on comprehensive technical synthesis and authoritative conclusions
+- 🔍 WEB SEARCH REQUIRED - verify current facts against live sources
+- 📄 PRODUCE COMPREHENSIVE DOCUMENT with narrative intro, TOC, and summary
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show web search analysis before presenting findings
+- ⚠️ Present [C] complete option after synthesis content generation
+- 💾 ONLY save when user chooses C (Complete)
+- 📖 Update frontmatter `stepsCompleted: [1, 2, 3, 4, 5, 6]` before completing workflow
+- 🚫 FORBIDDEN to complete workflow until C is selected
+- 📚 GENERATE COMPLETE DOCUMENT STRUCTURE with intro, TOC, and summary
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from previous steps are available
+- **Research topic = "{{research_topic}}"** - comprehensive technical analysis
+- **Research goals = "{{research_goals}}"** - achieved through exhaustive technical research
+- All technical research sections have been completed (overview, architecture, implementation)
+- Web search capabilities with source verification are enabled
+- This is the final synthesis step producing the complete technical research document
+
+## YOUR TASK:
+
+Produce a comprehensive, authoritative technical research document on **{{research_topic}}** with compelling narrative introduction, detailed TOC, and executive summary based on exhaustive technical research.
+
+## COMPREHENSIVE TECHNICAL DOCUMENT SYNTHESIS:
+
+### 1. Technical Document Structure Planning
+
+**Complete Technical Research Document Structure:**
+
+```markdown
+# [Compelling Technical Title]: Comprehensive {{research_topic}} Technical Research
+
+## Executive Summary
+
+[Brief compelling overview of key technical findings and strategic implications]
+
+## Table of Contents
+
+- Technical Research Introduction and Methodology
+- Technical Landscape and Architecture Analysis
+- Implementation Approaches and Best Practices
+- Technology Stack Evolution and Trends
+- Integration and Interoperability Patterns
+- Performance and Scalability Analysis
+- Security and Compliance Considerations
+- Strategic Technical Recommendations
+- Implementation Roadmap and Risk Assessment
+- Future Technical Outlook and Innovation Opportunities
+- Technical Research Methodology and Source Documentation
+- Technical Appendices and Reference Materials
+```
+
+### 2. Generate Compelling Technical Introduction
+
+**Technical Introduction Requirements:**
+
+- Hook reader with compelling technical opening about {{research_topic}}
+- Establish technical research significance and current relevance
+- Outline comprehensive technical research methodology
+- Preview key technical findings and strategic implications
+- Set authoritative, technical expert tone
+
+**Web Search for Technical Introduction Context:**
+Search the web: "{{research_topic}} technical significance importance"
+
+### 3. Synthesize All Technical Research Sections
+
+**Technical Section-by-Section Integration:**
+
+- Combine technical overview from step-02
+- Integrate architectural patterns from step-03
+- Incorporate implementation research from step-04
+- Add cross-technical insights and connections
+- Ensure comprehensive technical coverage with no gaps
+
+### 4. Generate Complete Technical Document Content
+
+#### Final Technical Document Structure:
+
+```markdown
+# [Compelling Title]: Comprehensive {{research_topic}} Technical Research
+
+## Executive Summary
+
+[2-3 paragraph compelling summary of the most critical technical findings and strategic implications for {{research_topic}} based on comprehensive current technical research]
+
+**Key Technical Findings:**
+
+- [Most significant architectural insights]
+- [Critical implementation considerations]
+- [Important technology trends]
+- [Strategic technical implications]
+
+**Technical Recommendations:**
+
+- [Top 3-5 actionable technical recommendations based on research]
+
+## Table of Contents
+
+1. Technical Research Introduction and Methodology
+2. {{research_topic}} Technical Landscape and Architecture Analysis
+3. Implementation Approaches and Best Practices
+4. Technology Stack Evolution and Current Trends
+5. Integration and Interoperability Patterns
+6. Performance and Scalability Analysis
+7. Security and Compliance Considerations
+8. Strategic Technical Recommendations
+9. Implementation Roadmap and Risk Assessment
+10. Future Technical Outlook and Innovation Opportunities
+11. Technical Research Methodology and Source Verification
+12. Technical Appendices and Reference Materials
+
+## 1. Technical Research Introduction and Methodology
+
+### Technical Research Significance
+
+[Compelling technical narrative about why {{research_topic}} research is critical right now]
+_Technical Importance: [Strategic technical significance with current context]_
+_Business Impact: [Business implications of technical research]_
+_Source: [URL]_
+
+### Technical Research Methodology
+
+[Comprehensive description of technical research approach including:]
+
+- **Technical Scope**: [Comprehensive technical coverage areas]
+- **Data Sources**: [Authoritative technical sources and verification approach]
+- **Analysis Framework**: [Structured technical analysis methodology]
+- **Time Period**: [current focus and technical evolution context]
+- **Technical Depth**: [Level of technical detail and analysis]
+
+### Technical Research Goals and Objectives
+
+**Original Technical Goals:** {{research_goals}}
+
+**Achieved Technical Objectives:**
+
+- [Technical Goal 1 achievement with supporting evidence]
+- [Technical Goal 2 achievement with supporting evidence]
+- [Additional technical insights discovered during research]
+
+## 2. {{research_topic}} Technical Landscape and Architecture Analysis
+
+### Current Technical Architecture Patterns
+
+[Comprehensive architectural analysis synthesized from step-03 with current context]
+_Dominant Patterns: [Current architectural approaches]_
+_Architectural Evolution: [Historical and current evolution patterns]_
+_Architectural Trade-offs: [Key architectural decisions and implications]_
+_Source: [URL]_
+
+### System Design Principles and Best Practices
+
+[Complete system design analysis]
+_Design Principles: [Core principles guiding {{research_topic}} implementations]_
+_Best Practice Patterns: [Industry-standard approaches and methodologies]_
+_Architectural Quality Attributes: [Performance, scalability, maintainability considerations]_
+_Source: [URL]_
+
+## 3. Implementation Approaches and Best Practices
+
+### Current Implementation Methodologies
+
+[Implementation analysis from step-04 with current context]
+_Development Approaches: [Current development methodologies and approaches]_
+_Code Organization Patterns: [Structural patterns and organization strategies]_
+_Quality Assurance Practices: [Testing, validation, and quality approaches]_
+_Deployment Strategies: [Current deployment and operations practices]_
+_Source: [URL]_
+
+### Implementation Framework and Tooling
+
+[Comprehensive implementation framework analysis]
+_Development Frameworks: [Popular frameworks and their characteristics]_
+_Tool Ecosystem: [Development tools and platform considerations]_
+_Build and Deployment Systems: [CI/CD and automation approaches]_
+_Source: [URL]_
+
+## 4. Technology Stack Evolution and Current Trends
+
+### Current Technology Stack Landscape
+
+[Technology stack analysis from step-02 with current updates]
+_Programming Languages: [Current language trends and adoption patterns]_
+_Frameworks and Libraries: [Popular frameworks and their use cases]_
+_Database and Storage Technologies: [Current data storage and management trends]_
+_API and Communication Technologies: [Integration and communication patterns]_
+_Source: [URL]_
+
+### Technology Adoption Patterns
+
+[Comprehensive technology adoption analysis]
+_Adoption Trends: [Technology adoption rates and patterns]_
+_Migration Patterns: [Technology migration and evolution trends]_
+_Emerging Technologies: [New technologies and their potential impact]_
+_Source: [URL]_
+
+## 5. Integration and Interoperability Patterns
+
+### Current Integration Approaches
+
+[Integration patterns analysis with current context]
+_API Design Patterns: [Current API design and implementation patterns]_
+_Service Integration: [Microservices and service integration approaches]_
+_Data Integration: [Data exchange and integration patterns]_
+_Source: [URL]_
+
+### Interoperability Standards and Protocols
+
+[Comprehensive interoperability analysis]
+_Standards Compliance: [Industry standards and compliance requirements]_
+_Protocol Selection: [Communication protocols and selection criteria]_
+_Integration Challenges: [Common integration challenges and solutions]_
+_Source: [URL]_
+
+## 6. Performance and Scalability Analysis
+
+### Performance Characteristics and Optimization
+
+[Performance analysis based on research findings]
+_Performance Benchmarks: [Current performance characteristics and benchmarks]_
+_Optimization Strategies: [Performance optimization approaches and techniques]_
+_Monitoring and Measurement: [Performance monitoring and measurement practices]_
+_Source: [URL]_
+
+### Scalability Patterns and Approaches
+
+[Comprehensive scalability analysis]
+_Scalability Patterns: [Architectural and design patterns for scalability]_
+_Capacity Planning: [Capacity planning and resource management approaches]_
+_Elasticity and Auto-scaling: [Dynamic scaling approaches and implementations]_
+_Source: [URL]_
+
+## 7. Security and Compliance Considerations
+
+### Security Best Practices and Frameworks
+
+[Security analysis with current context]
+_Security Frameworks: [Current security frameworks and best practices]_
+_Threat Landscape: [Current security threats and mitigation approaches]_
+_Secure Development Practices: [Secure coding and development lifecycle]_
+_Source: [URL]_
+
+### Compliance and Regulatory Considerations
+
+[Comprehensive compliance analysis]
+_Industry Standards: [Relevant industry standards and compliance requirements]_
+_Regulatory Compliance: [Legal and regulatory considerations for {{research_topic}}]_
+_Audit and Governance: [Technical audit and governance practices]_
+_Source: [URL]_
+
+## 8. Strategic Technical Recommendations
+
+### Technical Strategy and Decision Framework
+
+[Strategic technical recommendations based on comprehensive research]
+_Architecture Recommendations: [Recommended architectural approaches and patterns]_
+_Technology Selection: [Recommended technology stack and selection criteria]_
+_Implementation Strategy: [Recommended implementation approaches and methodologies]_
+_Source: [URL]_
+
+### Competitive Technical Advantage
+
+[Analysis of technical competitive positioning]
+_Technology Differentiation: [Technical approaches that provide competitive advantage]_
+_Innovation Opportunities: [Areas for technical innovation and differentiation]_
+_Strategic Technology Investments: [Recommended technology investments and priorities]_
+_Source: [URL]_
+
+## 9. Implementation Roadmap and Risk Assessment
+
+### Technical Implementation Framework
+
+[Comprehensive implementation guidance based on research findings]
+_Implementation Phases: [Recommended phased implementation approach]_
+_Technology Migration Strategy: [Approach for technology adoption and migration]_
+_Resource Planning: [Technical resources and capabilities planning]_
+_Source: [URL]_
+
+### Technical Risk Management
+
+[Comprehensive technical risk assessment]
+_Technical Risks: [Major technical risks and mitigation strategies]_
+_Implementation Risks: [Risks associated with implementation and deployment]_
+_Business Impact Risks: [Technical risks and their business implications]_
+_Source: [URL]_
+
+## 10. Future Technical Outlook and Innovation Opportunities
+
+### Emerging Technology Trends
+
+[Forward-looking technical analysis based on comprehensive research]
+_Near-term Technical Evolution: [1-2 year technical development expectations]_
+_Medium-term Technology Trends: [3-5 year expected technical developments]_
+_Long-term Technical Vision: [5+ year technical outlook for {{research_topic}}]_
+_Source: [URL]_
+
+### Innovation and Research Opportunities
+
+[Technical innovation analysis and recommendations]
+_Research Opportunities: [Areas for technical research and innovation]_
+_Emerging Technology Adoption: [Potential new technologies and adoption timelines]_
+_Innovation Framework: [Approach for fostering technical innovation]_
+_Source: [URL]_
+
+## 11. Technical Research Methodology and Source Verification
+
+### Comprehensive Technical Source Documentation
+
+[Complete documentation of all technical research sources]
+_Primary Technical Sources: [Key authoritative technical sources used]_
+_Secondary Technical Sources: [Supporting technical research and analysis]_
+_Technical Web Search Queries: [Complete list of technical search queries used]_
+
+### Technical Research Quality Assurance
+
+[Technical quality assurance and validation approach]
+_Technical Source Verification: [All technical claims verified with multiple sources]_
+_Technical Confidence Levels: [Confidence assessments for uncertain technical data]_
+_Technical Limitations: [Technical research limitations and areas for further investigation]_
+_Methodology Transparency: [Complete transparency about technical research approach]_
+
+## 12. Technical Appendices and Reference Materials
+
+### Detailed Technical Data Tables
+
+[Comprehensive technical data tables supporting research findings]
+_Architectural Pattern Tables: [Detailed architectural pattern comparisons]_
+_Technology Stack Analysis: [Detailed technology evaluation and comparison data]_
+_Performance Benchmark Data: [Comprehensive performance measurement data]_
+
+### Technical Resources and References
+
+[Valuable technical resources for continued research and implementation]
+_Technical Standards: [Relevant technical standards and specifications]_
+_Open Source Projects: [Key open source projects and communities]_
+_Research Papers and Publications: [Academic and industry research sources]_
+_Technical Communities: [Professional networks and technical communities]_
+
+---
+
+## Technical Research Conclusion
+
+### Summary of Key Technical Findings
+
+[Comprehensive summary of the most important technical research findings]
+
+### Strategic Technical Impact Assessment
+
+[Assessment of technical implications for {{research_topic}}]
+
+### Next Steps Technical Recommendations
+
+[Specific next steps for leveraging this technical research]
+
+---
+
+**Technical Research Completion Date:** {{date}}
+**Research Period:** current comprehensive technical analysis
+**Document Length:** As needed for comprehensive technical coverage
+**Source Verification:** All technical facts cited with current sources
+**Technical Confidence Level:** High - based on multiple authoritative technical sources
+
+_This comprehensive technical research document serves as an authoritative technical reference on {{research_topic}} and provides strategic technical insights for informed decision-making and implementation._
+```
+
+### 5. Present Complete Technical Document and Final Option
+
+**Technical Document Completion Presentation:**
+
+"I've completed the **comprehensive technical research document synthesis** for **{{research_topic}}**, producing an authoritative technical research document with:
+
+**Technical Document Features:**
+
+- **Compelling Technical Introduction**: Engaging technical opening that establishes research significance
+- **Comprehensive Technical TOC**: Complete navigation structure for technical reference
+- **Exhaustive Technical Research Coverage**: All technical aspects of {{research_topic}} thoroughly analyzed
+- **Executive Technical Summary**: Key technical findings and strategic implications highlighted
+- **Strategic Technical Recommendations**: Actionable technical insights based on comprehensive research
+- **Complete Technical Source Citations**: Every technical claim verified with current sources
+
+**Technical Research Completeness:**
+
+- Technical landscape and architecture analysis fully documented
+- Implementation approaches and best practices comprehensively covered
+- Technology stack evolution and trends detailed
+- Integration, performance, and security analysis complete
+- Strategic technical insights and implementation guidance provided
+
+**Technical Document Standards Met:**
+
+- Exhaustive technical research with no critical gaps
+- Professional technical structure and compelling narrative
+- As long as needed for comprehensive technical coverage
+- Multiple independent technical sources for all claims
+- current technical data throughout with proper citations
+
+**Ready to complete this comprehensive technical research document?**
+[C] Complete Research - Save final comprehensive technical document
+
+### 6. Handle Final Technical Completion
+
+#### If 'C' (Complete Research):
+
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
+- Append the complete technical document to the research file
+- Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6]`
+- Complete the technical research workflow
+- Provide final technical document delivery confirmation
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the complete comprehensive technical research document using the full structure above. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
+
+## SUCCESS METRICS:
+
+✅ Compelling technical introduction with research significance
+✅ Comprehensive technical table of contents with complete document structure
+✅ Exhaustive technical research coverage across all technical aspects
+✅ Executive technical summary with key findings and strategic implications
+✅ Strategic technical recommendations grounded in comprehensive research
+✅ Complete technical source verification with current citations
+✅ Professional technical document structure and compelling narrative
+✅ [C] complete option presented and handled correctly
+✅ Technical research workflow completed with comprehensive document
+
+## FAILURE MODES:
+
+❌ Not producing compelling technical introduction
+❌ Missing comprehensive technical table of contents
+❌ Incomplete technical research coverage across technical aspects
+❌ Not providing executive technical summary with key findings
+❌ Missing strategic technical recommendations based on research
+❌ Relying solely on training data without web verification for current facts
+❌ Producing technical document without professional structure
+❌ Not presenting completion option for final technical document
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+## COMPREHENSIVE TECHNICAL DOCUMENT STANDARDS:
+
+This step ensures the final technical research document:
+
+- Serves as an authoritative technical reference on {{research_topic}}
+- Provides strategic technical insights for informed decision-making
+- Includes comprehensive technical coverage with no gaps
+- Maintains rigorous technical source verification standards
+- Delivers strategic technical insights and actionable recommendations
+- Meets professional technical research document quality standards
+
+## TECHNICAL RESEARCH WORKFLOW COMPLETION:
+
+When 'C' is selected:
+
+- All technical research steps completed (1-5)
+- Comprehensive technical research document generated
+- Professional technical document structure with intro, TOC, and summary
+- All technical sections appended with source citations
+- Technical research workflow status updated to complete
+- Final comprehensive technical research document delivered to user
+
+## FINAL TECHNICAL DELIVERABLE:
+
+Complete authoritative technical research document on {{research_topic}} that:
+
+- Establishes technical credibility through comprehensive research
+- Provides strategic technical insights for informed decision-making
+- Serves as technical reference document for continued use
+- Maintains highest technical research quality standards with current verification
+
+Congratulations on completing comprehensive technical research with professional documentation! 🎉
diff --git a/.claude/skills/bmad-technical-research/workflow.md b/.claude/skills/bmad-technical-research/workflow.md
new file mode 100644
index 0000000..f85b147
--- /dev/null
+++ b/.claude/skills/bmad-technical-research/workflow.md
@@ -0,0 +1,52 @@
+
+# Technical Research Workflow
+
+**Goal:** Conduct comprehensive technical research using current web data and verified sources to produce complete research documents with compelling narratives and proper citations.
+
+**Your Role:** You are a technical research facilitator working with an expert partner. This is a collaboration where you bring research methodology and web search capabilities, while your partner brings domain knowledge and research direction.
+
+## PREREQUISITE
+
+**⛔ Web search required.** If unavailable, abort and tell the user.
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+## QUICK TOPIC DISCOVERY
+
+"Welcome {{user_name}}! Let's get started with your **technical research**.
+
+**What technology, tool, or technical area do you want to research?**
+
+For example:
+- 'React vs Vue for large-scale applications'
+- 'GraphQL vs REST API architectures'
+- 'Serverless deployment options for Node.js'
+- 'Or any other technical topic you have in mind...'"
+
+### Topic Clarification
+
+Based on the user's topic, briefly clarify:
+1. **Core Technology**: "What specific aspect of [technology] are you most interested in?"
+2. **Research Goals**: "What do you hope to achieve with this research?"
+3. **Scope**: "Should we focus broadly or dive deep into specific aspects?"
+
+## ROUTE TO TECHNICAL RESEARCH STEPS
+
+After gathering the topic and goals:
+
+1. Set `research_type = "technical"`
+2. Set `research_topic = [discovered topic from discussion]`
+3. Set `research_goals = [discovered goals from discussion]`
+4. Create the starter output file: `{planning_artifacts}/research/technical-{{research_topic}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents
+5. Load: `./technical-steps/step-01-init.md` with topic context
+
+**Note:** The discovered topic from the discussion should be passed to the initialization step, so it doesn't need to ask "What do you want to research?" again - it can focus on refining the scope for technical research.
+
+**✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`**
diff --git a/.claude/skills/bmad-validate-prd/SKILL.md b/.claude/skills/bmad-validate-prd/SKILL.md
new file mode 100644
index 0000000..77b523b
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: bmad-validate-prd
+description: 'Validate a PRD against standards. Use when the user says "validate this PRD" or "run PRD validation"'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/.claude/skills/bmad-validate-prd/data/domain-complexity.csv b/.claude/skills/bmad-validate-prd/data/domain-complexity.csv
new file mode 100644
index 0000000..60a7b50
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/data/domain-complexity.csv
@@ -0,0 +1,15 @@
+domain,signals,complexity,key_concerns,required_knowledge,suggested_workflow,web_searches,special_sections
+healthcare,"medical,diagnostic,clinical,FDA,patient,treatment,HIPAA,therapy,pharma,drug",high,"FDA approval;Clinical validation;HIPAA compliance;Patient safety;Medical device classification;Liability","Regulatory pathways;Clinical trial design;Medical standards;Data privacy;Integration requirements","domain-research","FDA software medical device guidance {date};HIPAA compliance software requirements;Medical software standards {date};Clinical validation software","clinical_requirements;regulatory_pathway;validation_methodology;safety_measures"
+fintech,"payment,banking,trading,investment,crypto,wallet,transaction,KYC,AML,funds,fintech",high,"Regional compliance;Security standards;Audit requirements;Fraud prevention;Data protection","KYC/AML requirements;PCI DSS;Open banking;Regional laws (US/EU/APAC);Crypto regulations","domain-research","fintech regulations {date};payment processing compliance {date};open banking API standards;cryptocurrency regulations {date}","compliance_matrix;security_architecture;audit_requirements;fraud_prevention"
+govtech,"government,federal,civic,public sector,citizen,municipal,voting",high,"Procurement rules;Security clearance;Accessibility (508);FedRAMP;Privacy;Transparency","Government procurement;Security frameworks;Accessibility standards;Privacy laws;Open data requirements","domain-research","government software procurement {date};FedRAMP compliance requirements;section 508 accessibility;government security standards","procurement_compliance;security_clearance;accessibility_standards;transparency_requirements"
+edtech,"education,learning,student,teacher,curriculum,assessment,K-12,university,LMS",medium,"Student privacy (COPPA/FERPA);Accessibility;Content moderation;Age verification;Curriculum standards","Educational privacy laws;Learning standards;Accessibility requirements;Content guidelines;Assessment validity","domain-research","educational software privacy {date};COPPA FERPA compliance;WCAG education requirements;learning management standards","privacy_compliance;content_guidelines;accessibility_features;curriculum_alignment"
+aerospace,"aircraft,spacecraft,aviation,drone,satellite,propulsion,flight,radar,navigation",high,"Safety certification;DO-178C compliance;Performance validation;Simulation accuracy;Export controls","Aviation standards;Safety analysis;Simulation validation;ITAR/export controls;Performance requirements","domain-research + technical-model","DO-178C software certification;aerospace simulation standards {date};ITAR export controls software;aviation safety requirements","safety_certification;simulation_validation;performance_requirements;export_compliance"
+automotive,"vehicle,car,autonomous,ADAS,automotive,driving,EV,charging",high,"Safety standards;ISO 26262;V2X communication;Real-time requirements;Certification","Automotive standards;Functional safety;V2X protocols;Real-time systems;Testing requirements","domain-research","ISO 26262 automotive software;automotive safety standards {date};V2X communication protocols;EV charging standards","safety_standards;functional_safety;communication_protocols;certification_requirements"
+scientific,"research,algorithm,simulation,modeling,computational,analysis,data science,ML,AI",medium,"Reproducibility;Validation methodology;Peer review;Performance;Accuracy;Computational resources","Scientific method;Statistical validity;Computational requirements;Domain expertise;Publication standards","technical-model","scientific computing best practices {date};research reproducibility standards;computational modeling validation;peer review software","validation_methodology;accuracy_metrics;reproducibility_plan;computational_requirements"
+legaltech,"legal,law,contract,compliance,litigation,patent,attorney,court",high,"Legal ethics;Bar regulations;Data retention;Attorney-client privilege;Court system integration","Legal practice rules;Ethics requirements;Court filing systems;Document standards;Confidentiality","domain-research","legal technology ethics {date};law practice management software requirements;court filing system standards;attorney client privilege technology","ethics_compliance;data_retention;confidentiality_measures;court_integration"
+insuretech,"insurance,claims,underwriting,actuarial,policy,risk,premium",high,"Insurance regulations;Actuarial standards;Data privacy;Fraud detection;State compliance","Insurance regulations by state;Actuarial methods;Risk modeling;Claims processing;Regulatory reporting","domain-research","insurance software regulations {date};actuarial standards software;insurance fraud detection;state insurance compliance","regulatory_requirements;risk_modeling;fraud_detection;reporting_compliance"
+energy,"energy,utility,grid,solar,wind,power,electricity,oil,gas",high,"Grid compliance;NERC standards;Environmental regulations;Safety requirements;Real-time operations","Energy regulations;Grid standards;Environmental compliance;Safety protocols;SCADA systems","domain-research","energy sector software compliance {date};NERC CIP standards;smart grid requirements;renewable energy software standards","grid_compliance;safety_protocols;environmental_compliance;operational_requirements"
+process_control,"industrial automation,process control,PLC,SCADA,DCS,HMI,operational technology,OT,control system,cyberphysical,MES,historian,instrumentation,I&C,P&ID",high,"Functional safety;OT cybersecurity;Real-time control requirements;Legacy system integration;Process safety and hazard analysis;Environmental compliance and permitting;Engineering authority and PE requirements","Functional safety standards;OT security frameworks;Industrial protocols;Process control architecture;Plant reliability and maintainability","domain-research + technical-model","IEC 62443 OT cybersecurity requirements {date};functional safety software requirements {date};industrial process control architecture;ISA-95 manufacturing integration","functional_safety;ot_security;process_requirements;engineering_authority"
+building_automation,"building automation,BAS,BMS,HVAC,smart building,lighting control,fire alarm,fire protection,fire suppression,life safety,elevator,access control,DDC,energy management,sequence of operations,commissioning",high,"Life safety codes;Building energy standards;Multi-trade coordination and interoperability;Commissioning and ongoing operational performance;Indoor environmental quality and occupant comfort;Engineering authority and PE requirements","Building automation protocols;HVAC and mechanical controls;Fire alarm, fire protection, and life safety design;Commissioning process and sequence of operations;Building codes and energy standards","domain-research","smart building software architecture {date};BACnet integration best practices;building automation cybersecurity {date};ASHRAE building standards","life_safety;energy_compliance;commissioning_requirements;engineering_authority"
+gaming,"game,player,gameplay,level,character,multiplayer,quest",redirect,"REDIRECT TO GAME WORKFLOWS","Game design","game-brief","NA","NA"
+general,"",low,"Standard requirements;Basic security;User experience;Performance","General software practices","continue","software development best practices {date}","standard_requirements"
\ No newline at end of file
diff --git a/.claude/skills/bmad-validate-prd/data/prd-purpose.md b/.claude/skills/bmad-validate-prd/data/prd-purpose.md
new file mode 100644
index 0000000..755230b
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/data/prd-purpose.md
@@ -0,0 +1,197 @@
+# BMAD PRD Purpose
+
+**The PRD is the top of the required funnel that feeds all subsequent product development work in rhw BMad Method.**
+
+---
+
+## What is a BMAD PRD?
+
+A dual-audience document serving:
+1. **Human Product Managers and builders** - Vision, strategy, stakeholder communication
+2. **LLM Downstream Consumption** - UX Design → Architecture → Epics → Development AI Agents
+
+Each successive document becomes more AI-tailored and granular.
+
+---
+
+## Core Philosophy: Information Density
+
+**High Signal-to-Noise Ratio**
+
+Every sentence must carry information weight. LLMs consume precise, dense content efficiently.
+
+**Anti-Patterns (Eliminate These):**
+- ❌ "The system will allow users to..." → ✅ "Users can..."
+- ❌ "It is important to note that..." → ✅ State the fact directly
+- ❌ "In order to..." → ✅ "To..."
+- ❌ Conversational filler and padding → ✅ Direct, concise statements
+
+**Goal:** Maximum information per word. Zero fluff.
+
+---
+
+## The Traceability Chain
+
+**PRD starts the chain:**
+```
+Vision → Success Criteria → User Journeys → Functional Requirements → (future: User Stories)
+```
+
+**In the PRD, establish:**
+- Vision → Success Criteria alignment
+- Success Criteria → User Journey coverage
+- User Journey → Functional Requirement mapping
+- All requirements traceable to user needs
+
+**Why:** Each downstream artifact (UX, Architecture, Epics, Stories) must trace back to documented user needs and business objectives. This chain ensures we build the right thing.
+
+---
+
+## What Makes Great Functional Requirements?
+
+### FRs are Capabilities, Not Implementation
+
+**Good FR:** "Users can reset their password via email link"
+**Bad FR:** "System sends JWT via email and validates with database" (implementation leakage)
+
+**Good FR:** "Dashboard loads in under 2 seconds for 95th percentile"
+**Bad FR:** "Fast loading time" (subjective, unmeasurable)
+
+### SMART Quality Criteria
+
+**Specific:** Clear, precisely defined capability
+**Measurable:** Quantifiable with test criteria
+**Attainable:** Realistic within constraints
+**Relevant:** Aligns with business objectives
+**Traceable:** Links to source (executive summary or user journey)
+
+### FR Anti-Patterns
+
+**Subjective Adjectives:**
+- ❌ "easy to use", "intuitive", "user-friendly", "fast", "responsive"
+- ✅ Use metrics: "completes task in under 3 clicks", "loads in under 2 seconds"
+
+**Implementation Leakage:**
+- ❌ Technology names, specific libraries, implementation details
+- ✅ Focus on capability and measurable outcomes
+
+**Vague Quantifiers:**
+- ❌ "multiple users", "several options", "various formats"
+- ✅ "up to 100 concurrent users", "3-5 options", "PDF, DOCX, TXT formats"
+
+**Missing Test Criteria:**
+- ❌ "The system shall provide notifications"
+- ✅ "The system shall send email notifications within 30 seconds of trigger event"
+
+---
+
+## What Makes Great Non-Functional Requirements?
+
+### NFRs Must Be Measurable
+
+**Template:**
+```
+"The system shall [metric] [condition] [measurement method]"
+```
+
+**Examples:**
+- ✅ "The system shall respond to API requests in under 200ms for 95th percentile as measured by APM monitoring"
+- ✅ "The system shall maintain 99.9% uptime during business hours as measured by cloud provider SLA"
+- ✅ "The system shall support 10,000 concurrent users as measured by load testing"
+
+### NFR Anti-Patterns
+
+**Unmeasurable Claims:**
+- ❌ "The system shall be scalable" → ✅ "The system shall handle 10x load growth through horizontal scaling"
+- ❌ "High availability required" → ✅ "99.9% uptime as measured by cloud provider SLA"
+
+**Missing Context:**
+- ❌ "Response time under 1 second" → ✅ "API response time under 1 second for 95th percentile under normal load"
+
+---
+
+## Domain-Specific Requirements
+
+**Auto-Detect and Enforce Based on Project Context**
+
+Certain industries have mandatory requirements that must be present:
+
+- **Healthcare:** HIPAA Privacy & Security Rules, PHI encryption, audit logging, MFA
+- **Fintech:** PCI-DSS Level 1, AML/KYC compliance, SOX controls, financial audit trails
+- **GovTech:** NIST framework, Section 508 accessibility (WCAG 2.1 AA), FedRAMP, data residency
+- **E-Commerce:** PCI-DSS for payments, inventory accuracy, tax calculation by jurisdiction
+
+**Why:** Missing these requirements in the PRD means they'll be missed in architecture and implementation, creating expensive rework. During PRD creation there is a step to cover this - during validation we want to make sure it was covered. For this purpose steps will utilize a domain-complexity.csv and project-types.csv.
+
+---
+
+## Document Structure (Markdown, Human-Readable)
+
+### Required Sections
+1. **Executive Summary** - Vision, differentiator, target users
+2. **Success Criteria** - Measurable outcomes (SMART)
+3. **Product Scope** - MVP, Growth, Vision phases
+4. **User Journeys** - Comprehensive coverage
+5. **Domain Requirements** - Industry-specific compliance (if applicable)
+6. **Innovation Analysis** - Competitive differentiation (if applicable)
+7. **Project-Type Requirements** - Platform-specific needs
+8. **Functional Requirements** - Capability contract (FRs)
+9. **Non-Functional Requirements** - Quality attributes (NFRs)
+
+### Formatting for Dual Consumption
+
+**For Humans:**
+- Clear, professional language
+- Logical flow from vision to requirements
+- Easy for stakeholders to review and approve
+
+**For LLMs:**
+- ## Level 2 headers for all main sections (enables extraction)
+- Consistent structure and patterns
+- Precise, testable language
+- High information density
+
+---
+
+## Downstream Impact
+
+**How the PRD Feeds Next Artifacts:**
+
+**UX Design:**
+- User journeys → interaction flows
+- FRs → design requirements
+- Success criteria → UX metrics
+
+**Architecture:**
+- FRs → system capabilities
+- NFRs → architecture decisions
+- Domain requirements → compliance architecture
+- Project-type requirements → platform choices
+
+**Epics & Stories (created after architecture):**
+- FRs → user stories (1 FR could map to 1-3 stories potentially)
+- Acceptance criteria → story acceptance tests
+- Priority → sprint sequencing
+- Traceability → stories map back to vision
+
+**Development AI Agents:**
+- Precise requirements → implementation clarity
+- Test criteria → automated test generation
+- Domain requirements → compliance enforcement
+- Measurable NFRs → performance targets
+
+---
+
+## Summary: What Makes a Great BMAD PRD?
+
+✅ **High Information Density** - Every sentence carries weight, zero fluff
+✅ **Measurable Requirements** - All FRs and NFRs are testable with specific criteria
+✅ **Clear Traceability** - Each requirement links to user need and business objective
+✅ **Domain Awareness** - Industry-specific requirements auto-detected and included
+✅ **Zero Anti-Patterns** - No subjective adjectives, implementation leakage, or vague quantifiers
+✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable
+✅ **Markdown Format** - Professional, clean, accessible to all stakeholders
+
+---
+
+**Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective.
diff --git a/.claude/skills/bmad-validate-prd/data/project-types.csv b/.claude/skills/bmad-validate-prd/data/project-types.csv
new file mode 100644
index 0000000..6f71c51
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/data/project-types.csv
@@ -0,0 +1,11 @@
+project_type,detection_signals,key_questions,required_sections,skip_sections,web_search_triggers,innovation_signals
+api_backend,"API,REST,GraphQL,backend,service,endpoints","Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?","endpoint_specs;auth_model;data_schemas;error_codes;rate_limits;api_docs","ux_ui;visual_design;user_journeys","framework best practices;OpenAPI standards","API composition;New protocol"
+mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features"
+saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents"
+developer_tool,"SDK,library,package,npm,pip,framework","Language support?;Package managers?;IDE integration?;Documentation?;Examples?","language_matrix;installation_methods;api_surface;code_examples;migration_guide","visual_design;store_compliance","package manager best practices;API design patterns","New paradigm;DSL creation"
+cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands"
+web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO needed?;Real-time?;Accessibility?","browser_matrix;responsive_design;performance_targets;seo_strategy;accessibility_level","native_features;cli_commands","web standards;WCAG guidelines","New interaction;WebAssembly use"
+game,"game,player,gameplay,level,character","REDIRECT TO USE THE BMad Method Game Module Agent and Workflows - HALT","game-brief;GDD","most_sections","game design patterns","Novel mechanics;Genre mixing"
+desktop_app,"desktop,Windows,Mac,Linux,native","Cross-platform?;Auto-update?;System integration?;Offline?","platform_support;system_integration;update_strategy;offline_capabilities","web_seo;mobile_features","desktop guidelines;platform requirements","Desktop AI;System automation"
+iot_embedded,"IoT,embedded,device,sensor,hardware","Hardware specs?;Connectivity?;Power constraints?;Security?;OTA updates?","hardware_reqs;connectivity_protocol;power_profile;security_model;update_mechanism","visual_ui;browser_support","IoT standards;protocol specs","Edge AI;New sensors"
+blockchain_web3,"blockchain,crypto,DeFi,NFT,smart contract","Chain selection?;Wallet integration?;Gas optimization?;Security audit?","chain_specs;wallet_support;smart_contracts;security_audit;gas_optimization","traditional_auth;centralized_db","blockchain standards;security patterns","Novel tokenomics;DAO structure"
\ No newline at end of file
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-01-discovery.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-01-discovery.md
new file mode 100644
index 0000000..feb0026
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-01-discovery.md
@@ -0,0 +1,221 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-02-format-detection.md'
+prdPurpose: '../data/prd-purpose.md'
+---
+
+# Step 1: Document Discovery & Confirmation
+
+## STEP GOAL:
+
+Handle fresh context validation by confirming PRD path, discovering and loading input documents from frontmatter, and initializing the validation report.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring systematic validation expertise and analytical rigor
+- ✅ User brings domain knowledge and specific PRD context
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on discovering PRD and input documents, not validating yet
+- 🚫 FORBIDDEN to perform any validation checks in this step
+- 💬 Approach: Systematic discovery with clear reporting to user
+- 🚪 This is the setup step - get everything ready for validation
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Discover and confirm PRD to validate
+- 💾 Load PRD and all input documents from frontmatter
+- 📖 Initialize validation report next to PRD
+- 🚫 FORBIDDEN to load next step until user confirms setup
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD path (user-specified or discovered), workflow configuration
+- Focus: Document discovery and setup only
+- Limits: Don't perform validation, don't skip discovery
+- Dependencies: Configuration loaded from PRD workflow.md initialization
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load PRD Purpose and Standards
+
+Load and read the complete file at:
+`{prdPurpose}`
+
+This file contains the BMAD PRD philosophy, standards, and validation criteria that will guide all validation checks. Internalize this understanding - it defines what makes a great BMAD PRD.
+
+### 2. Discover PRD to Validate
+
+**If PRD path provided as invocation parameter:**
+- Use provided path
+
+**If no PRD path provided, auto-discover:**
+- Search `{planning_artifacts}` for files matching `*prd*.md`
+- Also check for sharded PRDs: `{planning_artifacts}/*prd*/*.md`
+
+**If exactly ONE PRD found:**
+- Use it automatically
+- Inform user: "Found PRD: {discovered_path} — using it for validation."
+
+**If MULTIPLE PRDs found:**
+- List all discovered PRDs with numbered options
+- "I found multiple PRDs. Which one would you like to validate?"
+- Wait for user selection
+
+**If NO PRDs found:**
+- "I couldn't find any PRD files in {planning_artifacts}. Please provide the path to the PRD file you want to validate."
+- Wait for user to provide PRD path.
+
+### 3. Validate PRD Exists and Load
+
+Once PRD path is provided:
+
+- Check if PRD file exists at specified path
+- If not found: "I cannot find a PRD at that path. Please check the path and try again."
+- If found: Load the complete PRD file including frontmatter
+
+### 4. Extract Frontmatter and Input Documents
+
+From the loaded PRD frontmatter, extract:
+
+- `inputDocuments: []` array (if present)
+- Any other relevant metadata (classification, date, etc.)
+
+**If no inputDocuments array exists:**
+Note this and proceed with PRD-only validation
+
+### 5. Load Input Documents
+
+For each document listed in `inputDocuments`:
+
+- Attempt to load the document
+- Track successfully loaded documents
+- Note any documents that fail to load
+
+**Build list of loaded input documents:**
+- Product Brief (if present)
+- Research documents (if present)
+- Other reference materials (if present)
+
+### 6. Ask About Additional Reference Documents
+
+"**I've loaded the following documents from your PRD frontmatter:**
+
+{list loaded documents with file names}
+
+**Are there any additional reference documents you'd like me to include in this validation?**
+
+These could include:
+- Additional research or context documents
+- Project documentation not tracked in frontmatter
+- Standards or compliance documents
+- Competitive analysis or benchmarks
+
+Please provide paths to any additional documents, or type 'none' to proceed."
+
+**Load any additional documents provided by user.**
+
+### 7. Initialize Validation Report
+
+Create validation report at: `{validationReportPath}`
+
+**Initialize with frontmatter:**
+```yaml
+---
+validationTarget: '{prd_path}'
+validationDate: '{current_date}'
+inputDocuments: [list of all loaded documents]
+validationStepsCompleted: []
+validationStatus: IN_PROGRESS
+---
+```
+
+**Initial content:**
+```markdown
+# PRD Validation Report
+
+**PRD Being Validated:** {prd_path}
+**Validation Date:** {current_date}
+
+## Input Documents
+
+{list all documents loaded for validation}
+
+## Validation Findings
+
+[Findings will be appended as validation progresses]
+```
+
+### 8. Present Discovery Summary
+
+"**Setup Complete!**
+
+**PRD to Validate:** {prd_path}
+
+**Input Documents Loaded:**
+- PRD: {prd_name} ✓
+- Product Brief: {count} {if count > 0}✓{else}(none found){/if}
+- Research: {count} {if count > 0}✓{else}(none found){/if}
+- Additional References: {count} {if count > 0}✓{else}(none){/if}
+
+**Validation Report:** {validationReportPath}
+
+**Ready to begin validation.**"
+
+### 9. Present MENU OPTIONS
+
+Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Format Detection
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can ask questions or add more documents - always respond and redisplay menu
+
+#### Menu Handling Logic:
+
+- IF A: Invoke the `bmad-advanced-elicitation` skill, and when finished redisplay the menu
+- IF P: Invoke the `bmad-party-mode` skill, and when finished redisplay the menu
+- IF C: Read fully and follow: {nextStepFile} to begin format detection
+- IF user provides additional document: Load it, update report, redisplay summary
+- IF Any other: help user, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- PRD path discovered and confirmed
+- PRD file exists and loads successfully
+- All input documents from frontmatter loaded
+- Additional reference documents (if any) loaded
+- Validation report initialized next to PRD
+- User clearly informed of setup status
+- Menu presented and user input handled correctly
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with non-existent PRD file
+- Not loading input documents from frontmatter
+- Creating validation report in wrong location
+- Proceeding without user confirming setup
+- Not handling missing input documents gracefully
+
+**Master Rule:** Complete discovery and setup BEFORE validation. This step ensures everything is in place for systematic validation checks.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-02-format-detection.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-02-format-detection.md
new file mode 100644
index 0000000..1211ca6
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-02-format-detection.md
@@ -0,0 +1,188 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-03-density-validation.md'
+altStepFile: './step-v-02b-parity-check.md'
+prdFile: '{prd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step 2: Format Detection & Structure Analysis
+
+## STEP GOAL:
+
+Detect if PRD follows BMAD format and route appropriately - classify as BMAD Standard / BMAD Variant / Non-Standard, with optional parity check for non-standard formats.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring systematic validation expertise and pattern recognition
+- ✅ User brings domain knowledge and PRD context
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on detecting format and classifying structure
+- 🚫 FORBIDDEN to perform other validation checks in this step
+- 💬 Approach: Analytical and systematic, clear reporting of findings
+- 🚪 This is a branch step - may route to parity check for non-standard PRDs
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Analyze PRD structure systematically
+- 💾 Append format findings to validation report
+- 📖 Route appropriately based on format classification
+- 🚫 FORBIDDEN to skip format detection or proceed without classification
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file loaded in step 1, validation report initialized
+- Focus: Format detection and classification only
+- Limits: Don't perform other validation, don't skip classification
+- Dependencies: Step 1 completed - PRD loaded and report initialized
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Extract PRD Structure
+
+Load the complete PRD file and extract:
+
+**All Level 2 (##) headers:**
+- Scan through entire PRD document
+- Extract all ## section headers
+- List them in order
+
+**PRD frontmatter:**
+- Extract classification.domain if present
+- Extract classification.projectType if present
+- Note any other relevant metadata
+
+### 2. Check for BMAD PRD Core Sections
+
+Check if the PRD contains the following BMAD PRD core sections:
+
+1. **Executive Summary** (or variations: ## Executive Summary, ## Overview, ## Introduction)
+2. **Success Criteria** (or: ## Success Criteria, ## Goals, ## Objectives)
+3. **Product Scope** (or: ## Product Scope, ## Scope, ## In Scope, ## Out of Scope)
+4. **User Journeys** (or: ## User Journeys, ## User Stories, ## User Flows)
+5. **Functional Requirements** (or: ## Functional Requirements, ## Features, ## Capabilities)
+6. **Non-Functional Requirements** (or: ## Non-Functional Requirements, ## NFRs, ## Quality Attributes)
+
+**Count matches:**
+- How many of these 6 core sections are present?
+- Which specific sections are present?
+- Which are missing?
+
+### 3. Classify PRD Format
+
+Based on core section count, classify:
+
+**BMAD Standard:**
+- 5-6 core sections present
+- Follows BMAD PRD structure closely
+
+**BMAD Variant:**
+- 3-4 core sections present
+- Generally follows BMAD patterns but may have structural differences
+- Missing some sections but recognizable as BMAD-style
+
+**Non-Standard:**
+- Fewer than 3 core sections present
+- Does not follow BMAD PRD structure
+- May be completely custom format, legacy format, or from another framework
+
+### 4. Report Format Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Format Detection
+
+**PRD Structure:**
+[List all ## Level 2 headers found]
+
+**BMAD Core Sections Present:**
+- Executive Summary: [Present/Missing]
+- Success Criteria: [Present/Missing]
+- Product Scope: [Present/Missing]
+- User Journeys: [Present/Missing]
+- Functional Requirements: [Present/Missing]
+- Non-Functional Requirements: [Present/Missing]
+
+**Format Classification:** [BMAD Standard / BMAD Variant / Non-Standard]
+**Core Sections Present:** [count]/6
+```
+
+### 5. Route Based on Format Classification
+
+**IF format is BMAD Standard or BMAD Variant:**
+
+Display: "**Format Detected:** {classification}
+
+Proceeding to systematic validation checks..."
+
+Without delay, read fully and follow: {nextStepFile} (step-v-03-density-validation.md)
+
+**IF format is Non-Standard (< 3 core sections):**
+
+Display: "**Format Detected:** Non-Standard PRD
+
+This PRD does not follow BMAD standard structure (only {count}/6 core sections present).
+
+You have options:"
+
+Present MENU OPTIONS below for user selection
+
+### 6. Present MENU OPTIONS (Non-Standard PRDs Only)
+
+**[A] Parity Check** - Analyze gaps and estimate effort to reach BMAD PRD parity
+**[B] Validate As-Is** - Proceed with validation using current structure
+**[C] Exit** - Exit validation and review format findings
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- IF A (Parity Check): Read fully and follow: {altStepFile} (step-v-02b-parity-check.md)
+- IF B (Validate As-Is): Display "Proceeding with validation..." then read fully and follow: {nextStepFile}
+- IF C (Exit): Display format findings summary and exit validation
+- IF Any other: help user respond, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All ## Level 2 headers extracted successfully
+- BMAD core sections checked systematically
+- Format classified correctly based on section count
+- Findings reported to validation report
+- BMAD Standard/Variant PRDs proceed directly to next validation step
+- Non-Standard PRDs pause and present options to user
+- User can choose parity check, validate as-is, or exit
+
+### ❌ SYSTEM FAILURE:
+
+- Not extracting all headers before classification
+- Incorrect format classification
+- Not reporting findings to validation report
+- Not pausing for non-standard PRDs
+- Proceeding without user decision for non-standard formats
+
+**Master Rule:** Format detection determines validation path. Non-standard PRDs require user choice before proceeding.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-02b-parity-check.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-02b-parity-check.md
new file mode 100644
index 0000000..33b6a19
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-02b-parity-check.md
@@ -0,0 +1,206 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-03-density-validation.md'
+prdFile: '{prd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step 2B: Document Parity Check
+
+## STEP GOAL:
+
+Analyze non-standard PRD and identify gaps to achieve BMAD PRD parity, presenting user with options for how to proceed.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring BMAD PRD standards expertise and gap analysis
+- ✅ User brings domain knowledge and PRD context
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on analyzing gaps and estimating parity effort
+- 🚫 FORBIDDEN to perform other validation checks in this step
+- 💬 Approach: Systematic gap analysis with clear recommendations
+- 🚪 This is an optional branch step - user chooses next action
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Analyze each BMAD PRD section for gaps
+- 💾 Append parity analysis to validation report
+- 📖 Present options and await user decision
+- 🚫 FORBIDDEN to proceed without user selection
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Non-standard PRD from step 2, validation report in progress
+- Focus: Parity analysis only - what's missing, what's needed
+- Limits: Don't perform validation checks, don't auto-proceed
+- Dependencies: Step 2 classified PRD as non-standard and user chose parity check
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Analyze Each BMAD PRD Section
+
+For each of the 6 BMAD PRD core sections, analyze:
+
+**Executive Summary:**
+- Does PRD have vision/overview?
+- Is problem statement clear?
+- Are target users identified?
+- Gap: [What's missing or incomplete]
+
+**Success Criteria:**
+- Are measurable goals defined?
+- Is success clearly defined?
+- Gap: [What's missing or incomplete]
+
+**Product Scope:**
+- Is scope clearly defined?
+- Are in-scope items listed?
+- Are out-of-scope items listed?
+- Gap: [What's missing or incomplete]
+
+**User Journeys:**
+- Are user types/personas identified?
+- Are user flows documented?
+- Gap: [What's missing or incomplete]
+
+**Functional Requirements:**
+- Are features/capabilities listed?
+- Are requirements structured?
+- Gap: [What's missing or incomplete]
+
+**Non-Functional Requirements:**
+- Are quality attributes defined?
+- Are performance/security/etc. requirements documented?
+- Gap: [What's missing or incomplete]
+
+### 2. Estimate Effort to Reach Parity
+
+For each missing or incomplete section, estimate:
+
+**Effort Level:**
+- Minimal - Section exists but needs minor enhancements
+- Moderate - Section missing but content exists elsewhere in PRD
+- Significant - Section missing, requires new content creation
+
+**Total Parity Effort:**
+- Based on individual section estimates
+- Classify overall: Quick / Moderate / Substantial effort
+
+### 3. Report Parity Analysis to Validation Report
+
+Append to validation report:
+
+```markdown
+## Parity Analysis (Non-Standard PRD)
+
+### Section-by-Section Gap Analysis
+
+**Executive Summary:**
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Success Criteria:**
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Product Scope:**
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**User Journeys:**
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Functional Requirements:**
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Non-Functional Requirements:**
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+### Overall Parity Assessment
+
+**Overall Effort to Reach BMAD Standard:** [Quick/Moderate/Substantial]
+**Recommendation:** [Brief recommendation based on analysis]
+```
+
+### 4. Present Parity Analysis and Options
+
+Display:
+
+"**Parity Analysis Complete**
+
+Your PRD is missing {count} of 6 core BMAD PRD sections. The overall effort to reach BMAD standard is: **{effort level}**
+
+**Quick Summary:**
+[2-3 sentence summary of key gaps]
+
+**Recommendation:**
+{recommendation from analysis}
+
+**How would you like to proceed?**"
+
+### 5. Present MENU OPTIONS
+
+**[C] Continue Validation** - Proceed with validation using current structure
+**[E] Exit & Review** - Exit validation and review parity report
+**[S] Save & Exit** - Save parity report and exit
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- IF C (Continue): Display "Proceeding with validation..." then read fully and follow: {nextStepFile}
+- IF E (Exit): Display parity summary and exit validation
+- IF S (Save): Confirm saved, display summary, exit
+- IF Any other: help user respond, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All 6 BMAD PRD sections analyzed for gaps
+- Effort estimates provided for each gap
+- Overall parity effort assessed correctly
+- Parity analysis reported to validation report
+- Clear summary presented to user
+- User can choose to continue validation, exit, or save report
+
+### ❌ SYSTEM FAILURE:
+
+- Not analyzing all 6 sections systematically
+- Missing effort estimates
+- Not reporting parity analysis to validation report
+- Auto-proceeding without user decision
+- Unclear recommendations
+
+**Master Rule:** Parity check informs user of gaps and effort, but user decides whether to proceed with validation or address gaps first.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-03-density-validation.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-03-density-validation.md
new file mode 100644
index 0000000..35b7e45
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-03-density-validation.md
@@ -0,0 +1,171 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-04-brief-coverage-validation.md'
+prdFile: '{prd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step 3: Information Density Validation
+
+## STEP GOAL:
+
+Validate PRD meets BMAD information density standards by scanning for conversational filler, wordy phrases, and redundant expressions that violate conciseness principles.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and attention to detail
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on information density anti-patterns
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Systematic scanning and categorization
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Scan PRD for density anti-patterns systematically
+- 💾 Append density findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file, validation report with format findings
+- Focus: Information density validation only
+- Limits: Don't validate other aspects, don't pause for user input
+- Dependencies: Step 2 completed - format classification done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform information density validation on this PRD:
+
+1. Load the PRD file
+2. Scan for the following anti-patterns:
+   - Conversational filler phrases (examples: 'The system will allow users to...', 'It is important to note that...', 'In order to')
+   - Wordy phrases (examples: 'Due to the fact that', 'In the event of', 'For the purpose of')
+   - Redundant phrases (examples: 'Future plans', 'Absolutely essential', 'Past history')
+3. Count violations by category with line numbers
+4. Classify severity: Critical (>10 violations), Warning (5-10), Pass (<5)
+
+Return structured findings with counts and examples."
+
+### 2. Graceful Degradation (if Task tool unavailable)
+
+If Task tool unavailable, perform analysis directly:
+
+**Scan for conversational filler patterns:**
+- "The system will allow users to..."
+- "It is important to note that..."
+- "In order to"
+- "For the purpose of"
+- "With regard to"
+- Count occurrences and note line numbers
+
+**Scan for wordy phrases:**
+- "Due to the fact that" (use "because")
+- "In the event of" (use "if")
+- "At this point in time" (use "now")
+- "In a manner that" (use "how")
+- Count occurrences and note line numbers
+
+**Scan for redundant phrases:**
+- "Future plans" (just "plans")
+- "Past history" (just "history")
+- "Absolutely essential" (just "essential")
+- "Completely finish" (just "finish")
+- Count occurrences and note line numbers
+
+### 3. Classify Severity
+
+**Calculate total violations:**
+- Conversational filler count
+- Wordy phrases count
+- Redundant phrases count
+- Total = sum of all categories
+
+**Determine severity:**
+- **Critical:** Total > 10 violations
+- **Warning:** Total 5-10 violations
+- **Pass:** Total < 5 violations
+
+### 4. Report Density Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Information Density Validation
+
+**Anti-Pattern Violations:**
+
+**Conversational Filler:** {count} occurrences
+[If count > 0, list examples with line numbers]
+
+**Wordy Phrases:** {count} occurrences
+[If count > 0, list examples with line numbers]
+
+**Redundant Phrases:** {count} occurrences
+[If count > 0, list examples with line numbers]
+
+**Total Violations:** {total}
+
+**Severity Assessment:** [Critical/Warning/Pass]
+
+**Recommendation:**
+[If Critical] "PRD requires significant revision to improve information density. Every sentence should carry weight without filler."
+[If Warning] "PRD would benefit from reducing wordiness and eliminating filler phrases."
+[If Pass] "PRD demonstrates good information density with minimal violations."
+```
+
+### 5. Display Progress and Auto-Proceed
+
+Display: "**Information Density Validation Complete**
+
+Severity: {Critical/Warning/Pass}
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-04-brief-coverage-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- PRD scanned for all three anti-pattern categories
+- Violations counted with line numbers
+- Severity classified correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not scanning all anti-pattern categories
+- Missing severity classification
+- Not reporting findings to validation report
+- Pausing for user input (should auto-proceed)
+- Not attempting subprocess architecture
+
+**Master Rule:** Information density validation runs autonomously. Scan, classify, report, auto-proceed. No user interaction needed.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-04-brief-coverage-validation.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-04-brief-coverage-validation.md
new file mode 100644
index 0000000..e1e70af
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-04-brief-coverage-validation.md
@@ -0,0 +1,211 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-05-measurability-validation.md'
+prdFile: '{prd_file_path}'
+productBrief: '{product_brief_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step 4: Product Brief Coverage Validation
+
+## STEP GOAL:
+
+Validate that PRD covers all content from Product Brief (if brief was used as input), mapping brief content to PRD sections and identifying gaps.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and traceability expertise
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on Product Brief coverage (conditional on brief existence)
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Systematic mapping and gap analysis
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check if Product Brief exists in input documents
+- 💬 If no brief: Skip this check and report "N/A - No Product Brief"
+- 🎯 If brief exists: Map brief content to PRD sections
+- 💾 Append coverage findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file, input documents from step 1, validation report
+- Focus: Product Brief coverage only (conditional)
+- Limits: Don't validate other aspects, conditional execution
+- Dependencies: Step 1 completed - input documents loaded
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Check for Product Brief
+
+Check if Product Brief was loaded in step 1's inputDocuments:
+
+**IF no Product Brief found:**
+Append to validation report:
+```markdown
+## Product Brief Coverage
+
+**Status:** N/A - No Product Brief was provided as input
+```
+
+Display: "**Product Brief Coverage: Skipped** (No Product Brief provided)
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile}
+
+**IF Product Brief exists:** Continue to step 2 below
+
+### 2. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform Product Brief coverage validation:
+
+1. Load the Product Brief
+2. Extract key content:
+   - Vision statement
+   - Target users/personas
+   - Problem statement
+   - Key features
+   - Goals/objectives
+   - Differentiators
+   - Constraints
+3. For each item, search PRD for corresponding coverage
+4. Classify coverage: Fully Covered / Partially Covered / Not Found / Intentionally Excluded
+5. Note any gaps with severity: Critical / Moderate / Informational
+
+Return structured coverage map with classifications."
+
+### 3. Graceful Degradation (if Task tool unavailable)
+
+If Task tool unavailable, perform analysis directly:
+
+**Extract from Product Brief:**
+- Vision: What is this product?
+- Users: Who is it for?
+- Problem: What problem does it solve?
+- Features: What are the key capabilities?
+- Goals: What are the success criteria?
+- Differentiators: What makes it unique?
+
+**For each item, search PRD:**
+- Scan Executive Summary for vision
+- Check User Journeys or user personas
+- Look for problem statement
+- Review Functional Requirements for features
+- Check Success Criteria section
+- Search for differentiators
+
+**Classify coverage:**
+- **Fully Covered:** Content present and complete
+- **Partially Covered:** Content present but incomplete
+- **Not Found:** Content missing from PRD
+- **Intentionally Excluded:** Content explicitly out of scope
+
+### 4. Assess Coverage and Severity
+
+**For each gap (Partially Covered or Not Found):**
+- Is this Critical? (Core vision, primary users, main features)
+- Is this Moderate? (Secondary features, some goals)
+- Is this Informational? (Nice-to-have features, minor details)
+
+**Note:** Some exclusions may be intentional (valid scoping decisions)
+
+### 5. Report Coverage Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Product Brief Coverage
+
+**Product Brief:** {brief_file_name}
+
+### Coverage Map
+
+**Vision Statement:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+**Target Users:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+**Problem Statement:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+**Key Features:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: List specific features with severity]
+
+**Goals/Objectives:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+**Differentiators:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+### Coverage Summary
+
+**Overall Coverage:** [percentage or qualitative assessment]
+**Critical Gaps:** [count] [list if any]
+**Moderate Gaps:** [count] [list if any]
+**Informational Gaps:** [count] [list if any]
+
+**Recommendation:**
+[If critical gaps exist] "PRD should be revised to cover critical Product Brief content."
+[If moderate gaps] "Consider addressing moderate gaps for complete coverage."
+[If minimal gaps] "PRD provides good coverage of Product Brief content."
+```
+
+### 6. Display Progress and Auto-Proceed
+
+Display: "**Product Brief Coverage Validation Complete**
+
+Overall Coverage: {assessment}
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-05-measurability-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Checked for Product Brief existence correctly
+- If no brief: Reported "N/A" and skipped gracefully
+- If brief exists: Mapped all key brief content to PRD sections
+- Coverage classified appropriately (Fully/Partially/Not Found/Intentionally Excluded)
+- Severity assessed for gaps (Critical/Moderate/Informational)
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking for brief existence before attempting validation
+- If brief exists: not mapping all key content areas
+- Missing coverage classifications
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Product Brief coverage is conditional - skip if no brief, validate thoroughly if brief exists. Always auto-proceed.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-05-measurability-validation.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-05-measurability-validation.md
new file mode 100644
index 0000000..196f5c7
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-05-measurability-validation.md
@@ -0,0 +1,225 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-06-traceability-validation.md'
+prdFile: '{prd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step 5: Measurability Validation
+
+## STEP GOAL:
+
+Validate that all Functional Requirements (FRs) and Non-Functional Requirements (NFRs) are measurable, testable, and follow proper format without implementation details.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and requirements engineering expertise
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on FR and NFR measurability
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Systematic requirement-by-requirement analysis
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract all FRs and NFRs from PRD
+- 💾 Validate each for measurability and format
+- 📖 Append findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file, validation report
+- Focus: FR and NFR measurability only
+- Limits: Don't validate other aspects, don't pause for user input
+- Dependencies: Steps 2-4 completed - initial validation checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform measurability validation on this PRD:
+
+**Functional Requirements (FRs):**
+1. Extract all FRs from Functional Requirements section
+2. Check each FR for:
+   - '[Actor] can [capability]' format compliance
+   - No subjective adjectives (easy, fast, simple, intuitive, etc.)
+   - No vague quantifiers (multiple, several, some, many, etc.)
+   - No implementation details (technology names, library names, data structures unless capability-relevant)
+3. Document violations with line numbers
+
+**Non-Functional Requirements (NFRs):**
+1. Extract all NFRs from Non-Functional Requirements section
+2. Check each NFR for:
+   - Specific metrics with measurement methods
+   - Template compliance (criterion, metric, measurement method, context)
+   - Context included (why this matters, who it affects)
+3. Document violations with line numbers
+
+Return structured findings with violation counts and examples."
+
+### 2. Graceful Degradation (if Task tool unavailable)
+
+If Task tool unavailable, perform analysis directly:
+
+**Functional Requirements Analysis:**
+
+Extract all FRs and check each for:
+
+**Format compliance:**
+- Does it follow "[Actor] can [capability]" pattern?
+- Is actor clearly defined?
+- Is capability actionable and testable?
+
+**No subjective adjectives:**
+- Scan for: easy, fast, simple, intuitive, user-friendly, responsive, quick, efficient (without metrics)
+- Note line numbers
+
+**No vague quantifiers:**
+- Scan for: multiple, several, some, many, few, various, number of
+- Note line numbers
+
+**No implementation details:**
+- Scan for: React, Vue, Angular, PostgreSQL, MongoDB, AWS, Docker, Kubernetes, Redux, etc.
+- Unless capability-relevant (e.g., "API consumers can access...")
+- Note line numbers
+
+**Non-Functional Requirements Analysis:**
+
+Extract all NFRs and check each for:
+
+**Specific metrics:**
+- Is there a measurable criterion? (e.g., "response time < 200ms", not "fast response")
+- Can this be measured or tested?
+
+**Template compliance:**
+- Criterion defined?
+- Metric specified?
+- Measurement method included?
+- Context provided?
+
+### 3. Tally Violations
+
+**FR Violations:**
+- Format violations: count
+- Subjective adjectives: count
+- Vague quantifiers: count
+- Implementation leakage: count
+- Total FR violations: sum
+
+**NFR Violations:**
+- Missing metrics: count
+- Incomplete template: count
+- Missing context: count
+- Total NFR violations: sum
+
+**Total violations:** FR violations + NFR violations
+
+### 4. Report Measurability Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Measurability Validation
+
+### Functional Requirements
+
+**Total FRs Analyzed:** {count}
+
+**Format Violations:** {count}
+[If violations exist, list examples with line numbers]
+
+**Subjective Adjectives Found:** {count}
+[If found, list examples with line numbers]
+
+**Vague Quantifiers Found:** {count}
+[If found, list examples with line numbers]
+
+**Implementation Leakage:** {count}
+[If found, list examples with line numbers]
+
+**FR Violations Total:** {total}
+
+### Non-Functional Requirements
+
+**Total NFRs Analyzed:** {count}
+
+**Missing Metrics:** {count}
+[If missing, list examples with line numbers]
+
+**Incomplete Template:** {count}
+[If incomplete, list examples with line numbers]
+
+**Missing Context:** {count}
+[If missing, list examples with line numbers]
+
+**NFR Violations Total:** {total}
+
+### Overall Assessment
+
+**Total Requirements:** {FRs + NFRs}
+**Total Violations:** {FR violations + NFR violations}
+
+**Severity:** [Critical if >10 violations, Warning if 5-10, Pass if <5]
+
+**Recommendation:**
+[If Critical] "Many requirements are not measurable or testable. Requirements must be revised to be testable for downstream work."
+[If Warning] "Some requirements need refinement for measurability. Focus on violating requirements above."
+[If Pass] "Requirements demonstrate good measurability with minimal issues."
+```
+
+### 5. Display Progress and Auto-Proceed
+
+Display: "**Measurability Validation Complete**
+
+Total Violations: {count} ({severity})
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-06-traceability-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All FRs extracted and analyzed for measurability
+- All NFRs extracted and analyzed for measurability
+- Violations documented with line numbers
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not analyzing all FRs and NFRs
+- Missing line numbers for violations
+- Not reporting findings to validation report
+- Not assessing severity
+- Not auto-proceeding
+
+**Master Rule:** Requirements must be testable to be useful. Validate every requirement for measurability, document violations, auto-proceed.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-06-traceability-validation.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-06-traceability-validation.md
new file mode 100644
index 0000000..67fb284
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-06-traceability-validation.md
@@ -0,0 +1,214 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-07-implementation-leakage-validation.md'
+prdFile: '{prd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step 6: Traceability Validation
+
+## STEP GOAL:
+
+Validate the traceability chain from Executive Summary → Success Criteria → User Journeys → Functional Requirements is intact, ensuring every requirement traces back to a user need or business objective.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and traceability matrix expertise
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on traceability chain validation
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Systematic chain validation and orphan detection
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Build and validate traceability matrix
+- 💾 Identify broken chains and orphan requirements
+- 📖 Append findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file, validation report
+- Focus: Traceability chain validation only
+- Limits: Don't validate other aspects, don't pause for user input
+- Dependencies: Steps 2-5 completed - initial validations done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform traceability validation on this PRD:
+
+1. Extract content from Executive Summary (vision, goals)
+2. Extract Success Criteria
+3. Extract User Journeys (user types, flows, outcomes)
+4. Extract Functional Requirements (FRs)
+5. Extract Product Scope (in-scope items)
+
+**Validate chains:**
+- Executive Summary → Success Criteria: Does vision align with defined success?
+- Success Criteria → User Journeys: Are success criteria supported by user journeys?
+- User Journeys → Functional Requirements: Does each FR trace back to a user journey?
+- Scope → FRs: Do MVP scope FRs align with in-scope items?
+
+**Identify orphans:**
+- FRs not traceable to any user journey or business objective
+- Success criteria not supported by user journeys
+- User journeys without supporting FRs
+
+Build traceability matrix and identify broken chains and orphan FRs.
+
+Return structured findings with chain status and orphan list."
+
+### 2. Graceful Degradation (if Task tool unavailable)
+
+If Task tool unavailable, perform analysis directly:
+
+**Step 1: Extract key elements**
+- Executive Summary: Note vision, goals, objectives
+- Success Criteria: List all criteria
+- User Journeys: List user types and their flows
+- Functional Requirements: List all FRs
+- Product Scope: List in-scope items
+
+**Step 2: Validate Executive Summary → Success Criteria**
+- Does Executive Summary mention the success dimensions?
+- Are Success Criteria aligned with vision?
+- Note any misalignment
+
+**Step 3: Validate Success Criteria → User Journeys**
+- For each success criterion, is there a user journey that achieves it?
+- Note success criteria without supporting journeys
+
+**Step 4: Validate User Journeys → FRs**
+- For each user journey/flow, are there FRs that enable it?
+- List FRs with no clear user journey origin
+- Note orphan FRs (requirements without traceable source)
+
+**Step 5: Validate Scope → FR Alignment**
+- Does MVP scope align with essential FRs?
+- Are in-scope items supported by FRs?
+- Note misalignments
+
+**Step 6: Build traceability matrix**
+- Map each FR to its source (journey or business objective)
+- Note orphan FRs
+- Identify broken chains
+
+### 3. Tally Traceability Issues
+
+**Broken chains:**
+- Executive Summary → Success Criteria gaps: count
+- Success Criteria → User Journeys gaps: count
+- User Journeys → FRs gaps: count
+- Scope → FR misalignments: count
+
+**Orphan elements:**
+- Orphan FRs (no traceable source): count
+- Unsupported success criteria: count
+- User journeys without FRs: count
+
+**Total issues:** Sum of all broken chains and orphans
+
+### 4. Report Traceability Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Traceability Validation
+
+### Chain Validation
+
+**Executive Summary → Success Criteria:** [Intact/Gaps Identified]
+{If gaps: List specific misalignments}
+
+**Success Criteria → User Journeys:** [Intact/Gaps Identified]
+{If gaps: List unsupported success criteria}
+
+**User Journeys → Functional Requirements:** [Intact/Gaps Identified]
+{If gaps: List journeys without supporting FRs}
+
+**Scope → FR Alignment:** [Intact/Misaligned]
+{If misaligned: List specific issues}
+
+### Orphan Elements
+
+**Orphan Functional Requirements:** {count}
+{List orphan FRs with numbers}
+
+**Unsupported Success Criteria:** {count}
+{List unsupported criteria}
+
+**User Journeys Without FRs:** {count}
+{List journeys without FRs}
+
+### Traceability Matrix
+
+{Summary table showing traceability coverage}
+
+**Total Traceability Issues:** {total}
+
+**Severity:** [Critical if orphan FRs exist, Warning if gaps, Pass if intact]
+
+**Recommendation:**
+[If Critical] "Orphan requirements exist - every FR must trace back to a user need or business objective."
+[If Warning] "Traceability gaps identified - strengthen chains to ensure all requirements are justified."
+[If Pass] "Traceability chain is intact - all requirements trace to user needs or business objectives."
+```
+
+### 5. Display Progress and Auto-Proceed
+
+Display: "**Traceability Validation Complete**
+
+Total Issues: {count} ({severity})
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-07-implementation-leakage-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All traceability chains validated systematically
+- Orphan FRs identified with numbers
+- Broken chains documented
+- Traceability matrix built
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not validating all traceability chains
+- Missing orphan FR detection
+- Not building traceability matrix
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Every requirement should trace to a user need or business objective. Orphan FRs indicate broken traceability that must be fixed.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-07-implementation-leakage-validation.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-07-implementation-leakage-validation.md
new file mode 100644
index 0000000..a4f740c
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-07-implementation-leakage-validation.md
@@ -0,0 +1,202 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-08-domain-compliance-validation.md'
+prdFile: '{prd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step 7: Implementation Leakage Validation
+
+## STEP GOAL:
+
+Ensure Functional Requirements and Non-Functional Requirements don't include implementation details - they should specify WHAT, not HOW.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and separation of concerns expertise
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on implementation leakage detection
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Systematic scanning for technology and implementation terms
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Scan FRs and NFRs for implementation terms
+- 💾 Distinguish capability-relevant vs leakage
+- 📖 Append findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file, validation report
+- Focus: Implementation leakage detection only
+- Limits: Don't validate other aspects, don't pause for user input
+- Dependencies: Steps 2-6 completed - initial validations done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform implementation leakage validation on this PRD:
+
+**Scan for:**
+1. Technology names (React, Vue, Angular, PostgreSQL, MongoDB, AWS, GCP, Azure, Docker, Kubernetes, etc.)
+2. Library names (Redux, axios, lodash, Express, Django, Rails, Spring, etc.)
+3. Data structures (JSON, XML, CSV) unless relevant to capability
+4. Architecture patterns (MVC, microservices, serverless) unless business requirement
+5. Protocol names (HTTP, REST, GraphQL, WebSockets) - check if capability-relevant
+
+**For each term found:**
+- Is this capability-relevant? (e.g., 'API consumers can access...' - API is capability)
+- Or is this implementation detail? (e.g., 'React component for...' - implementation)
+
+Document violations with line numbers and explanation.
+
+Return structured findings with leakage counts and examples."
+
+### 2. Graceful Degradation (if Task tool unavailable)
+
+If Task tool unavailable, perform analysis directly:
+
+**Implementation leakage terms to scan for:**
+
+**Frontend Frameworks:**
+React, Vue, Angular, Svelte, Solid, Next.js, Nuxt, etc.
+
+**Backend Frameworks:**
+Express, Django, Rails, Spring, Laravel, FastAPI, etc.
+
+**Databases:**
+PostgreSQL, MySQL, MongoDB, Redis, DynamoDB, Cassandra, etc.
+
+**Cloud Platforms:**
+AWS, GCP, Azure, Cloudflare, Vercel, Netlify, etc.
+
+**Infrastructure:**
+Docker, Kubernetes, Terraform, Ansible, etc.
+
+**Libraries:**
+Redux, Zustand, axios, fetch, lodash, jQuery, etc.
+
+**Data Formats:**
+JSON, XML, YAML, CSV (unless capability-relevant)
+
+**For each term found in FRs/NFRs:**
+- Determine if it's capability-relevant or implementation leakage
+- Example: "API consumers can access data via REST endpoints" - API/REST is capability
+- Example: "React components fetch data using Redux" - implementation leakage
+
+**Count violations and note line numbers**
+
+### 3. Tally Implementation Leakage
+
+**By category:**
+- Frontend framework leakage: count
+- Backend framework leakage: count
+- Database leakage: count
+- Cloud platform leakage: count
+- Infrastructure leakage: count
+- Library leakage: count
+- Other implementation details: count
+
+**Total implementation leakage violations:** sum
+
+### 4. Report Implementation Leakage Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Implementation Leakage Validation
+
+### Leakage by Category
+
+**Frontend Frameworks:** {count} violations
+{If violations, list examples with line numbers}
+
+**Backend Frameworks:** {count} violations
+{If violations, list examples with line numbers}
+
+**Databases:** {count} violations
+{If violations, list examples with line numbers}
+
+**Cloud Platforms:** {count} violations
+{If violations, list examples with line numbers}
+
+**Infrastructure:** {count} violations
+{If violations, list examples with line numbers}
+
+**Libraries:** {count} violations
+{If violations, list examples with line numbers}
+
+**Other Implementation Details:** {count} violations
+{If violations, list examples with line numbers}
+
+### Summary
+
+**Total Implementation Leakage Violations:** {total}
+
+**Severity:** [Critical if >5 violations, Warning if 2-5, Pass if <2]
+
+**Recommendation:**
+[If Critical] "Extensive implementation leakage found. Requirements specify HOW instead of WHAT. Remove all implementation details - these belong in architecture, not PRD."
+[If Warning] "Some implementation leakage detected. Review violations and remove implementation details from requirements."
+[If Pass] "No significant implementation leakage found. Requirements properly specify WHAT without HOW."
+
+**Note:** API consumers, GraphQL (when required), and other capability-relevant terms are acceptable when they describe WHAT the system must do, not HOW to build it.
+```
+
+### 5. Display Progress and Auto-Proceed
+
+Display: "**Implementation Leakage Validation Complete**
+
+Total Violations: {count} ({severity})
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-08-domain-compliance-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Scanned FRs and NFRs for all implementation term categories
+- Distinguished capability-relevant from implementation leakage
+- Violations documented with line numbers and explanations
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not scanning all implementation term categories
+- Not distinguishing capability-relevant from leakage
+- Missing line numbers for violations
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Requirements specify WHAT, not HOW. Implementation details belong in architecture documents, not PRDs.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-08-domain-compliance-validation.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-08-domain-compliance-validation.md
new file mode 100644
index 0000000..c9f48e9
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-08-domain-compliance-validation.md
@@ -0,0 +1,240 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-09-project-type-validation.md'
+prdFile: '{prd_file_path}'
+prdFrontmatter: '{prd_frontmatter}'
+validationReportPath: '{validation_report_path}'
+domainComplexityData: '../data/domain-complexity.csv'
+---
+
+# Step 8: Domain Compliance Validation
+
+## STEP GOAL:
+
+Validate domain-specific requirements are present for high-complexity domains (Healthcare, Fintech, GovTech, etc.), ensuring regulatory and compliance requirements are properly documented.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring domain expertise and compliance knowledge
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on domain-specific compliance requirements
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Conditional validation based on domain classification
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check classification.domain from PRD frontmatter
+- 💬 If low complexity (general): Skip detailed checks
+- 🎯 If high complexity: Validate required special sections
+- 💾 Append compliance findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file with frontmatter classification, validation report
+- Focus: Domain compliance only (conditional on domain complexity)
+- Limits: Don't validate other aspects, conditional execution
+- Dependencies: Steps 2-7 completed - format and requirements validation done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Domain Complexity Data
+
+Load and read the complete file at:
+`{domainComplexityData}` (../data/domain-complexity.csv)
+
+This CSV contains:
+- Domain classifications and complexity levels (high/medium/low)
+- Required special sections for each domain
+- Key concerns and requirements for regulated industries
+
+Internalize this data - it drives which domains require special compliance sections.
+
+### 2. Extract Domain Classification
+
+From PRD frontmatter, extract:
+- `classification.domain` - what domain is this PRD for?
+
+**If no domain classification found:**
+Treat as "general" (low complexity) and proceed to step 4
+
+### 2. Determine Domain Complexity
+
+**Low complexity domains (skip detailed checks):**
+- General
+- Consumer apps (standard e-commerce, social, productivity)
+- Content websites
+- Business tools (standard)
+
+**High complexity domains (require special sections):**
+- Healthcare / Healthtech
+- Fintech / Financial services
+- GovTech / Public sector
+- EdTech (educational records, accredited courses)
+- Legal tech
+- Other regulated domains
+
+### 3. For High-Complexity Domains: Validate Required Special Sections
+
+**Attempt subprocess validation:**
+
+"Perform domain compliance validation for {domain}:
+
+Based on {domain} requirements, check PRD for:
+
+**Healthcare:**
+- Clinical Requirements section
+- Regulatory Pathway (FDA, HIPAA, etc.)
+- Safety Measures
+- HIPAA Compliance (data privacy, security)
+- Patient safety considerations
+
+**Fintech:**
+- Compliance Matrix (SOC2, PCI-DSS, GDPR, etc.)
+- Security Architecture
+- Audit Requirements
+- Fraud Prevention measures
+- Financial transaction handling
+
+**GovTech:**
+- Accessibility Standards (WCAG 2.1 AA, Section 508)
+- Procurement Compliance
+- Security Clearance requirements
+- Data residency requirements
+
+**Other regulated domains:**
+- Check for domain-specific regulatory sections
+- Compliance requirements
+- Special considerations
+
+For each required section:
+- Is it present in PRD?
+- Is it adequately documented?
+- Note any gaps
+
+Return compliance matrix with presence/adequacy assessment."
+
+**Graceful degradation (if no Task tool):**
+- Manually check for required sections based on domain
+- List present sections and missing sections
+- Assess adequacy of documentation
+
+### 5. For Low-Complexity Domains: Skip Detailed Checks
+
+Append to validation report:
+```markdown
+## Domain Compliance Validation
+
+**Domain:** {domain}
+**Complexity:** Low (general/standard)
+**Assessment:** N/A - No special domain compliance requirements
+
+**Note:** This PRD is for a standard domain without regulatory compliance requirements.
+```
+
+Display: "**Domain Compliance Validation Skipped**
+
+Domain: {domain} (low complexity)
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile}
+
+### 6. Report Compliance Findings (High-Complexity Domains)
+
+Append to validation report:
+
+```markdown
+## Domain Compliance Validation
+
+**Domain:** {domain}
+**Complexity:** High (regulated)
+
+### Required Special Sections
+
+**{Section 1 Name}:** [Present/Missing/Adequate]
+{If missing or inadequate: Note specific gaps}
+
+**{Section 2 Name}:** [Present/Missing/Adequate]
+{If missing or inadequate: Note specific gaps}
+
+[Continue for all required sections]
+
+### Compliance Matrix
+
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| {Requirement 1} | [Met/Partial/Missing] | {Notes} |
+| {Requirement 2} | [Met/Partial/Missing] | {Notes} |
+[... continue for all requirements]
+
+### Summary
+
+**Required Sections Present:** {count}/{total}
+**Compliance Gaps:** {count}
+
+**Severity:** [Critical if missing regulatory sections, Warning if incomplete, Pass if complete]
+
+**Recommendation:**
+[If Critical] "PRD is missing required domain-specific compliance sections. These are essential for {domain} products."
+[If Warning] "Some domain compliance sections are incomplete. Strengthen documentation for full compliance."
+[If Pass] "All required domain compliance sections are present and adequately documented."
+```
+
+### 7. Display Progress and Auto-Proceed
+
+Display: "**Domain Compliance Validation Complete**
+
+Domain: {domain} ({complexity})
+Compliance Status: {status}
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-09-project-type-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Domain classification extracted correctly
+- Complexity assessed appropriately
+- Low complexity domains: Skipped with clear "N/A" documentation
+- High complexity domains: All required sections checked
+- Compliance matrix built with status for each requirement
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking domain classification before proceeding
+- Performing detailed checks on low complexity domains
+- For high complexity: missing required section checks
+- Not building compliance matrix
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Domain compliance is conditional. High-complexity domains require special sections - low complexity domains skip these checks.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-09-project-type-validation.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-09-project-type-validation.md
new file mode 100644
index 0000000..f9343b9
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-09-project-type-validation.md
@@ -0,0 +1,260 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-10-smart-validation.md'
+prdFile: '{prd_file_path}'
+prdFrontmatter: '{prd_frontmatter}'
+validationReportPath: '{validation_report_path}'
+projectTypesData: '../data/project-types.csv'
+---
+
+# Step 9: Project-Type Compliance Validation
+
+## STEP GOAL:
+
+Validate project-type specific requirements are properly documented - different project types (api_backend, web_app, mobile_app, etc.) have different required and excluded sections.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring project type expertise and architectural knowledge
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on project-type compliance
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Validate required sections present, excluded sections absent
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check classification.projectType from PRD frontmatter
+- 🎯 Validate required sections for that project type are present
+- 🎯 Validate excluded sections for that project type are absent
+- 💾 Append compliance findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file with frontmatter classification, validation report
+- Focus: Project-type compliance only
+- Limits: Don't validate other aspects, don't pause for user input
+- Dependencies: Steps 2-8 completed - domain and requirements validation done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Project Types Data
+
+Load and read the complete file at:
+`{projectTypesData}` (../data/project-types.csv)
+
+This CSV contains:
+- Detection signals for each project type
+- Required sections for each project type
+- Skip/excluded sections for each project type
+- Innovation signals
+
+Internalize this data - it drives what sections must be present or absent for each project type.
+
+### 2. Extract Project Type Classification
+
+From PRD frontmatter, extract:
+- `classification.projectType` - what type of project is this?
+
+**Common project types:**
+- api_backend
+- web_app
+- mobile_app
+- desktop_app
+- data_pipeline
+- ml_system
+- library_sdk
+- infrastructure
+- other
+
+**If no projectType classification found:**
+Assume "web_app" (most common) and note in findings
+
+### 3. Determine Required and Excluded Sections from CSV Data
+
+**From loaded project-types.csv data, for this project type:**
+
+**Required sections:** (from required_sections column)
+These MUST be present in the PRD
+
+**Skip sections:** (from skip_sections column)
+These MUST NOT be present in the PRD
+
+**Example mappings from CSV:**
+- api_backend: Required=[endpoint_specs, auth_model, data_schemas], Skip=[ux_ui, visual_design]
+- mobile_app: Required=[platform_reqs, device_permissions, offline_mode], Skip=[desktop_features, cli_commands]
+- cli_tool: Required=[command_structure, output_formats, config_schema], Skip=[visual_design, ux_principles, touch_interactions]
+- etc.
+
+### 4. Validate Against CSV-Based Requirements
+
+**Based on project type, determine:**
+
+**api_backend:**
+- Required: Endpoint Specs, Auth Model, Data Schemas, API Versioning
+- Excluded: UX/UI sections, mobile-specific sections
+
+**web_app:**
+- Required: User Journeys, UX/UI Requirements, Responsive Design
+- Excluded: None typically
+
+**mobile_app:**
+- Required: Mobile UX, Platform specifics (iOS/Android), Offline mode
+- Excluded: Desktop-specific sections
+
+**desktop_app:**
+- Required: Desktop UX, Platform specifics (Windows/Mac/Linux)
+- Excluded: Mobile-specific sections
+
+**data_pipeline:**
+- Required: Data Sources, Data Transformation, Data Sinks, Error Handling
+- Excluded: UX/UI sections
+
+**ml_system:**
+- Required: Model Requirements, Training Data, Inference Requirements, Model Performance
+- Excluded: UX/UI sections (unless ML UI)
+
+**library_sdk:**
+- Required: API Surface, Usage Examples, Integration Guide
+- Excluded: UX/UI sections, deployment sections
+
+**infrastructure:**
+- Required: Infrastructure Components, Deployment, Monitoring, Scaling
+- Excluded: Feature requirements (this is infrastructure, not product)
+
+### 4. Attempt Sub-Process Validation
+
+"Perform project-type compliance validation for {projectType}:
+
+**Check that required sections are present:**
+{List required sections for this project type}
+For each: Is it present in PRD? Is it adequately documented?
+
+**Check that excluded sections are absent:**
+{List excluded sections for this project type}
+For each: Is it absent from PRD? (Should not be present)
+
+Build compliance table showing:
+- Required sections: [Present/Missing/Incomplete]
+- Excluded sections: [Absent/Present] (Present = violation)
+
+Return compliance table with findings."
+
+**Graceful degradation (if no Task tool):**
+- Manually check PRD for required sections
+- Manually check PRD for excluded sections
+- Build compliance table
+
+### 5. Build Compliance Table
+
+**Required sections check:**
+- For each required section: Present / Missing / Incomplete
+- Count: Required sections present vs total required
+
+**Excluded sections check:**
+- For each excluded section: Absent / Present (violation)
+- Count: Excluded sections present (violations)
+
+**Total compliance score:**
+- Required: {present}/{total}
+- Excluded violations: {count}
+
+### 6. Report Project-Type Compliance Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Project-Type Compliance Validation
+
+**Project Type:** {projectType}
+
+### Required Sections
+
+**{Section 1}:** [Present/Missing/Incomplete]
+{If missing or incomplete: Note specific gaps}
+
+**{Section 2}:** [Present/Missing/Incomplete]
+{If missing or incomplete: Note specific gaps}
+
+[Continue for all required sections]
+
+### Excluded Sections (Should Not Be Present)
+
+**{Section 1}:** [Absent/Present] ✓
+{If present: This section should not be present for {projectType}}
+
+**{Section 2}:** [Absent/Present] ✓
+{If present: This section should not be present for {projectType}}
+
+[Continue for all excluded sections]
+
+### Compliance Summary
+
+**Required Sections:** {present}/{total} present
+**Excluded Sections Present:** {violations} (should be 0)
+**Compliance Score:** {percentage}%
+
+**Severity:** [Critical if required sections missing, Warning if incomplete, Pass if complete]
+
+**Recommendation:**
+[If Critical] "PRD is missing required sections for {projectType}. Add missing sections to properly specify this type of project."
+[If Warning] "Some required sections for {projectType} are incomplete. Strengthen documentation."
+[If Pass] "All required sections for {projectType} are present. No excluded sections found."
+```
+
+### 7. Display Progress and Auto-Proceed
+
+Display: "**Project-Type Compliance Validation Complete**
+
+Project Type: {projectType}
+Compliance: {score}%
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-10-smart-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Project type extracted correctly (or default assumed)
+- Required sections validated for presence and completeness
+- Excluded sections validated for absence
+- Compliance table built with status for all sections
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking project type before proceeding
+- Missing required section checks
+- Missing excluded section checks
+- Not building compliance table
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Different project types have different requirements. API PRDs don't need UX sections - validate accordingly.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-10-smart-validation.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-10-smart-validation.md
new file mode 100644
index 0000000..52f5cbb
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-10-smart-validation.md
@@ -0,0 +1,206 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-11-holistic-quality-validation.md'
+prdFile: '{prd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step 10: SMART Requirements Validation
+
+## STEP GOAL:
+
+Validate Functional Requirements meet SMART quality criteria (Specific, Measurable, Attainable, Relevant, Traceable), ensuring high-quality requirements.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring requirements engineering expertise and quality assessment
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on FR quality assessment using SMART framework
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Score each FR on SMART criteria (1-5 scale)
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract all FRs from PRD
+- 🎯 Score each FR on SMART criteria (Specific, Measurable, Attainable, Relevant, Traceable)
+- 💾 Flag FRs with score < 3 in any category
+- 📖 Append scoring table and suggestions to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: PRD file, validation report
+- Focus: FR quality assessment only using SMART framework
+- Limits: Don't validate NFRs or other aspects, don't pause for user input
+- Dependencies: Steps 2-9 completed - comprehensive validation checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Extract All Functional Requirements
+
+From the PRD's Functional Requirements section, extract:
+- All FRs with their FR numbers (FR-001, FR-002, etc.)
+- Count total FRs
+
+### 2. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform SMART requirements validation on these Functional Requirements:
+
+{List all FRs}
+
+**For each FR, score on SMART criteria (1-5 scale):**
+
+**Specific (1-5):**
+- 5: Clear, unambiguous, well-defined
+- 3: Somewhat clear but could be more specific
+- 1: Vague, ambiguous, unclear
+
+**Measurable (1-5):**
+- 5: Quantifiable metrics, testable
+- 3: Partially measurable
+- 1: Not measurable, subjective
+
+**Attainable (1-5):**
+- 5: Realistic, achievable with constraints
+- 3: Probably achievable but uncertain
+- 1: Unrealistic, technically infeasible
+
+**Relevant (1-5):**
+- 5: Clearly aligned with user needs and business objectives
+- 3: Somewhat relevant but connection unclear
+- 1: Not relevant, doesn't align with goals
+
+**Traceable (1-5):**
+- 5: Clearly traces to user journey or business objective
+- 3: Partially traceable
+- 1: Orphan requirement, no clear source
+
+**For each FR with score < 3 in any category:**
+- Provide specific improvement suggestions
+
+Return scoring table with all FR scores and improvement suggestions for low-scoring FRs."
+
+**Graceful degradation (if no Task tool):**
+- Manually score each FR on SMART criteria
+- Note FRs with low scores
+- Provide improvement suggestions
+
+### 3. Build Scoring Table
+
+For each FR:
+- FR number
+- Specific score (1-5)
+- Measurable score (1-5)
+- Attainable score (1-5)
+- Relevant score (1-5)
+- Traceable score (1-5)
+- Average score
+- Flag if any category < 3
+
+**Calculate overall FR quality:**
+- Percentage of FRs with all scores ≥ 3
+- Percentage of FRs with all scores ≥ 4
+- Average score across all FRs and categories
+
+### 4. Report SMART Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## SMART Requirements Validation
+
+**Total Functional Requirements:** {count}
+
+### Scoring Summary
+
+**All scores ≥ 3:** {percentage}% ({count}/{total})
+**All scores ≥ 4:** {percentage}% ({count}/{total})
+**Overall Average Score:** {average}/5.0
+
+### Scoring Table
+
+| FR # | Specific | Measurable | Attainable | Relevant | Traceable | Average | Flag |
+|------|----------|------------|------------|----------|-----------|--------|------|
+| FR-001 | {s1} | {m1} | {a1} | {r1} | {t1} | {avg1} | {X if any <3} |
+| FR-002 | {s2} | {m2} | {a2} | {r2} | {t2} | {avg2} | {X if any <3} |
+[Continue for all FRs]
+
+**Legend:** 1=Poor, 3=Acceptable, 5=Excellent
+**Flag:** X = Score < 3 in one or more categories
+
+### Improvement Suggestions
+
+**Low-Scoring FRs:**
+
+**FR-{number}:** {specific suggestion for improvement}
+[For each FR with score < 3 in any category]
+
+### Overall Assessment
+
+**Severity:** [Critical if >30% flagged FRs, Warning if 10-30%, Pass if <10%]
+
+**Recommendation:**
+[If Critical] "Many FRs have quality issues. Revise flagged FRs using SMART framework to improve clarity and testability."
+[If Warning] "Some FRs would benefit from SMART refinement. Focus on flagged requirements above."
+[If Pass] "Functional Requirements demonstrate good SMART quality overall."
+```
+
+### 5. Display Progress and Auto-Proceed
+
+Display: "**SMART Requirements Validation Complete**
+
+FR Quality: {percentage}% with acceptable scores ({severity})
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-11-holistic-quality-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All FRs extracted from PRD
+- Each FR scored on all 5 SMART criteria (1-5 scale)
+- FRs with scores < 3 flagged for improvement
+- Improvement suggestions provided for low-scoring FRs
+- Scoring table built with all FR scores
+- Overall quality assessment calculated
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not scoring all FRs on all SMART criteria
+- Missing improvement suggestions for low-scoring FRs
+- Not building scoring table
+- Not calculating overall quality metrics
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** FRs should be high-quality, not just present. SMART framework provides objective quality measure.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-11-holistic-quality-validation.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-11-holistic-quality-validation.md
new file mode 100644
index 0000000..a559e40
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-11-holistic-quality-validation.md
@@ -0,0 +1,261 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-12-completeness-validation.md'
+prdFile: '{prd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step 11: Holistic Quality Assessment
+
+## STEP GOAL:
+
+Assess the PRD as a cohesive, compelling document - evaluating document flow, dual audience effectiveness (humans and LLMs), BMAD PRD principles compliance, and overall quality rating.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and document quality expertise
+- ✅ This step runs autonomously - no user input needed
+- ✅ Uses Advanced Elicitation for multi-perspective evaluation
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on holistic document quality assessment
+- 🚫 FORBIDDEN to validate individual components (done in previous steps)
+- 💬 Approach: Multi-perspective evaluation using Advanced Elicitation
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Use Advanced Elicitation for multi-perspective assessment
+- 🎯 Evaluate document flow, dual audience, BMAD principles
+- 💾 Append comprehensive assessment to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete PRD file, validation report with findings from steps 1-10
+- Focus: Holistic quality - the WHOLE document
+- Limits: Don't re-validate individual components, don't pause for user input
+- Dependencies: Steps 1-10 completed - all systematic checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process with Advanced Elicitation
+
+**Try to use Task tool to spawn a subprocess using Advanced Elicitation:**
+
+"Perform holistic quality assessment on this PRD using multi-perspective evaluation:
+
+**Advanced Elicitation workflow:**
+Invoke the `bmad-advanced-elicitation` skill
+
+**Evaluate the PRD from these perspectives:**
+
+**1. Document Flow & Coherence:**
+- Read entire PRD
+- Evaluate narrative flow - does it tell a cohesive story?
+- Check transitions between sections
+- Assess consistency - is it coherent throughout?
+- Evaluate readability - is it clear and well-organized?
+
+**2. Dual Audience Effectiveness:**
+
+**For Humans:**
+- Executive-friendly: Can executives understand vision and goals quickly?
+- Developer clarity: Do developers have clear requirements to build from?
+- Designer clarity: Do designers understand user needs and flows?
+- Stakeholder decision-making: Can stakeholders make informed decisions?
+
+**For LLMs:**
+- Machine-readable structure: Is the PRD structured for LLM consumption?
+- UX readiness: Can an LLM generate UX designs from this?
+- Architecture readiness: Can an LLM generate architecture from this?
+- Epic/Story readiness: Can an LLM break down into epics and stories?
+
+**3. BMAD PRD Principles Compliance:**
+- Information density: Every sentence carries weight?
+- Measurability: Requirements testable?
+- Traceability: Requirements trace to sources?
+- Domain awareness: Domain-specific considerations included?
+- Zero anti-patterns: No filler or wordiness?
+- Dual audience: Works for both humans and LLMs?
+- Markdown format: Proper structure and formatting?
+
+**4. Overall Quality Rating:**
+Rate the PRD on 5-point scale:
+- Excellent (5/5): Exemplary, ready for production use
+- Good (4/5): Strong with minor improvements needed
+- Adequate (3/5): Acceptable but needs refinement
+- Needs Work (2/5): Significant gaps or issues
+- Problematic (1/5): Major flaws, needs substantial revision
+
+**5. Top 3 Improvements:**
+Identify the 3 most impactful improvements to make this a great PRD
+
+Return comprehensive assessment with all perspectives, rating, and top 3 improvements."
+
+**Graceful degradation (if no Task tool or Advanced Elicitation unavailable):**
+- Perform holistic assessment directly in current context
+- Read complete PRD
+- Evaluate document flow, coherence, transitions
+- Assess dual audience effectiveness
+- Check BMAD principles compliance
+- Assign overall quality rating
+- Identify top 3 improvements
+
+### 2. Synthesize Assessment
+
+**Compile findings from multi-perspective evaluation:**
+
+**Document Flow & Coherence:**
+- Overall assessment: [Excellent/Good/Adequate/Needs Work/Problematic]
+- Key strengths: [list]
+- Key weaknesses: [list]
+
+**Dual Audience Effectiveness:**
+- For Humans: [assessment]
+- For LLMs: [assessment]
+- Overall dual audience score: [1-5]
+
+**BMAD Principles Compliance:**
+- Principles met: [count]/7
+- Principles with issues: [list]
+
+**Overall Quality Rating:** [1-5 with label]
+
+**Top 3 Improvements:**
+1. [Improvement 1]
+2. [Improvement 2]
+3. [Improvement 3]
+
+### 3. Report Holistic Quality Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Holistic Quality Assessment
+
+### Document Flow & Coherence
+
+**Assessment:** [Excellent/Good/Adequate/Needs Work/Problematic]
+
+**Strengths:**
+{List key strengths}
+
+**Areas for Improvement:**
+{List key weaknesses}
+
+### Dual Audience Effectiveness
+
+**For Humans:**
+- Executive-friendly: [assessment]
+- Developer clarity: [assessment]
+- Designer clarity: [assessment]
+- Stakeholder decision-making: [assessment]
+
+**For LLMs:**
+- Machine-readable structure: [assessment]
+- UX readiness: [assessment]
+- Architecture readiness: [assessment]
+- Epic/Story readiness: [assessment]
+
+**Dual Audience Score:** {score}/5
+
+### BMAD PRD Principles Compliance
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| Information Density | [Met/Partial/Not Met] | {notes} |
+| Measurability | [Met/Partial/Not Met] | {notes} |
+| Traceability | [Met/Partial/Not Met] | {notes} |
+| Domain Awareness | [Met/Partial/Not Met] | {notes} |
+| Zero Anti-Patterns | [Met/Partial/Not Met] | {notes} |
+| Dual Audience | [Met/Partial/Not Met] | {notes} |
+| Markdown Format | [Met/Partial/Not Met] | {notes} |
+
+**Principles Met:** {count}/7
+
+### Overall Quality Rating
+
+**Rating:** {rating}/5 - {label}
+
+**Scale:**
+- 5/5 - Excellent: Exemplary, ready for production use
+- 4/5 - Good: Strong with minor improvements needed
+- 3/5 - Adequate: Acceptable but needs refinement
+- 2/5 - Needs Work: Significant gaps or issues
+- 1/5 - Problematic: Major flaws, needs substantial revision
+
+### Top 3 Improvements
+
+1. **{Improvement 1}**
+   {Brief explanation of why and how}
+
+2. **{Improvement 2}**
+   {Brief explanation of why and how}
+
+3. **{Improvement 3}**
+   {Brief explanation of why and how}
+
+### Summary
+
+**This PRD is:** {one-sentence overall assessment}
+
+**To make it great:** Focus on the top 3 improvements above.
+```
+
+### 4. Display Progress and Auto-Proceed
+
+Display: "**Holistic Quality Assessment Complete**
+
+Overall Rating: {rating}/5 - {label}
+
+**Proceeding to final validation checks...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-12-completeness-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Advanced Elicitation used for multi-perspective evaluation (or graceful degradation)
+- Document flow & coherence assessed
+- Dual audience effectiveness evaluated (humans and LLMs)
+- BMAD PRD principles compliance checked
+- Overall quality rating assigned (1-5 scale)
+- Top 3 improvements identified
+- Comprehensive assessment reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not using Advanced Elicitation for multi-perspective evaluation
+- Missing document flow assessment
+- Missing dual audience evaluation
+- Not checking all BMAD principles
+- Not assigning overall quality rating
+- Missing top 3 improvements
+- Not reporting comprehensive assessment to validation report
+- Not auto-proceeding
+
+**Master Rule:** This evaluates the WHOLE document, not just components. Answers "Is this a good PRD?" and "What would make it great?"
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-12-completeness-validation.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-12-completeness-validation.md
new file mode 100644
index 0000000..90065e1
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-12-completeness-validation.md
@@ -0,0 +1,239 @@
+---
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-13-report-complete.md'
+prdFile: '{prd_file_path}'
+prdFrontmatter: '{prd_frontmatter}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step 12: Completeness Validation
+
+## STEP GOAL:
+
+Final comprehensive completeness check - validate no template variables remain, each section has required content, section-specific completeness, and frontmatter is properly populated.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring attention to detail and completeness verification
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on completeness verification
+- 🚫 FORBIDDEN to validate quality (done in step 11) or other aspects
+- 💬 Approach: Systematic checklist-style verification
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check template completeness (no variables remaining)
+- 🎯 Validate content completeness (each section has required content)
+- 🎯 Validate section-specific completeness
+- 🎯 Validate frontmatter completeness
+- 💾 Append completeness matrix to validation report
+- 📖 Display "Proceeding to final step..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete PRD file, frontmatter, validation report
+- Focus: Completeness verification only (final gate)
+- Limits: Don't assess quality, don't pause for user input
+- Dependencies: Steps 1-11 completed - all validation checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform completeness validation on this PRD - final gate check:
+
+**1. Template Completeness:**
+- Scan PRD for any remaining template variables
+- Look for: {variable}, {{variable}}, {placeholder}, [placeholder], etc.
+- List any found with line numbers
+
+**2. Content Completeness:**
+- Executive Summary: Has vision statement? ({key content})
+- Success Criteria: All criteria measurable? ({metrics present})
+- Product Scope: In-scope and out-of-scope defined? ({both present})
+- User Journeys: User types identified? ({users listed})
+- Functional Requirements: FRs listed with proper format? ({FRs present})
+- Non-Functional Requirements: NFRs with metrics? ({NFRs present})
+
+For each section: Is required content present? (Yes/No/Partial)
+
+**3. Section-Specific Completeness:**
+- Success Criteria: Each has specific measurement method?
+- User Journeys: Cover all user types?
+- Functional Requirements: Cover MVP scope?
+- Non-Functional Requirements: Each has specific criteria?
+
+**4. Frontmatter Completeness:**
+- stepsCompleted: Populated?
+- classification: Present (domain, projectType)?
+- inputDocuments: Tracked?
+- date: Present?
+
+Return completeness matrix with status for each check."
+
+**Graceful degradation (if no Task tool):**
+- Manually scan for template variables
+- Manually check each section for required content
+- Manually verify frontmatter fields
+- Build completeness matrix
+
+### 2. Build Completeness Matrix
+
+**Template Completeness:**
+- Template variables found: count
+- List if any found
+
+**Content Completeness by Section:**
+- Executive Summary: Complete / Incomplete / Missing
+- Success Criteria: Complete / Incomplete / Missing
+- Product Scope: Complete / Incomplete / Missing
+- User Journeys: Complete / Incomplete / Missing
+- Functional Requirements: Complete / Incomplete / Missing
+- Non-Functional Requirements: Complete / Incomplete / Missing
+- Other sections: [List completeness]
+
+**Section-Specific Completeness:**
+- Success criteria measurable: All / Some / None
+- Journeys cover all users: Yes / Partial / No
+- FRs cover MVP scope: Yes / Partial / No
+- NFRs have specific criteria: All / Some / None
+
+**Frontmatter Completeness:**
+- stepsCompleted: Present / Missing
+- classification: Present / Missing
+- inputDocuments: Present / Missing
+- date: Present / Missing
+
+**Overall completeness:**
+- Sections complete: X/Y
+- Critical gaps: [list if any]
+
+### 3. Report Completeness Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Completeness Validation
+
+### Template Completeness
+
+**Template Variables Found:** {count}
+{If count > 0, list variables with line numbers}
+{If count = 0, note: No template variables remaining ✓}
+
+### Content Completeness by Section
+
+**Executive Summary:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Success Criteria:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Product Scope:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**User Journeys:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Functional Requirements:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Non-Functional Requirements:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+### Section-Specific Completeness
+
+**Success Criteria Measurability:** [All/Some/None] measurable
+{If Some or None, note which criteria lack metrics}
+
+**User Journeys Coverage:** [Yes/Partial/No] - covers all user types
+{If Partial or No, note missing user types}
+
+**FRs Cover MVP Scope:** [Yes/Partial/No]
+{If Partial or No, note scope gaps}
+
+**NFRs Have Specific Criteria:** [All/Some/None]
+{If Some or None, note which NFRs lack specificity}
+
+### Frontmatter Completeness
+
+**stepsCompleted:** [Present/Missing]
+**classification:** [Present/Missing]
+**inputDocuments:** [Present/Missing]
+**date:** [Present/Missing]
+
+**Frontmatter Completeness:** {complete_fields}/4
+
+### Completeness Summary
+
+**Overall Completeness:** {percentage}% ({complete_sections}/{total_sections})
+
+**Critical Gaps:** [count] [list if any]
+**Minor Gaps:** [count] [list if any]
+
+**Severity:** [Critical if template variables exist or critical sections missing, Warning if minor gaps, Pass if complete]
+
+**Recommendation:**
+[If Critical] "PRD has completeness gaps that must be addressed before use. Fix template variables and complete missing sections."
+[If Warning] "PRD has minor completeness gaps. Address minor gaps for complete documentation."
+[If Pass] "PRD is complete with all required sections and content present."
+```
+
+### 4. Display Progress and Auto-Proceed
+
+Display: "**Completeness Validation Complete**
+
+Overall Completeness: {percentage}% ({severity})
+
+**Proceeding to final step...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-13-report-complete.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Scanned for template variables systematically
+- Validated each section for required content
+- Validated section-specific completeness (measurability, coverage, scope)
+- Validated frontmatter completeness
+- Completeness matrix built with all checks
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to final step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not scanning for template variables
+- Missing section-specific completeness checks
+- Not validating frontmatter
+- Not building completeness matrix
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Final gate to ensure document is complete before presenting findings. Template variables or critical gaps must be fixed.
diff --git a/.claude/skills/bmad-validate-prd/steps-v/step-v-13-report-complete.md b/.claude/skills/bmad-validate-prd/steps-v/step-v-13-report-complete.md
new file mode 100644
index 0000000..946b570
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/steps-v/step-v-13-report-complete.md
@@ -0,0 +1,229 @@
+---
+# File references (ONLY variables used in this step)
+validationReportPath: '{validation_report_path}'
+prdFile: '{prd_file_path}'
+---
+
+# Step 13: Validation Report Complete
+
+## STEP GOAL:
+
+Finalize validation report, summarize all findings from steps 1-12, present summary to user conversationally, and offer actionable next steps.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring synthesis and summary expertise
+- ✅ This is the FINAL step - requires user interaction
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on summarizing findings and presenting options
+- 🚫 FORBIDDEN to perform additional validation
+- 💬 Approach: Conversational summary with clear next steps
+- 🚪 This is the final step - no next step after this
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load complete validation report
+- 🎯 Summarize all findings from steps 1-12
+- 🎯 Update report frontmatter with final status
+- 💬 Present summary to user conversationally
+- 💬 Offer menu options for next actions
+- 🚫 FORBIDDEN to proceed without user selection
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete validation report with findings from all validation steps
+- Focus: Summary and presentation only (no new validation)
+- Limits: Don't add new findings, just synthesize existing
+- Dependencies: Steps 1-12 completed - all validation checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Complete Validation Report
+
+Read the entire validation report from {validationReportPath}
+
+Extract all findings from:
+- Format Detection (Step 2)
+- Parity Analysis (Step 2B, if applicable)
+- Information Density (Step 3)
+- Product Brief Coverage (Step 4)
+- Measurability (Step 5)
+- Traceability (Step 6)
+- Implementation Leakage (Step 7)
+- Domain Compliance (Step 8)
+- Project-Type Compliance (Step 9)
+- SMART Requirements (Step 10)
+- Holistic Quality (Step 11)
+- Completeness (Step 12)
+
+### 2. Update Report Frontmatter with Final Status
+
+Update validation report frontmatter:
+
+```yaml
+---
+validationTarget: '{prd_path}'
+validationDate: '{current_date}'
+inputDocuments: [list of documents]
+validationStepsCompleted: ['step-v-01-discovery', 'step-v-02-format-detection', 'step-v-03-density-validation', 'step-v-04-brief-coverage-validation', 'step-v-05-measurability-validation', 'step-v-06-traceability-validation', 'step-v-07-implementation-leakage-validation', 'step-v-08-domain-compliance-validation', 'step-v-09-project-type-validation', 'step-v-10-smart-validation', 'step-v-11-holistic-quality-validation', 'step-v-12-completeness-validation']
+validationStatus: COMPLETE
+holisticQualityRating: '{rating from step 11}'
+overallStatus: '{Pass/Warning/Critical based on all findings}'
+---
+```
+
+### 3. Create Summary of Findings
+
+**Overall Status:**
+- Determine from all validation findings
+- **Pass:** All critical checks pass, minor warnings acceptable
+- **Warning:** Some issues found but PRD is usable
+- **Critical:** Major issues that prevent PRD from being fit for purpose
+
+**Quick Results Table:**
+- Format: [classification]
+- Information Density: [severity]
+- Measurability: [severity]
+- Traceability: [severity]
+- Implementation Leakage: [severity]
+- Domain Compliance: [status]
+- Project-Type Compliance: [compliance score]
+- SMART Quality: [percentage]
+- Holistic Quality: [rating/5]
+- Completeness: [percentage]
+
+**Critical Issues:** List from all validation steps
+**Warnings:** List from all validation steps
+**Strengths:** List positives from all validation steps
+
+**Holistic Quality Rating:** From step 11
+**Top 3 Improvements:** From step 11
+
+**Recommendation:** Based on overall status
+
+### 4. Present Summary to User Conversationally
+
+Display:
+
+"**✓ PRD Validation Complete**
+
+**Overall Status:** {Pass/Warning/Critical}
+
+**Quick Results:**
+{Present quick results table with key findings}
+
+**Critical Issues:** {count or "None"}
+{If any, list briefly}
+
+**Warnings:** {count or "None"}
+{If any, list briefly}
+
+**Strengths:**
+{List key strengths}
+
+**Holistic Quality:** {rating}/5 - {label}
+
+**Top 3 Improvements:**
+1. {Improvement 1}
+2. {Improvement 2}
+3. {Improvement 3}
+
+**Recommendation:**
+{Based on overall status:
+- Pass: "PRD is in good shape. Address minor improvements to make it great."
+- Warning: "PRD is usable but has issues that should be addressed. Review warnings and improve where needed."
+- Critical: "PRD has significant issues that should be fixed before use. Focus on critical issues above."}
+
+**What would you like to do next?**"
+
+### 5. Present MENU OPTIONS
+
+Display:
+
+**[R] Review Detailed Findings** - Walk through validation report section by section
+**[E] Use Edit Workflow** - Use validation report with Edit workflow for systematic improvements
+**[F] Fix Simpler Items** - Immediate fixes for simple issues (anti-patterns, leakage, missing headers)
+**[X] Exit** - Exit and Suggest Next Steps.
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- **IF R (Review Detailed Findings):**
+  - Walk through validation report section by section
+  - Present findings from each validation step
+  - Allow user to ask questions
+  - After review, return to menu
+
+- **IF E (Use Edit Workflow):**
+  - Explain: "The Edit workflow can use this validation report to systematically address issues. Edit mode will guide you through discovering what to edit, reviewing the PRD, and applying targeted improvements."
+  - Offer: "Would you like to launch Edit mode now? It will help you fix validation findings systematically."
+  - If yes: Invoke the `bmad-edit-prd` skill, passing the validation report path as context
+  - If no: Return to menu
+
+- **IF F (Fix Simpler Items):**
+  - Offer immediate fixes for:
+    - Template variables (fill in with appropriate content)
+    - Conversational filler (remove wordy phrases)
+    - Implementation leakage (remove technology names from FRs/NFRs)
+    - Missing section headers (add ## headers)
+  - Ask: "Which simple fixes would you like me to make?"
+  - If user specifies fixes, make them and update validation report
+  - Return to menu
+
+- **IF X (Exit):**
+  - Display: "**Validation Report Saved:** {validationReportPath}"
+  - Display: "**Summary:** {overall status} - {recommendation}"
+  - PRD Validation complete. Invoke the `bmad-help` skill.
+
+- **IF Any other:** Help user, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Complete validation report loaded successfully
+- All findings from steps 1-12 summarized
+- Report frontmatter updated with final status
+- Overall status determined correctly (Pass/Warning/Critical)
+- Quick results table presented
+- Critical issues, warnings, and strengths listed
+- Holistic quality rating included
+- Top 3 improvements presented
+- Clear recommendation provided
+- Menu options presented with clear explanations
+- User can review findings, get help, or exit
+
+### ❌ SYSTEM FAILURE:
+
+- Not loading complete validation report
+- Missing summary of findings
+- Not updating report frontmatter
+- Not determining overall status
+- Missing menu options
+- Unclear next steps
+
+**Master Rule:** User needs clear summary and actionable next steps. Edit workflow is best for complex issues; immediate fixes available for simpler ones.
diff --git a/.claude/skills/bmad-validate-prd/workflow.md b/.claude/skills/bmad-validate-prd/workflow.md
new file mode 100644
index 0000000..4fe8fce
--- /dev/null
+++ b/.claude/skills/bmad-validate-prd/workflow.md
@@ -0,0 +1,61 @@
+---
+main_config: '{project-root}/_bmad/bmm/config.yaml'
+validateWorkflow: './steps-v/step-v-01-discovery.md'
+---
+
+# PRD Validate Workflow
+
+**Goal:** Validate existing PRDs against BMAD standards through comprehensive review.
+
+**Your Role:** Validation Architect and Quality Assurance Specialist.
+
+You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
+- **Append-Only Building**: Build documents by appending content as directed to the output file
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
+6. **LOAD NEXT**: When directed, read fully and follow the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## Activation
+
+1. Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
+✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`.
+
+2. Route to Validate Workflow
+
+"**Validate Mode: Validating an existing PRD against BMAD standards.**"
+
+Then read fully and follow: `{validateWorkflow}` (steps-v/step-v-01-discovery.md)
diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md
new file mode 100644
index 0000000..70fbdb8
--- /dev/null
+++ b/.claude/skills/openspec-apply-change/SKILL.md
@@ -0,0 +1,156 @@
+---
+name: openspec-apply-change
+description: Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - `contextFiles`: artifact ID -> array of concrete file paths (varies by schema - could be proposal/specs/design/tasks or spec/tests/implementation/docs)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using openspec-continue-change
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read every file path listed under `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! Ready to archive this change.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md
new file mode 100644
index 0000000..12e2f70
--- /dev/null
+++ b/.claude/skills/openspec-archive-change/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: openspec-archive-change
+description: Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name. If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Use **AskUserQuestion tool** to confirm user wants to proceed
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Whether specs were synced (if applicable)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs (or "No delta specs" or "Sync skipped")
+
+All artifacts complete. All tasks complete.
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use openspec-sync-specs approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.claude/skills/openspec-explore/SKILL.md b/.claude/skills/openspec-explore/SKILL.md
new file mode 100644
index 0000000..836820e
--- /dev/null
+++ b/.claude/skills/openspec-explore/SKILL.md
@@ -0,0 +1,288 @@
+---
+name: openspec-explore
+description: Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create a proposal?"
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | `openspec/specs/<capability>/spec.md` |
+    | Requirement changed        | `openspec/specs/<capability>/spec.md` |
+    | Design decision made       | `design.md`                  |
+    | Scope changed              | `proposal.md`                |
+    | New work identified        | `tasks.md`                   |
+    | Assumption invalidated     | Relevant artifact              |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Handling Different Entry Points
+
+**User brings a vague idea:**
+```
+User: I'm thinking about adding real-time collaboration
+
+You: Real-time collab is a big space. Let me think about this...
+
+      COLLABORATION SPECTRUM
+      ════════════════════════════════════════════
+
+      Awareness          Coordination         Sync
+          │                   │                 │
+          ▼                   ▼                 ▼
+      ┌────────┐         ┌────────┐        ┌────────┐
+      │Presence│         │Cursors │        │  CRDT  │
+      │  "3    │         │ Multi  │        │Conflict│
+      │online" │         │ select │        │  free  │
+      └────────┘         └────────┘        └────────┘
+          │                   │                 │
+       trivial            moderate           complex
+
+      Where's your head at?
+```
+
+**User brings a specific problem:**
+```
+User: The auth system is a mess
+
+You: [reads codebase]
+
+     ┌─────────────────────────────────────────────┐
+     │              CURRENT AUTH FLOW              │
+     └─────────────────────────────────────────────┘
+                        │
+          ┌─────────────┼─────────────┐
+          ▼             ▼             ▼
+     ┌─────────┐  ┌─────────┐  ┌─────────┐
+     │ Google  │  │  GitHub │  │  Email  │
+     │  OAuth  │  │  OAuth  │  │  Magic  │
+     └────┬────┘  └────┬────┘  └────┬────┘
+          │             │             │
+          └─────────────┼─────────────┘
+                        ▼
+                  ┌───────────┐
+                  │  Session  │
+                  └─────┬─────┘
+                        │
+                        ▼
+                  ┌───────────┐
+                  │   Perms   │
+                  └───────────┘
+
+     I see three tangles. Which one's burning?
+```
+
+**User is stuck mid-implementation:**
+```
+User: /opsx:explore add-auth-system
+      The OAuth integration is more complex than expected
+
+You: [reads change artifacts]
+
+     You're on task 4: "Implement OAuth flow"
+
+     Let me trace what's involved...
+
+     [draws diagram, explores options, suggests paths]
+
+     Want to update the design to reflect this?
+     Or add a spike task to investigate?
+```
+
+**User wants to compare options:**
+```
+User: Should we use Postgres or SQLite?
+
+You: Generic answer is boring. What's the context?
+
+User: A CLI tool that tracks local dev environments
+
+You: That changes everything.
+
+     ┌─────────────────────────────────────────────────┐
+     │          CLI TOOL DATA STORAGE                  │
+     └─────────────────────────────────────────────────┘
+
+     Key constraints:
+     • No daemon running
+     • Must work offline
+     • Single user
+
+                  SQLite          Postgres
+     Deployment   embedded ✓      needs server ✗
+     Offline      yes ✓           no ✗
+     Single file  yes ✓           no ✗
+
+     SQLite. Not even close.
+
+     Unless... is there a sync component?
+```
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When it feels like things are crystallizing, you might summarize:
+
+```
+## What We Figured Out
+
+**The problem**: [crystallized understanding]
+
+**The approach**: [if one emerged]
+
+**Open questions**: [if any remain]
+
+**Next steps** (if ready):
+- Create a change proposal
+- Keep exploring: just keep talking
+```
+
+But this summary is optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.claude/skills/openspec-propose/SKILL.md b/.claude/skills/openspec-propose/SKILL.md
new file mode 100644
index 0000000..4b7e204
--- /dev/null
+++ b/.claude/skills/openspec-propose/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: openspec-propose
+description: Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
+license: MIT
+compatibility: Requires openspec CLI.
+metadata:
+  author: openspec
+  version: "1.0"
+  generatedBy: "1.3.1"
+---
+
+Propose a new change - create the change and generate all artifacts in one step.
+
+I'll create a change with artifacts:
+- proposal.md (what & why)
+- design.md (how)
+- tasks.md (implementation steps)
+
+When ready to implement, run /opsx:apply
+
+---
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/` with `.openspec.yaml`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` or ask me to implement to start working on the tasks."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use `template` as the structure for your output file - fill in its sections
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.claude/skills/verify/SKILL.md b/.claude/skills/verify/SKILL.md
new file mode 100644
index 0000000..a7b3db4
--- /dev/null
+++ b/.claude/skills/verify/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: verify
+description: Run format check, build, and tests to verify changes are correct. Use before committing or after significant edits.
+---
+
+Run full verification for Tiny-LLM:
+
+## Steps
+
+1. **Format check** — Verify C++/CUDA formatting:
+   ```bash
+   find . -type f \( -name '*.cpp' -o -name '*.h' -o -name '*.cu' -o -name '*.cuh' \) \
+     ! -path './build/*' | xargs clang-format-18 --dry-run --Werror
+   ```
+
+2. **Build** — Compile in release mode:
+   ```bash
+   mkdir -p build && cd build && \
+   cmake .. -DCMAKE_BUILD_TYPE=Release -DCUDAHOSTCXX=/usr/bin/g++-10 && \
+   make -j$(nproc)
+   ```
+
+3. **Test** — Run all tests:
+   ```bash
+   cd build && ctest --output-on-failure --timeout 300
+   ```
+
+## On Failure
+
+- If format check fails: run `clang-format-18 -i <files>` to fix
+- If build fails: check GCC version (must be GCC 10 for CUDA)
+- If tests fail: run specific test with `./tiny_llm_tests --gtest_filter="TestSuite.TestName"`
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..9975495
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,38 @@
+# Copilot instructions for Tiny-LLM
+
+## Project mode
+
+Tiny-LLM is in a final hardening phase. Prefer cleanup, alignment, and reliability work over new roadmap expansion.
+
+## Required workflow
+
+- Use OpenSpec for non-trivial work.
+- Read the active change in `openspec/changes/<name>/` before editing.
+- Treat `openspec/specs/` as the current behavior contract.
+- Keep changes scoped to the active task instead of mixing unrelated cleanup.
+
+## Repository-specific rules
+
+- Do not reintroduce legacy `/specs` guidance.
+- Prefer deleting or merging stale docs over adding parallel explanations.
+- Keep README, Pages, changelog surfaces, and GitHub metadata aligned.
+- Do not assume CI will auto-format or auto-commit fixes.
+- Use `gh` for repository metadata updates.
+
+## Engineering constraints
+
+- C++17 and CUDA C++17
+- `Result<T>` for fallible operations
+- RAII for ownership
+- `clang-format-18`
+- `clangd` + `compile_commands.json` as the default language-intelligence baseline
+
+## Validation commands
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
+cmake --build build -j$(nproc)
+ctest --test-dir build --output-on-failure --timeout 300
+```
+
+`nvcc` must be available for configure/build/test to succeed.
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 0000000..4722adf
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "llvm-vs-code-extensions.vscode-clangd",
+    "ms-vscode.cmake-tools"
+  ]
+}
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..1e8761b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,56 @@
+# CLAUDE.md
+
+This file defines the preferred Claude/agent operating style for Tiny-LLM.
+
+## Mission
+
+Help finish the repository cleanly:
+
+- tighten OpenSpec compliance
+- reduce document and workflow drift
+- keep the CUDA/C++ core reliable
+- make the public project surface sharper
+- avoid speculative expansion
+
+## Default workflow
+
+1. Read the active OpenSpec change and current specs first.
+2. If the task is non-trivial and no change exists, propose one before broad edits.
+3. Implement from `tasks.md` in dependency order.
+4. Run a review pass after major workstreams.
+5. Archive the change when code, docs, and specs agree.
+
+## Editing posture
+
+- Prefer precise rewrites over layering more generic text.
+- Prefer deleting stale material over “keeping both”.
+- Keep CI non-mutating.
+- Keep user-facing claims conservative and verifiable.
+- Respect existing user changes in the working tree; reconcile before overwriting.
+
+## Tooling posture
+
+- Use `gh` for repository metadata work.
+- Treat `clangd` + `compile_commands.json` as the canonical LSP baseline.
+- Keep MCP/plugin usage optional and narrow.
+- Prefer long single-session execution over `/fleet`.
+
+## Technical reminders
+
+- C++17 + CUDA C++17
+- `Result<T>` instead of control-flow exceptions
+- RAII for resource ownership
+- `clang-format-18`
+- `nvcc` required for real configure/build/test passes
+
+## Validation commands
+
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
+cmake --build build -j$(nproc)
+ctest --test-dir build --output-on-failure --timeout 300
+```
+
+## Local overrides
+
+Personal overrides may live in `CLAUDE.local.md`, but that file is local-only and must stay untracked.
diff --git a/openspec/MIGRATION.md b/openspec/MIGRATION.md
new file mode 100644
index 0000000..fa7333d
--- /dev/null
+++ b/openspec/MIGRATION.md
@@ -0,0 +1,113 @@
+# OpenSpec Migration Record
+
+> **Date:** 2026-04-23
+> **From:** Custom SDD structure (`specs/`)
+> **To:** OpenSpec framework (`openspec/`)
+
+---
+
+## Migration Summary
+
+Successfully migrated the Tiny-LLM project from a custom Spec-Driven Development structure to the OpenSpec framework.
+
+---
+
+## What Changed
+
+### Directory Structure
+
+| Before | After | Status |
+|--------|-------|--------|
+| `specs/product/*.md` | `openspec/specs/<capability>/spec.md` | Migrated |
+| `specs/rfc/*.md` | `openspec/changes/archive/*/` | Archived |
+| `specs/api/*.yaml` | `openspec/schemas/api/` | Moved |
+| `specs/testing/*.feature` | Embedded in `spec.md` | Integrated |
+| `specs/db/*.dbml` | `openspec/schemas/db/` | Moved |
+| `specs/` | *Deleted* | Removed |
+
+### Workflow Commands
+
+| Before | After |
+|--------|-------|
+| Manual spec-first workflow | `/opsx:propose` |
+| No structured implementation tracking | `/opsx:apply` |
+| No archival process | `/opsx:archive` |
+
+---
+
+## Artifacts Created
+
+### OpenSpec Configuration
+- `openspec/config.yaml` - Project configuration with C++/CUDA context
+
+### Capability Specs
+- `openspec/specs/inference-engine/spec.md` - Main inference engine specification
+
+### Archived Changes
+- `openspec/changes/archive/core-architecture/` - Original architecture RFC
+- `openspec/changes/archive/initial-implementation/` - Original implementation tasks
+
+### Supplementary Schemas
+- `openspec/schemas/api/inference-engine.yaml` - API contracts
+- `openspec/schemas/db/schema-v1.dbml` - Data models
+
+### Claude Code Integration
+- `.claude/skills/openspec-propose/SKILL.md`
+- `.claude/skills/openspec-apply-change/SKILL.md`
+- `.claude/skills/openspec-archive-change/SKILL.md`
+- `.claude/skills/openspec-explore/SKILL.md`
+
+---
+
+## Key Improvements
+
+1. **Structured Workflow**: OpenSpec provides clear proposal → apply → archive cycle
+2. **Delta Specs**: Changes are tracked with ADDED/MODIFIED/REMOVED sections
+3. **AI Integration**: Built-in slash commands for Claude Code and 27+ other tools
+4. **RFC 2119 Keywords**: Mandatory requirements use SHALL/MUST, recommended use SHOULD
+5. **Scenario-based Testing**: Each requirement has test scenarios in GIVEN/WHEN/THEN format
+
+---
+
+## Verification
+
+```bash
+# Validate all specs
+openspec validate --all
+# Result: 1 passed, 0 failed
+
+# List capability specs
+openspec list --specs
+# Result: inference-engine
+
+# Check OpenSpec version
+openspec --version
+# Result: 1.3.1
+```
+
+---
+
+## Post-Migration Tasks
+
+- [x] Install OpenSpec CLI (`npm install -g @fission-ai/openspec@latest`)
+- [x] Initialize OpenSpec structure (`openspec init --tools claude`)
+- [x] Create `openspec/config.yaml`
+- [x] Migrate product specs to `openspec/specs/`
+- [x] Archive RFCs to `openspec/changes/archive/`
+- [x] Move API and DB schemas to `openspec/schemas/`
+- [x] Update `AGENTS.md` with OpenSpec workflow
+- [x] Delete original `specs/` directory
+- [x] Validate all specs pass
+
+---
+
+## Future Development
+
+For all future development, use the OpenSpec workflow:
+
+1. **New Features**: `/opsx:propose <change-name>`
+2. **Implementation**: `/opsx:apply <change-name>`
+3. **Completion**: `/opsx:archive <change-name>`
+4. **Exploration**: `/opsx:explore`
+
+See `AGENTS.md` for detailed workflow documentation.
diff --git a/openspec/changes/archive/core-architecture/design.md b/openspec/changes/archive/core-architecture/design.md
new file mode 100644
index 0000000..9f72b6f
--- /dev/null
+++ b/openspec/changes/archive/core-architecture/design.md
@@ -0,0 +1,148 @@
+# Core Architecture Design
+
+> **Version:** 2.0.1 | **Date:** 2026-04-16 | **Status:** Implemented
+
+## Context
+
+This document captures the architectural decisions made during the initial implementation of the Tiny-LLM inference engine.
+
+---
+
+## Goals / Non-Goals
+
+**Goals:**
+- Memory efficiency through INT8 weight quantization (~50% reduction)
+- Bandwidth optimization via register-level dequantization
+- Computational efficiency through warp shuffle and shared memory tiling
+- Extensibility for different model architectures
+
+**Non-Goals:**
+- Multi-GPU support (single GPU only)
+- Training capabilities (inference only)
+- Full precision fallback (W8A16 only)
+
+---
+
+## Decisions
+
+### Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      Host (CPU)                             │
+│  Model Loader  │  Tokenizer  │  Generation Controller      │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      Device (GPU)                           │
+│                                                             │
+│  ┌─ Memory ─────────────────────────────────────────────┐  │
+│  │  Weight Memory (INT8+Scales)  │  KV Cache  │  Activ  │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ┌─ Kernels ────────────────────────────────────────────┐  │
+│  │  W8A16 MatMul  │  Attention  │  RMSNorm  │  Elemwise │  │
+│  └───────────────────────────────────────────────────────┘  │
+│                                                             │
+│  ┌─ Transformer ────────────────────────────────────────┐  │
+│  │  Layer 1  →  Layer 2  →  ...  →  Layer N            │  │
+│  └───────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Core Components
+
+**Model Loader:**
+```cpp
+struct ModelConfig {
+    int vocab_size, hidden_dim, num_layers;
+    int num_heads, num_kv_heads, head_dim;
+    int intermediate_dim, max_seq_len;
+    float rope_theta, rms_norm_eps;
+};
+
+struct QuantizedWeight {
+    int8_t* data;      // INT8 weights
+    half* scales;      // Per-group scales
+    int rows, cols, group_size;
+};
+```
+
+**W8A16 MatMul:**
+- Formula: `output = input @ (weight_int8 * scales)`
+- Optimization: Shared memory tiling (TILE_M × TILE_N × BLOCK_K)
+- Optimization: Warp shuffle reduction
+- Optimization: Register-level dequantization
+
+**KV Cache Manager:**
+```cpp
+Result<int> allocateSequence(int max_len);
+void appendKV(seq_id, layer_idx, k, v, n);  // write-only
+void advanceSeqLen(seq_id, n);              // explicit advance
+void releaseSequence(int seq_id);
+```
+
+### Error Handling Pattern
+
+```cpp
+// CUDA error checking
+#define CUDA_CHECK(call) \
+    do { \
+        cudaError_t err = call; \
+        if (err != cudaSuccess) throw CudaException(err, __FILE__, __LINE__); \
+    } while(0)
+
+// Result type (monadic error handling)
+template<typename T>
+class Result {
+    static Result<T> ok(T value);
+    static Result<T> err(std::string message);
+    bool isOk() const;
+    T& value();
+    const std::string& error() const;
+};
+```
+
+---
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|------------|
+| INT8 precision loss | Validate against FP16 baseline, maintain < 1% error |
+| GPU memory fragmentation | Pre-allocated KV cache pool |
+| CUDA version compatibility | Support CUDA 11.0+ with forward compatibility |
+
+---
+
+## Test Strategy
+
+| Type | Framework | Coverage |
+|------|-----------|----------|
+| Unit Tests | GoogleTest | Concrete examples, edge cases |
+| Property Tests | RapidCheck | General correctness (100+ iterations) |
+| Integration Tests | GoogleTest | End-to-end inference |
+
+---
+
+## File Structure
+
+```
+tiny-llm/
+├── include/tiny_llm/     # Public headers
+│   ├── types.h           # Core types
+│   ├── result.h          # Error handling
+│   ├── cuda_utils.h      # CUDA utilities
+│   ├── kv_cache.h        # KV Cache
+│   ├── transformer.h     # Transformer layer
+│   ├── model_loader.h    # Model loading
+│   └── inference_engine.h
+├── kernels/              # CUDA Kernels
+│   ├── w8a16_matmul.cu
+│   ├── attention.cu
+│   ├── rmsnorm.cu
+│   └── elementwise.cu
+├── src/                  # Implementation
+└── tests/                # Tests
+```
diff --git a/openspec/changes/archive/core-architecture/proposal.md b/openspec/changes/archive/core-architecture/proposal.md
new file mode 100644
index 0000000..44f9d9d
--- /dev/null
+++ b/openspec/changes/archive/core-architecture/proposal.md
@@ -0,0 +1,22 @@
+# Core Architecture
+
+## Why
+
+Establish a lightweight LLM inference engine optimized for CUDA GPUs, focusing on W8A16 quantization for memory efficiency and bandwidth optimization.
+
+## What Changes
+
+### New Capabilities
+- `inference-engine`: Complete W8A16 quantized inference with KV Cache
+
+## Impact
+
+- Defines core system architecture for all future development
+- Establishes CUDA kernel optimization patterns
+- Sets error handling conventions (Result<T> monadic pattern)
+
+---
+
+## Status: Archived
+
+This proposal has been implemented. See `openspec/specs/inference-engine/` for current specifications.
diff --git a/openspec/changes/archive/initial-implementation/proposal.md b/openspec/changes/archive/initial-implementation/proposal.md
new file mode 100644
index 0000000..16592c3
--- /dev/null
+++ b/openspec/changes/archive/initial-implementation/proposal.md
@@ -0,0 +1,22 @@
+# Initial Implementation
+
+## Why
+
+Implement the core Tiny-LLM inference engine with W8A16 quantization and KV Cache for efficient LLM inference on CUDA GPUs.
+
+## What Changes
+
+### New Capabilities
+- `inference-engine`: Complete W8A16 quantized inference engine implementation
+
+## Impact
+
+- Establishes the complete codebase for Tiny-LLM
+- Implements all correctness properties (P1-P9)
+- Provides end-to-end inference capability
+
+---
+
+## Status: Archived
+
+This implementation is complete. See `openspec/specs/inference-engine/` for current specifications and `tasks.md` for completed task details.
diff --git a/openspec/changes/archive/initial-implementation/tasks.md b/openspec/changes/archive/initial-implementation/tasks.md
new file mode 100644
index 0000000..153ef20
--- /dev/null
+++ b/openspec/changes/archive/initial-implementation/tasks.md
@@ -0,0 +1,106 @@
+# Initial Implementation Tasks
+
+> **Version:** 2.0.1 | **Status:** ✅ Complete
+
+---
+
+## Overview
+
+| Phase | Tasks | Status |
+|-------|-------|--------|
+| 1. Infrastructure | 3 | ✅ |
+| 2. Data Types | 2 | ✅ |
+| 3. Model Loading | 5 | ✅ |
+| 4. W8A16 | 4 | ✅ |
+| 5. KV Cache | 3 | ✅ |
+| 6. Attention | 4 | ✅ |
+| 7. Transformer | 3 | ✅ |
+| 8. Inference Engine | 5 | ✅ |
+| 9. Optimization | 3 | ✅ |
+| 10. Integration | 2 | ✅ |
+
+---
+
+## Phase 1: Infrastructure ✅
+
+- [x] 1.1 Directory structure + CMake
+- [x] 1.2 CUDA error handling (CUDA_CHECK, Result<T>)
+- [x] 1.3 Error handling tests
+
+## Phase 2: Data Types ✅
+
+- [x] 2.1 ModelConfig, QuantizedWeight, TransformerWeights
+- [x] 2.2 Property test: Scale dimension consistency (P8)
+
+## Phase 3: Model Loading ✅
+
+- [x] 3.1 GGUF header parsing
+- [x] 3.2 Binary weight loading
+- [x] 3.3 GPU memory transfer
+- [x] 3.4 Property test: Corrupted file (P9)
+- [x] 3.5 Unit tests
+
+## Phase 4: W8A16 ✅
+
+- [x] 4.1 MatMul Kernel (tiling + dequant)
+- [x] 4.2 Warp shuffle optimization
+- [x] 4.3 Property test: Numerical precision (P1)
+- [x] 4.4 Unit tests
+
+## Phase 5: KV Cache ✅
+
+- [x] 5.1 Memory pool + slot management
+- [x] 5.2 allocate/append/release/getCache
+- [x] 5.3 Property test: Invariants (P2)
+
+## Phase 6: Attention ✅
+
+- [x] 6.1 RMSNorm Kernel
+- [x] 6.2 Property test: RMSNorm (P4)
+- [x] 6.3 Attention Kernel + causal masking
+- [x] 6.4 Property test: Causal masking (P3)
+
+## Phase 7: Transformer ✅
+
+- [x] 7.1 TransformerLayer (attention + FFN + residual)
+- [x] 7.2 KV Cache integration
+- [x] 7.3 Property test: Incremental decoding (P5)
+
+## Phase 8: Inference Engine ✅
+
+- [x] 8.1 prefill + decodeStep
+- [x] 8.2 Sampling strategies (greedy/temp/top-k/top-p)
+- [x] 8.3 Property test: Greedy sampling (P6)
+- [x] 8.4 Generation control + statistics
+- [x] 8.5 Property test: Length limit (P7)
+
+## Phase 9: Optimization ✅
+
+- [x] 9.1 Memory coalesced access
+- [x] 9.2 Block configuration optimization
+- [x] 9.3 CUDA streams
+
+## Phase 10: Integration ✅
+
+- [x] 10.1 Test models
+- [x] 10.2 End-to-end tests
+
+---
+
+## Fixed Issues
+
+### v2.0.1 (2026-04-16)
+
+- [x] `test_integration.cu`: Scale dimension calculation error
+- [x] `attention.cu`: Removed unused code
+
+---
+
+## Future Plans
+
+| Priority | Task | Status |
+|----------|------|--------|
+| P1 | Full GGUF runtime | Planned |
+| P2 | Configurable group_size | Planned |
+| P2 | Kernel error checking | Planned |
+| P3 | Paged Attention | Under evaluation |
diff --git a/openspec/changes/normalize-archive-readiness/.openspec.yaml b/openspec/changes/normalize-archive-readiness/.openspec.yaml
new file mode 100644
index 0000000..8b394c6
--- /dev/null
+++ b/openspec/changes/normalize-archive-readiness/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-23
diff --git a/openspec/changes/normalize-archive-readiness/design.md b/openspec/changes/normalize-archive-readiness/design.md
new file mode 100644
index 0000000..bf49971
--- /dev/null
+++ b/openspec/changes/normalize-archive-readiness/design.md
@@ -0,0 +1,127 @@
+## Context
+
+Tiny-LLM is a CUDA/C++ inference engine whose repository recently migrated from a custom `specs/` layout to OpenSpec. The migration created the right core structure, but several high-signal repository surfaces still point in different directions:
+
+- contributor guidance still mixes legacy `specs/` instructions with OpenSpec
+- GitHub Actions are more complex than the project's current maintenance intent and CI currently mutates the branch
+- README, changelog, GitHub Pages, and GitHub metadata are not yet aligned around a focused, archive-ready project story
+- AI-tooling guidance is fragmented across `AGENTS.md`, personal `CLAUDE.local.md`, OpenSpec Claude commands, and missing project-level Copilot/Claude guidance
+- the working tree already contains user edits, so cleanup must be precise rather than destructive-by-default in execution order
+
+This change is cross-cutting: it touches repository governance, documentation architecture, automation, public presentation, and the operator workflow used by AI agents during the project's final hardening phase.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Make OpenSpec the single authoritative planning and change-management spine.
+- Reduce repository drift by removing stale guidance, duplicated docs, and low-value workflow behavior.
+- Redesign public and contributor-facing surfaces so they reflect the actual project state and maintenance goals.
+- Standardize the AI-assisted development model for this repository with a small number of project-specific instruction files.
+- Establish a practical developer tooling baseline for a C++17/CUDA project, including LSP guidance and low-friction hooks.
+- Leave the repository in a cleaner, lower-noise state suitable for final bug-fixing and later low-maintenance archival mode.
+
+**Non-Goals:**
+- Expanding Tiny-LLM into a broader feature roadmap or reviving speculative roadmap items.
+- Introducing heavy new platform dependencies, large MCP/plugin stacks, or complex developer infrastructure.
+- Rewriting stable core CUDA architecture without evidence from the later bug audit.
+- Supporting every AI editor/runtime equally with bespoke configuration if shared guidance is sufficient.
+
+## Decisions
+
+### 1. Use a single umbrella OpenSpec change for repository normalization
+
+This work spans multiple repository surfaces that need to stay coordinated. A single umbrella change keeps proposal, design, specs, and tasks unified while still allowing the implementation to proceed in narrow phases.
+
+**Alternatives considered**
+- **Many small changes**: lower local scope, but higher drift risk and weaker overall architecture control.
+- **Ad hoc edits without a change**: faster initially, but contradicts the stated OpenSpec-first workflow.
+
+### 2. Treat aggressive cleanup as the default content strategy
+
+The user explicitly prefers aggressive cleanup. The implementation will therefore bias toward deleting, merging, or rewriting low-value documents and redundant workflow behavior instead of preserving them for historical completeness.
+
+**Alternatives considered**
+- **Preserve most files and only patch references**: safer short-term, but leaves the repository bloated and internally inconsistent.
+- **Freeze current docs and only add new meta-docs**: increases duplication and does not solve drift.
+
+### 3. Separate repository-governance concerns from inference-engine behavior
+
+This change introduces new governance-oriented capabilities instead of overloading the existing `inference-engine` capability with repository process requirements. Code bug fixing discovered later should primarily align implementation to the existing engine spec unless a genuine behavior change is required.
+
+**Alternatives considered**
+- **Modify `inference-engine` now**: possible, but would mix repository-operating concerns into product behavior and create premature spec churn.
+
+### 4. Make CI non-mutating and reduce automation noise
+
+Validation pipelines should check quality and fail loudly; they should not auto-format files and commit back to the branch. This reduces surprise, avoids noisy workflow loops, and better fits a final-hardening repository.
+
+**Alternatives considered**
+- **Keep auto-format-on-push**: convenient for style drift, but high-noise and risky during stabilization.
+- **Add more automation layers**: likely over-engineering for a project moving toward low maintenance.
+
+### 5. Reframe GitHub Pages and README surfaces around credibility and conversion
+
+The public project surface should do four things well: explain what Tiny-LLM is, show why it matters, establish its implementation maturity, and guide the right next step. Pages should not exist merely as a prettier README mirror.
+
+**Alternatives considered**
+- **Keep the current docs-heavy site mostly intact**: less work, but still under-optimized for attracting and orienting new users.
+- **Remove Pages entirely**: would simplify maintenance, but loses a valuable project showcase and homepage target for GitHub metadata.
+
+### 6. Use a minimal, project-specific AI tooling stack
+
+The canonical project instruction surfaces will be:
+- OpenSpec artifacts
+- `AGENTS.md`
+- project `CLAUDE.md`
+- project-level Copilot instructions
+
+Supplementary tool-specific configuration should only be added when it produces a concrete, repository-specific gain.
+
+**Alternatives considered**
+- **Many parallel instruction files for every tool**: higher maintenance, more drift, weak signal.
+- **No project-level AI guidance**: leaves agents relying on generic behavior and increases repository-specific mistakes.
+
+### 7. Standardize on clangd plus compile_commands.json for LSP
+
+For this C++17/CUDA repository, `clangd` backed by `compile_commands.json` is the most portable baseline across editors and AI tooling ecosystems. This becomes the default recommendation unless a tool requires a thin compatibility layer.
+
+**Alternatives considered**
+- **Tool-specific LSP setups**: more fragmentation and duplicated guidance.
+- **No explicit LSP baseline**: leads to inconsistent indexing and weaker editing assistance.
+
+### 8. Keep MCP optional and narrow
+
+MCP should be used only where it materially improves repository operations over existing built-in tools such as `gh`, GitHub integrations, or local CLI commands. This avoids context bloat and unnecessary runtime complexity.
+
+**Alternatives considered**
+- **Broad MCP adoption**: potentially powerful, but high context and maintenance overhead for limited payoff in this repository.
+
+### 9. Update GitHub metadata only after content surfaces stabilize
+
+Repository description, homepage URL, and topics should be updated with `gh` after README and Pages positioning are finalized so the public metadata points at the correct, polished destination.
+
+**Alternatives considered**
+- **Update metadata first**: creates temporary mismatch between GitHub summary and repo/site content.
+
+## Risks / Trade-offs
+
+- **Dirty working tree conflicts** -> Reconcile user-owned changes first and avoid blanket rewrites in touched files.
+- **Cleanup scope becomes too broad** -> Execute in dependency-aware phases and define explicit completion criteria per workstream.
+- **Accidentally removing useful historical context** -> Preserve only high-signal history through OpenSpec archive, meaningful changelog entries, and curated release notes.
+- **Workflow simplification breaks expected automation** -> Re-validate build, tests, and Pages behavior after each major automation change.
+- **Tooling guidance becomes too generic** -> Keep instructions tied to Tiny-LLM's actual stack and maintenance goal.
+- **GitHub metadata drifts again later** -> Make metadata alignment part of the final closure playbook.
+
+## Migration Plan
+
+1. Reconcile the current dirty repository state and establish the baseline audit.
+2. Normalize OpenSpec and contributor-governance surfaces first so later edits follow one workflow.
+3. Simplify workflows, hooks, and engineering config before relying on them for further cleanup.
+4. Redesign README, changelog policy, Pages content, and GitHub metadata as one public-surface pass.
+5. Standardize AI/tooling guidance and then run the repository-wide bug/drift audit.
+6. Finish with a closure playbook that defines the lightweight future maintenance path.
+
+## Open Questions
+
+- Which existing website/doc pages survive aggressive cleanup versus being merged into fewer, higher-signal entry points?
+- Which GitHub topics best balance discoverability with accuracy for a CUDA/C++ inference engine nearing archival mode?
diff --git a/openspec/changes/normalize-archive-readiness/proposal.md b/openspec/changes/normalize-archive-readiness/proposal.md
new file mode 100644
index 0000000..f7a37c5
--- /dev/null
+++ b/openspec/changes/normalize-archive-readiness/proposal.md
@@ -0,0 +1,30 @@
+## Why
+
+Tiny-LLM has completed a partial migration to OpenSpec, but the repository still behaves like a project with mixed governance models, duplicated documentation layers, and overbuilt automation. Before the project can be finished strongly and moved toward low-maintenance archival mode, its repository structure, contributor workflow, public presentation, and AI-assisted development guidance need to be normalized around a smaller, more coherent operating model.
+
+## What Changes
+
+- Create an OpenSpec-driven cleanup program that governs repository structure, document quality, and archive-readiness.
+- Replace remaining legacy `specs/` references and mixed workflow guidance with a single OpenSpec-first development flow.
+- Redesign AI collaboration guidance around project-specific `AGENTS.md`, project-level `CLAUDE.md`, and Copilot instructions, while keeping tool surface area minimal.
+- Simplify GitHub Actions so CI validates quality instead of mutating the branch, and reduce noisy or redundant workflow behavior.
+- Reposition GitHub Pages, README surfaces, changelog usage, and GitHub metadata so the project presents a focused, credible public surface.
+- Define the preferred local development/tooling baseline for this C++/CUDA repository, including hooks, LSP strategy, review flow, and the trade-offs around MCP/plugins.
+- Audit and fix repository drift, stale claims, and real defects uncovered during normalization.
+
+## Capabilities
+
+### New Capabilities
+- `repository-governance`: Defines the required repository structure, OpenSpec-first governance, documentation quality bar, and workflow simplification rules for Tiny-LLM.
+- `ai-assisted-development`: Defines the project-specific operating model for OpenSpec, AGENTS/CLAUDE/Copilot guidance, review checkpoints, subagent usage, and low-noise automation.
+- `project-presentation`: Defines how README, GitHub Pages, changelog surfaces, and GitHub metadata should present the project to new users and future maintainers.
+
+### Modified Capabilities
+- None.
+
+## Impact
+
+- Affects `openspec/`, `AGENTS.md`, contributor docs, README surfaces, website content, and `.github/workflows/*`.
+- Introduces project-level AI guidance artifacts and a clearer local development baseline.
+- May remove low-value or duplicated documents, changelog entries, and workflow behavior as part of aggressive cleanup.
+- Drives subsequent bug-fixing and repository hardening work from a single OpenSpec change instead of ad hoc edits.
diff --git a/openspec/changes/normalize-archive-readiness/specs/ai-assisted-development/spec.md b/openspec/changes/normalize-archive-readiness/specs/ai-assisted-development/spec.md
new file mode 100644
index 0000000..cc4c136
--- /dev/null
+++ b/openspec/changes/normalize-archive-readiness/specs/ai-assisted-development/spec.md
@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: The repository SHALL provide a clear project-specific AI instruction hierarchy
+Tiny-LLM SHALL define a compact, project-specific instruction hierarchy for AI-assisted development. `AGENTS.md`, project `CLAUDE.md`, OpenSpec artifacts, and project-level Copilot instructions SHALL be internally consistent and SHALL identify the repository's authoritative workflow, quality expectations, and scope boundaries.
+
+#### Scenario: An AI agent starts work
+- **WHEN** an AI agent reads repository guidance before making changes
+- **THEN** it SHALL be able to identify the authoritative workflow, current architectural constraints, and where project-specific instructions live
+
+#### Scenario: Local-only configuration coexists with project guidance
+- **WHEN** a local or personal instruction file exists alongside project-level guidance
+- **THEN** repository documentation SHALL make clear that local-only files do not override the project's authoritative rules
+
+### Requirement: AI-assisted development SHALL follow an OpenSpec-centered operating model
+AI-assisted work on Tiny-LLM SHALL use an OpenSpec-centered operating model: explore or propose first for non-trivial changes, apply against explicit tasks, and use review checkpoints before concluding major repository-wide edits. The operating model SHALL prefer long-running single-session execution over unnecessary parallel fleet usage and SHALL document when `/review` and subagents are appropriate.
+
+#### Scenario: A non-trivial cleanup is requested
+- **WHEN** an agent is asked to make a cross-cutting repository change
+- **THEN** it SHALL anchor the work in an OpenSpec change with explicit tasks before broad implementation begins
+
+#### Scenario: Review checkpoint is needed
+- **WHEN** a major workstream such as workflow redesign, governance rewrite, or public-site repositioning is completed
+- **THEN** the documented process SHALL require a review-oriented checkpoint before finalizing the workstream
+
+### Requirement: Developer tooling guidance SHALL standardize LSP and right-size integrations
+The project SHALL standardize on `clangd` plus `compile_commands.json` as the default LSP path for local development in this C++17/CUDA repository. Tooling guidance SHALL explain that this baseline is reusable across supported editors and AI coding tools, while MCP servers, plugins, and extra integrations SHALL remain optional and SHALL be adopted only when they provide clear repository-specific value.
+
+#### Scenario: A developer configures local intelligence tools
+- **WHEN** a developer or AI tool needs language-aware navigation for Tiny-LLM
+- **THEN** the project guidance SHALL direct them to the canonical `clangd` plus `compile_commands.json` setup
+
+#### Scenario: A new integration is considered
+- **WHEN** a plugin, MCP server, or tool-specific integration is proposed
+- **THEN** it SHALL be adopted only if its value exceeds the added maintenance and context cost
diff --git a/openspec/changes/normalize-archive-readiness/specs/project-presentation/spec.md b/openspec/changes/normalize-archive-readiness/specs/project-presentation/spec.md
new file mode 100644
index 0000000..4e34aa3
--- /dev/null
+++ b/openspec/changes/normalize-archive-readiness/specs/project-presentation/spec.md
@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: Public project surfaces SHALL present one focused project identity
+The repository README, GitHub description/about, homepage URL, and repository topics SHALL present a consistent explanation of what Tiny-LLM is, what it is good at, and how a new user should evaluate or start with it. Public messaging SHALL avoid stale roadmap inflation, duplicated positioning, and unsupported claims.
+
+#### Scenario: A new user lands on the repository
+- **WHEN** a user reads the README or GitHub About section
+- **THEN** they SHALL see a concise, consistent description of Tiny-LLM's purpose, maturity, and next-step links
+
+#### Scenario: Public claims are reviewed
+- **WHEN** a feature, performance, or roadmap claim cannot be supported by the repository's current implementation or validated documentation
+- **THEN** that claim SHALL be revised or removed from the public project surface
+
+### Requirement: GitHub Pages SHALL act as a focused showcase and onboarding surface
+The GitHub Pages site SHALL exist to attract, orient, and qualify new users. Its homepage and key entry pages SHALL emphasize Tiny-LLM's value proposition, architecture, implementation maturity, and developer entry points rather than functioning as a low-signal mirror of repository documents.
+
+#### Scenario: A visitor opens the homepage
+- **WHEN** a visitor lands on the GitHub Pages root
+- **THEN** the page SHALL communicate the project's value proposition, technical strengths, and primary calls to action within the first screenful
+
+#### Scenario: The site duplicates repository content
+- **WHEN** a Pages section provides little value beyond copying README text or low-signal historical content
+- **THEN** it SHALL be removed, merged, or redesigned into a higher-signal entry point
+
+### Requirement: Changelog and release surfaces SHALL stay high-signal
+Changelog pages, release notes, and related navigation SHALL focus on meaningful user-facing or maintainer-relevant changes. Low-value, noisy, or repetitive entries SHALL be consolidated or removed, and the remaining surfaces SHALL support a low-maintenance archival trajectory.
+
+#### Scenario: A change is considered for the changelog
+- **WHEN** a change does not materially affect users, maintainers, or the public understanding of the project
+- **THEN** it SHALL not receive a standalone changelog surface
+
+#### Scenario: Release history is presented
+- **WHEN** a reader browses release or changelog surfaces
+- **THEN** they SHALL encounter a concise history that highlights meaningful milestones instead of workflow noise
diff --git a/openspec/changes/normalize-archive-readiness/specs/repository-governance/spec.md b/openspec/changes/normalize-archive-readiness/specs/repository-governance/spec.md
new file mode 100644
index 0000000..bafa8de
--- /dev/null
+++ b/openspec/changes/normalize-archive-readiness/specs/repository-governance/spec.md
@@ -0,0 +1,45 @@
+## ADDED Requirements
+
+### Requirement: OpenSpec SHALL be the canonical change-management workflow
+The repository SHALL use OpenSpec as the only normative workflow for non-trivial changes, repository restructuring, and cross-cutting cleanup. Contributor-facing guidance SHALL reference `openspec/` paths and OpenSpec commands instead of legacy `specs/` structures or ad hoc spec-first instructions.
+
+#### Scenario: Cross-cutting change is prepared
+- **WHEN** a contributor begins a repository-wide or behavior-affecting change
+- **THEN** an active OpenSpec change SHALL exist before implementation proceeds
+
+#### Scenario: Contributor guidance references the workflow
+- **WHEN** a user reads project workflow documentation
+- **THEN** the documentation SHALL reference only the canonical OpenSpec workflow and current repository structure
+
+### Requirement: Repository structure SHALL stay coherent with documented ownership
+The repository SHALL maintain a clear and current mapping between top-level directories, their purpose, and the documents that govern them. Legacy or misleading references to removed directories, obsolete ownership models, or personal-only configuration SHALL be removed from project-level guidance.
+
+#### Scenario: Repository layout is described
+- **WHEN** a top-level guide describes the repository structure
+- **THEN** every referenced directory or file SHALL exist and match its documented purpose
+
+#### Scenario: Personal configuration is distinguished
+- **WHEN** the repository includes both project-level and personal/local configuration files
+- **THEN** project-level guidance SHALL identify which files are authoritative for the repository and which are local-only
+
+### Requirement: Repository automation SHALL be low-noise and non-mutating
+Continuous integration, release, and documentation workflows SHALL validate repository state without auto-committing back to the branch. Workflow triggers, jobs, and output SHALL be minimized to the smallest set that preserves confidence in buildability, correctness, and public-site integrity.
+
+#### Scenario: CI validates source quality
+- **WHEN** a CI workflow checks formatting, buildability, or tests
+- **THEN** it SHALL report failures directly instead of rewriting tracked files and creating commits
+
+#### Scenario: Workflow inventory is reviewed
+- **WHEN** a repository workflow provides no meaningful quality, release, or presentation value
+- **THEN** it SHALL be removed, simplified, or merged into a higher-signal workflow
+
+### Requirement: Repository documents SHALL be aggressively pruned for signal
+Project-level documentation SHALL prioritize Tiny-LLM-specific, actionable guidance. Low-value, duplicated, stale, or generic documents SHALL be deleted, merged, or rewritten so the repository becomes smaller and more coherent over time.
+
+#### Scenario: Duplicate guidance exists
+- **WHEN** two or more documents explain the same workflow or project concept
+- **THEN** the repository SHALL retain one authoritative version and remove or redirect the rest
+
+#### Scenario: Stale content is discovered
+- **WHEN** a document contains outdated structure, roadmap, or process claims
+- **THEN** that content SHALL be corrected or removed before the cleanup change is considered complete
diff --git a/openspec/changes/normalize-archive-readiness/tasks.md b/openspec/changes/normalize-archive-readiness/tasks.md
new file mode 100644
index 0000000..8b9ff11
--- /dev/null
+++ b/openspec/changes/normalize-archive-readiness/tasks.md
@@ -0,0 +1,36 @@
+## 1. Baseline audit
+
+- [x] 1.1 Inventory the dirty working tree, legacy `specs/` references, active docs drift, workflow sprawl, and site/public-surface inconsistencies
+- [x] 1.2 Run the current CMake configure/build/test flow and capture baseline failures, warnings, and environment/tooling gaps
+- [x] 1.3 Inspect current GitHub metadata, Pages configuration, and workflow behavior so later cleanup is grounded in actual repository state
+
+## 2. OpenSpec and governance normalization
+
+- [x] 2.1 Align OpenSpec migration artifacts, repository structure references, and governance docs so OpenSpec is the only canonical workflow
+- [x] 2.2 Rewrite contributor-facing workflow guidance to remove legacy `specs/` paths and define a closure-oriented development process
+- [x] 2.3 Define the repository cleanup policy for low-value docs, non-mutating CI, and authoritative project-level guidance files
+
+## 3. AI instruction and tooling baseline
+
+- [x] 3.1 Curate `AGENTS.md` and create a project-level `CLAUDE.md` that capture Tiny-LLM-specific workflow, constraints, and review expectations
+- [x] 3.2 Add concise project-level Copilot instructions and align them with OpenSpec, review, subagent, and autopilot usage guidance
+- [x] 3.3 Standardize the developer tooling baseline for `clangd` + `compile_commands.json`, lightweight hooks, and optional MCP/plugin usage
+
+## 4. Workflow and engineering configuration simplification
+
+- [x] 4.1 Redesign CI so it validates formatting, buildability, and tests without mutating tracked files or auto-committing changes
+- [x] 4.2 Simplify Pages and Release workflows, triggers, and supporting config to match a lower-noise archive-ready maintenance model
+- [x] 4.3 Rationalize root engineering config such as `.gitignore`, local setup guidance, and related repository-quality files
+
+## 5. Documentation and public-surface redesign
+
+- [x] 5.1 Rewrite `README.md` and `README.zh-CN.md` around the final project positioning and remove stale roadmap or structure claims
+- [x] 5.2 Prune or merge low-value docs, changelog surfaces, and supporting pages so the documentation tree becomes smaller and higher-signal
+- [x] 5.3 Reposition GitHub Pages as a focused showcase/onboarding surface with stronger value proposition, architecture framing, and calls to action
+
+## 6. Metadata alignment, bug remediation, and closure
+
+- [x] 6.1 Update GitHub repository description, homepage URL, and topics with `gh` after README and Pages messaging are finalized
+- [x] 6.2 Re-audit code/spec/doc drift and fix real defects or inconsistencies surfaced by the normalization work
+- [x] 6.3 Re-run formatting, build, tests, and site validation, then resolve any regressions introduced by the cleanup
+- [x] 6.4 Write the final lightweight closure playbook and prepare the change for archive once the repository is coherent
diff --git a/openspec/config.yaml b/openspec/config.yaml
new file mode 100644
index 0000000..a94008c
--- /dev/null
+++ b/openspec/config.yaml
@@ -0,0 +1,25 @@
+schema: spec-driven
+
+context: |
+  Tech stack: C++17, CUDA C++17, CMake 3.18+
+  GPU: CUDA 11.0+, Compute Capability 7.0+ (Volta+)
+  Testing: GoogleTest v1.14.0, RapidCheck (property-based)
+  Logging: spdlog v1.12.0
+  Code Style: clang-format 18 (LLVM style, 100 col limit)
+  Package Manager: CMake FetchContent
+
+  Project: Tiny-LLM - A CUDA C++ library for LLM inference with W8A16 quantization.
+
+rules:
+  specs:
+  - Include test scenarios linked to correctness properties (P1-P9)
+  - "Use RFC 2119 keywords: SHALL/MUST (mandatory), SHOULD (recommended), MAY (optional)"
+  - Reference API schemas in openspec/schemas/api/ for interface contracts
+  design:
+  - Document CUDA kernel optimization decisions
+  - Specify memory layout and quantization approach
+  - Consider GPU memory constraints and kernel efficiency
+  tasks:
+  - Verify build with cmake before marking complete
+  - Run GoogleTest suite after implementation
+  - Ensure clang-format compliance
diff --git a/openspec/schemas/api/inference-engine.yaml b/openspec/schemas/api/inference-engine.yaml
new file mode 100644
index 0000000..70022af
--- /dev/null
+++ b/openspec/schemas/api/inference-engine.yaml
@@ -0,0 +1,77 @@
+# Tiny-LLM API Specification
+# Human-readable API definition for the inference engine
+
+## Core Types
+
+### ModelConfig
+Configuration for loading a Transformer model.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| vocab_size | int | Vocabulary size |
+| hidden_dim | int | Hidden dimension |
+| num_layers | int | Number of Transformer layers |
+| num_heads | int | Number of attention heads |
+| num_kv_heads | int | Number of KV heads (for GQA) |
+| head_dim | int | Dimension per head |
+| intermediate_dim | int | FFN intermediate dimension |
+| max_seq_len | int | Maximum sequence length |
+| rope_theta | float | RoPE theta |
+| rms_norm_eps | float | RMSNorm epsilon |
+
+### GenerationConfig
+Configuration for text generation.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| max_new_tokens | int | Maximum tokens to generate |
+| temperature | float | Sampling temperature |
+| top_k | int | Top-k sampling parameter |
+| top_p | float | Top-p (nucleus) sampling parameter |
+| eos_token_id | int | End-of-sequence token ID |
+
+## Public API
+
+### InferenceEngine::load(path, config) -> Result<InferenceEngine>
+Load a model from file path with given configuration.
+
+**Parameters:**
+- `path`: Model file path (string)
+- `config`: ModelConfig struct
+
+**Returns:**
+- `Result<InferenceEngine>`: Engine instance or error
+
+**Errors:**
+- File not found
+- Corrupted model file
+- GPU memory allocation failure
+- Invalid model dimensions
+
+### InferenceEngine::generate(tokens, config) -> vector<int>
+Generate tokens from a prompt.
+
+**Parameters:**
+- `tokens`: Input token IDs (vector<int>)
+- `config`: GenerationConfig struct
+
+**Returns:**
+- Generated token sequence including input tokens
+
+### InferenceEngine::prefill(tokens) -> void
+Process input tokens in parallel (prefill phase).
+
+### InferenceEngine::decodeStep(config) -> int
+Generate a single token (decode phase).
+
+**Returns:**
+- Next token ID
+
+## Error Types
+
+| Error | Description |
+|-------|-------------|
+| CudaException | CUDA runtime error with file and line |
+| ModelLoadError | Failed to load or validate model |
+| OutOfMemoryError | GPU memory exhausted |
+| InvalidModelError | Model file corrupted or invalid |
diff --git a/openspec/schemas/db/schema-v1.dbml b/openspec/schemas/db/schema-v1.dbml
new file mode 100644
index 0000000..dfb0e2e
--- /dev/null
+++ b/openspec/schemas/db/schema-v1.dbml
@@ -0,0 +1,178 @@
+// Tiny-LLM Model Schema
+// DBML-style definition for model architecture and data structures
+// Version: 2.0.1 | Last Updated: 2026-04-17
+
+// =============================================================================
+// Core Configuration Models
+// =============================================================================
+
+Table model_config {
+  vocab_size int [not null, default: 32000, note: "Vocabulary size"]
+  hidden_dim int [not null, default: 4096, note: "Hidden dimension (d_model)"]
+  num_layers int [not null, default: 32, note: "Number of Transformer layers"]
+  num_heads int [not null, default: 32, note: "Number of attention heads"]
+  num_kv_heads int [not null, default: 32, note: "Number of KV heads (GQA)"]
+  head_dim int [not null, default: 128, note: "Dimension per attention head"]
+  intermediate_dim int [not null, default: 11008, note: "FFN intermediate dimension"]
+  max_seq_len int [not null, default: 2048, note: "Maximum sequence length"]
+  rope_theta float [not null, default: 10000.0, note: "RoPE theta parameter"]
+  rms_norm_eps float [not null, default: 1e-5, note: "RMSNorm epsilon"]
+  eos_token_id int [not null, default: 2, note: "End-of-sequence token ID"]
+  bos_token_id int [not null, default: 1, note: "Beginning-of-sequence token ID"]
+}
+
+Table quantization_params {
+  group_size int [not null, default: 128, note: "Elements per scale factor"]
+  symmetric bool [not null, default: true, note: "Symmetric quantization (no zero point)"]
+}
+
+// =============================================================================
+// Weight Tensor Models
+// =============================================================================
+
+Table quantized_weight {
+  id int [pk]
+  name varchar [not null, note: "Weight tensor name"]
+  rows int [not null, note: "Number of rows (output dimension)"]
+  cols int [not null, note: "Number of columns (input dimension)"]
+  group_size int [not null, default: 128, note: "Quantization group size"]
+
+  // Derived fields (computed)
+  scale_rows int [note: "ceil(rows/group_size)"]
+  scale_cols int [note: "Same as cols"]
+  weight_bytes bigint [note: "rows * cols * sizeof(int8)"]
+  scale_bytes bigint [note: "scale_rows * scale_cols * sizeof(fp16)"]
+  total_bytes bigint [note: "weight_bytes + scale_bytes"]
+}
+
+Table transformer_weights {
+  id int [pk]
+  layer_index int [not null, note: "Layer index in model"]
+
+  // Attention weights (all quantized)
+  wq_id int [ref: > quantized_weight.id, note: "Query projection [hidden_dim, hidden_dim]"]
+  wk_id int [ref: > quantized_weight.id, note: "Key projection [hidden_dim, kv_dim]"]
+  wv_id int [ref: > quantized_weight.id, note: "Value projection [hidden_dim, kv_dim]"]
+  wo_id int [ref: > quantized_weight.id, note: "Output projection [hidden_dim, hidden_dim]"]
+
+  // FFN weights (SwiGLU, all quantized)
+  w1_id int [ref: > quantized_weight.id, note: "Gate projection [hidden_dim, intermediate_dim]"]
+  w2_id int [ref: > quantized_weight.id, note: "Down projection [intermediate_dim, hidden_dim]"]
+  w3_id int [ref: > quantized_weight.id, note: "Up projection [hidden_dim, intermediate_dim]"]
+
+  // Normalization weights (FP16, not quantized)
+  rms_att_weight_dim int [not null, note: "RMS attention weight dimension [hidden_dim]"]
+  rms_ffn_weight_dim int [not null, note: "RMS FFN weight dimension [hidden_dim]"]
+}
+
+Table model_weights {
+  id int [pk]
+
+  // Token embedding (FP16)
+  token_embedding_rows int [not null, note: "vocab_size"]
+  token_embedding_cols int [not null, note: "hidden_dim"]
+
+  // Output
+  final_norm_weight_dim int [not null, note: "hidden_dim"]
+  lm_head_id int [ref: > quantized_weight.id, note: "Output projection [hidden_dim, vocab_size]"]
+}
+
+// =============================================================================
+// Runtime State Models
+// =============================================================================
+
+Table kv_cache_config {
+  num_layers int [not null, default: 32]
+  num_heads int [not null, default: 32]
+  head_dim int [not null, default: 128]
+  max_seq_len int [not null, default: 2048]
+  max_batch_size int [not null, default: 1]
+}
+
+Table kv_cache_slot {
+  slot_id int [pk]
+  seq_len int [not null, default: 0, note: "Current sequence length"]
+  is_active bool [not null, default: false, note: "Slot is in use"]
+
+  // Memory layout: [num_layers, 2, max_seq_len, num_heads, head_dim]
+  // 2 = K and V tensors
+  k_cache_ptr bigint [note: "GPU pointer to K cache"]
+  v_cache_ptr bigint [note: "GPU pointer to V cache"]
+}
+
+Table generation_config {
+  max_new_tokens int [not null, default: 256]
+  temperature float [not null, default: 1.0]
+  top_k int [not null, default: 50]
+  top_p float [not null, default: 0.9]
+  do_sample bool [not null, default: false, note: "false = greedy"]
+  repetition_penalty float [not null, default: 1.0]
+}
+
+Table generation_stats {
+  prefill_time_ms float [default: 0.0]
+  decode_time_ms float [default: 0.0]
+  prompt_tokens int [default: 0]
+  tokens_generated int [default: 0]
+  tokens_per_second float [default: 0.0]
+  peak_memory_bytes bigint [default: 0]
+}
+
+// =============================================================================
+// Memory Layout Specifications
+// =============================================================================
+
+// KV Cache Memory Layout (FP16):
+// Shape: [num_layers, 2, max_batch_size, max_seq_len, num_heads, head_dim]
+// Total elements: num_layers * 2 * max_batch_size * max_seq_len * num_heads * head_dim
+// Total bytes: total_elements * sizeof(half) = total_elements * 2
+
+// Weight Memory Layout:
+// - QuantizedWeight: INT8 weights + FP16 scales
+// - Weights: [rows, cols] int8
+// - Scales: [ceil(rows/group_size), cols] fp16
+
+// Example for Llama-2-7B (hidden_dim=4096, num_layers=32, intermediate_dim=11008):
+// Per-layer attention: 4 * 4096 * 4096 = 67M parameters -> 67MB INT8 + 0.5MB scales
+// Per-layer FFN: 3 * 4096 * 11008 = 135M parameters -> 135MB INT8 + 1MB scales
+// Total per layer: ~202MB INT8 + ~1.5MB scales = ~203.5MB
+// Full model (32 layers): ~6.5GB INT8 (vs ~13GB FP16)
+
+// =============================================================================
+// GGUF File Format Schema
+// =============================================================================
+
+Table gguf_header {
+  magic varchar [not null, note: "GGUF magic number"]
+  version int [not null, note: "Format version"]
+  tensor_count bigint [not null, note: "Number of tensors"]
+  metadata_kv_count bigint [not null, note: "Number of metadata key-value pairs"]
+}
+
+Table gguf_metadata {
+  key varchar [pk, not null]
+  value_type varchar [not null, note: "String, Float, Int, Bool, Array, etc."]
+  value text [not null, note: "JSON-encoded value"]
+}
+
+Table gguf_tensor_info {
+  name varchar [pk, not null, note: "Tensor name"]
+  n_dims int [not null, note: "Number of dimensions"]
+  dims array [not null, note: "Dimension sizes"]
+  dtype varchar [not null, note: "Data type (F16, Q8_0, etc.)"]
+  offset bigint [not null, note: "Offset in file"]
+}
+
+// =============================================================================
+// Indexes for Query Optimization
+// =============================================================================
+
+// Primary lookup paths:
+// 1. Model config -> Model weights -> Transformer weights per layer
+// 2. Generation config -> Generation stats
+// 3. KV cache config -> KV cache slots by is_active
+
+// Notes:
+// - All GPU memory allocations use RAII pattern (DeviceBuffer)
+// - Error handling via Result<T> monad (no exceptions for control flow)
+// - Thread-safe: single-owner model, concurrent KV cache slot allocation
diff --git a/openspec/specs/inference-engine/spec.md b/openspec/specs/inference-engine/spec.md
new file mode 100644
index 0000000..4e54f58
--- /dev/null
+++ b/openspec/specs/inference-engine/spec.md
@@ -0,0 +1,245 @@
+# Inference Engine Capability
+
+> **Version:** 3.0.0 | **Date:** 2026-04-23 | **Status:** Active
+
+## Purpose
+
+A lightweight LLM inference engine implementing W8A16 quantization, KV Cache incremental decoding, and modular Transformer inference for CUDA-enabled GPUs. This capability provides high-performance text generation with ~50% memory reduction through INT8 weight quantization.
+
+## Terminology
+
+| Term | Description |
+|------|-------------|
+| W8A16 | Mixed precision: INT8 weights, FP16 activations |
+| KV Cache | Key-Value cache for autoregressive generation |
+| Warp Shuffle | CUDA warp-level data exchange instruction |
+| GQA | Grouped Query Attention |
+| GGUF | LLM model weight file format |
+
+---
+
+## Requirements
+
+### REQ-1: Model Loading
+
+The system SHALL parse and load GGUF model files with the following capabilities:
+
+1. The system SHALL parse GGUF file headers and configuration metadata.
+2. The system SHALL read binary format quantized weights (INT8 + scales).
+3. The system SHALL allocate GPU memory and transfer weight data to the device.
+4. The system SHALL return a structured error for corrupted or invalid files.
+5. The system SHALL provide a structured model representation including `ModelConfig` and `QuantizedWeight` structures.
+
+#### Scenario: Load valid model file
+- **GIVEN** a valid GGUF model file
+- **WHEN** `InferenceEngine::load()` is called
+- **THEN** the engine SHALL be successfully created
+- **AND** weights SHALL be transferred to GPU memory
+
+#### Scenario: Handle corrupted model file
+- **GIVEN** a corrupted or invalid model file
+- **WHEN** `InferenceEngine::load()` is called
+- **THEN** an error SHALL be returned (not a crash)
+- **AND** the error message SHALL describe the issue
+
+#### Scenario: Scale dimension correctness (P8)
+- **GIVEN** per-group quantization scales
+- **WHEN** scales are applied to weights
+- **THEN** the output dimensions SHALL be correct
+
+---
+
+### REQ-2: W8A16 Matrix Multiplication
+
+The system SHALL implement W8A16 quantized matrix multiplication optimized for CUDA:
+
+1. The system SHALL accept INT8 weights, FP16 activations, and per-group scales as input.
+2. The system SHALL perform register-level dequantization for optimal bandwidth utilization.
+3. The system SHALL use CUDA intrinsics and warp shuffle optimization.
+4. The system SHALL support configurable tile sizes (TILE_M × TILE_N × BLOCK_K).
+5. The system SHALL achieve relative error < 1% compared to FP16 baseline.
+
+#### Scenario: W8A16 MatMul precision (P1)
+- **GIVEN** INT8 weights and FP16 activations
+- **WHEN** W8A16 matmul is executed
+- **THEN** the relative error vs FP16 baseline SHALL be < 1%
+
+#### Scenario: Performance optimization
+- **GIVEN** a W8A16 matrix multiplication kernel
+- **WHEN** executed on a CUDA device
+- **THEN** the kernel SHALL use global memory coalesced access
+- **AND** the kernel SHALL use shared memory tiling
+- **AND** the kernel SHALL minimize synchronization points
+
+---
+
+### REQ-3: KV Cache Management
+
+The system SHALL implement a KV Cache for efficient autoregressive generation:
+
+1. The system SHALL pre-allocate GPU memory pool for KV cache.
+2. The system SHALL allocate and release sequence slots dynamically.
+3. The system SHALL append KV pairs incrementally per-layer.
+4. The system SHALL track per-sequence usage and capacity.
+5. The system SHALL return an error on memory exhaustion.
+
+#### Scenario: Allocate and release sequence
+- **GIVEN** an initialized KV cache
+- **WHEN** a sequence is allocated via `allocateSequence(max_len)`
+- **THEN** memory SHALL be reserved for the sequence
+- **WHEN** the sequence is released via `releaseSequence(seq_id)`
+- **THEN** memory SHALL be freed and available for new sequences
+
+#### Scenario: KV cache invariants (P2)
+- **GIVEN** an active sequence in KV cache
+- **WHEN** KV pairs are appended via `appendKV(seq_id, layer_idx, k, v, n)`
+- **THEN** the cache size SHALL never exceed allocated capacity
+- **AND** sequence length SHALL be tracked correctly
+
+#### Scenario: Memory exhaustion
+- **GIVEN** limited GPU memory
+- **WHEN** allocation exceeds available memory
+- **THEN** an `OutOfMemoryError` SHALL be returned
+- **AND** existing allocations SHALL remain intact
+
+---
+
+### REQ-4: Transformer Layer
+
+The system SHALL implement a complete Transformer layer with W8A16 quantization:
+
+1. The system SHALL compute Q, K, V projections using W8A16 matmul.
+2. The system SHALL apply causal masking for autoregressive generation.
+3. The system SHALL compute FFN using W8A16 matmul.
+4. The system SHALL apply RMSNorm with output RMS ≈ 1.
+5. The system SHALL apply residual connections.
+6. The system SHALL support incremental decoding mode.
+
+#### Scenario: Causal masking correctness (P3)
+- **GIVEN** attention computation in a Transformer layer
+- **WHEN** causal masking is applied
+- **THEN** future tokens SHALL be masked out correctly
+
+#### Scenario: RMSNorm output normalization (P4)
+- **GIVEN** an input tensor to RMSNorm
+- **WHEN** RMSNorm is applied
+- **THEN** the output RMS SHALL be approximately 1
+
+#### Scenario: Incremental decoding equivalence (P5)
+- **GIVEN** a sequence of tokens
+- **WHEN** incremental decoding processes tokens one-by-one
+- **THEN** the output SHALL be equivalent to processing all tokens at once
+
+---
+
+### REQ-5: Token Generation
+
+The system SHALL implement token generation for autoregressive inference:
+
+1. The system SHALL process prefill phase in parallel.
+2. The system SHALL compute logits and support sampling strategies.
+3. The system SHALL update KV cache during generation.
+4. The system SHALL enforce configurable maximum generation length.
+5. The system SHALL detect EOS token for early stopping.
+6. The system SHALL report tokens/second statistics.
+
+#### Scenario: Greedy sampling (P6)
+- **GIVEN** logits from the model
+- **WHEN** greedy sampling is used
+- **THEN** the token with highest probability SHALL be selected
+
+#### Scenario: Generation length limit (P7)
+- **GIVEN** `max_new_tokens = N`
+- **WHEN** generation is executed
+- **THEN** the output length SHALL never exceed N tokens
+- **AND** EOS token SHALL stop generation early if encountered
+
+---
+
+### REQ-6: Performance Optimization
+
+The system SHALL optimize for GPU execution efficiency:
+
+1. The system SHALL use global memory coalesced access patterns.
+2. The system SHALL use shared memory tiling for matrix operations.
+3. The system SHALL use optimized thread block dimensions.
+4. The system SHALL minimize synchronization points.
+5. The system SHALL support CUDA streams for overlapping operations.
+
+#### Scenario: Memory coalescing optimization
+- **GIVEN** a CUDA kernel accessing global memory
+- **WHEN** the kernel is executed
+- **THEN** memory access patterns SHALL be coalesced for optimal bandwidth
+
+#### Scenario: Shared memory tiling
+- **GIVEN** a matrix multiplication kernel
+- **WHEN** the kernel computes partial results
+- **THEN** shared memory tiling SHALL be used to reduce global memory access
+
+---
+
+### REQ-7: Error Handling
+
+The system SHALL provide robust error handling:
+
+1. The system SHALL capture CUDA errors with file and line information.
+2. The system SHALL validate weight dimensions during loading.
+3. The system SHALL provide numerical validation options.
+4. The system SHALL report memory allocation failures.
+5. The system SHALL support profiling mode for timing analysis.
+
+#### Scenario: CUDA error recovery
+- **GIVEN** a CUDA operation that may fail
+- **WHEN** the operation fails
+- **THEN** a `CudaException` SHALL be thrown
+- **AND** the error SHALL include file and line information
+
+#### Scenario: Corrupted file does not crash (P9)
+- **GIVEN** a corrupted model file
+- **WHEN** the model loader attempts to load it
+- **THEN** the system SHALL NOT crash
+- **AND** an appropriate error SHALL be returned
+
+---
+
+## Non-Functional Requirements
+
+| Category | Requirement |
+|----------|-------------|
+| Precision | W8A16 SHALL achieve 99%+ precision vs FP16 baseline |
+| Memory | INT8 SHALL reduce ~50% weight memory compared to FP16 |
+| Compatibility | The system SHALL support CUDA 11.0+, CMake 3.18+, C++17 |
+| GPU | The system SHALL require Compute Capability 7.0+ (Volta+) |
+
+---
+
+## Correctness Properties
+
+| ID | Property | Validation Requirement |
+|----|----------|----------------------|
+| P1 | W8A16 relative error < 1% | REQ-2 Scenario 1 |
+| P2 | KV Cache invariants | REQ-3 Scenario 2 |
+| P3 | Causal masking correctness | REQ-4 Scenario 1 |
+| P4 | RMSNorm output RMS ≈ 1 | REQ-4 Scenario 2 |
+| P5 | Incremental decoding equivalent to full computation | REQ-4 Scenario 3 |
+| P6 | Greedy sampling = argmax | REQ-5 Scenario 1 |
+| P7 | Generation length ≤ max_new_tokens | REQ-5 Scenario 2 |
+| P8 | Scale dimension correctness | REQ-1 Scenario 3 |
+| P9 | Corrupted file does not crash | REQ-7 Scenario 2 |
+
+---
+
+## API Reference
+
+See `openspec/schemas/api/inference-engine.yaml` for detailed API contracts.
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 3.0.0 | 2026-04-23 | Migrated to OpenSpec format with RFC 2119 keywords |
+| 2.0.1 | 2026-04-16 | Fixed scale dimension calculation bug |
+| 2.0.0 | 2026-03-09 | KVCache API refactoring |
+| 1.0.0 | 2025-02-13 | Initial release |

From 3eb7f375c66392295fd204bc83b65a4d1dd3c90e Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 02:51:56 +0800
Subject: [PATCH 3/6] docs: streamline documentation and consolidate references

- Simplify README.md and README.zh-CN.md with focused content
- Update CHANGELOG.md with concise changelog entries
- Streamline CONTRIBUTING.md with clearer contribution guidelines
- Reorganize AGENTS.md for better AI assistant integration
---
 AGENTS.md       | 190 +++++++++++++++++---------------------
 CHANGELOG.md    |  54 ++---------
 CONTRIBUTING.md | 165 ++++++++++-----------------------
 README.md       | 238 +++++++++++-------------------------------------
 README.zh-CN.md | 238 +++++++++++-------------------------------------
 5 files changed, 247 insertions(+), 638 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 58671dc..c8a7775 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,148 +1,128 @@
-# Project Philosophy: Spec-Driven Development (SDD)
+# Tiny-LLM Agent Guide
 
-This project strictly follows the **Spec-Driven Development (SDD)** paradigm. All code implementations must use the specifications in the `/specs` directory as the single source of truth.
+Tiny-LLM is in a **final hardening / archive-readiness** phase. Treat this repository as a CUDA/C++ engine that should become **smaller, sharper, and lower-noise** over time.
 
----
+## Operating mode
 
-## Directory Context
+- Prioritize correctness, coherence, and maintainability over new roadmap expansion.
+- Prefer deleting, merging, or rewriting low-value content instead of preserving redundant guidance.
+- Keep public claims aligned with what the repository actually implements and validates.
+- Avoid over-engineering new automation, process, or tooling layers.
 
-| Directory | Purpose | File Types |
-|-----------|---------|------------|
-| `/specs/product/` | Product feature definitions and acceptance criteria | `.md` |
-| `/specs/rfc/` | Technical design documents and architecture decisions | `NNNN-title.md` |
-| `/specs/api/` | API interface definitions (human and machine readable) | `.yaml`, `.json` |
-| `/specs/db/` | Model and data schema definitions | `.dbml`, `.sql` |
-| `/specs/testing/` | BDD test case specifications | `.feature` |
-| `/docs/` | Developer and user documentation | `.md` (EN/ZH) |
-| `/website/` | GitHub Pages website source (Jekyll) | `.yml`, `.md`, `.html`, `.json` |
+## Source of truth
 
----
+1. **Active OpenSpec change** in `openspec/changes/<name>/`
+2. **Current capability specs** in `openspec/specs/`
+3. **Repository code and configuration**
+4. **Project instruction files** (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`)
 
-## AI Agent Workflow Instructions
+Local-only overrides such as `CLAUDE.local.md` are allowed for personal use, but they are **not** authoritative and should not be committed.
 
-When you (the AI agent) are asked to develop a new feature, modify an existing feature, or fix a bug, **you must strictly follow this workflow without skipping any steps**:
+## Required workflow
 
-### Step 1: Review Specs
+### 1. Explore before guessing
 
-Before writing any code, first read the relevant documents in `/specs`:
+Use `/opsx:explore` for open-ended investigation, architecture trade-offs, and requirement clarification.
 
-1. Read the product spec in `/specs/product/` for feature requirements
-2. Read the relevant RFC in `/specs/rfc/` for architecture decisions
-3. Read the API definition in `/specs/api/` for interface contracts
-4. Check `/specs/db/` for data model constraints
+### 2. Propose before non-trivial changes
 
-**If the user's request conflicts with existing specs**, stop immediately and point out the conflict. Ask the user whether to update the spec first.
+Use `/opsx:propose <change-name>` for:
 
-### Step 2: Spec-First Update
+- repository-wide cleanup
+- workflow changes
+- public-surface repositioning
+- feature or behavior changes
+- multi-file refactors with architectural impact
 
-If this is a new feature, or if existing interfaces/data structures need to change:
+### 3. Apply from explicit tasks
 
-1. **Propose spec changes first** - Create or modify files in `/specs/`:
-   - New feature: `specs/product/<feature-name>.md` + `specs/rfc/NNNN-<title>.md`
-   - API changes: Update `specs/api/*.yaml`
-   - Data model changes: Update `specs/db/*.dbml`
-   - Test requirements: Create `specs/testing/<feature>.feature`
+Use `/opsx:apply <change-name>` and implement directly from `tasks.md`. Work in dependency order and keep each task tightly scoped.
 
-2. **Wait for user confirmation** before entering the code implementation phase
+### 4. Review major workstreams
 
-### Step 3: Implementation
+After major workflow, documentation, or architecture changes, run a review-oriented pass (`/review` or equivalent) before considering the workstream complete.
 
-When writing code, **100% adhere to the spec definitions**:
+### 5. Archive finished changes
 
-- Use exact variable naming from specs
-- Follow API paths and data types from `specs/api/`
-- Respect constraints defined in `specs/db/`
-- Implement acceptance criteria from `specs/product/`
+Use `/opsx:archive <change-name>` only after specs, code, docs, and validation results all agree.
 
-**Do not add features not defined in the specs (No Gold-Plating).**
+## Repository priorities
 
-### Step 4: Test Against Spec
+### OpenSpec-first governance
 
-Write tests based on the acceptance criteria in `/specs`:
+- Do not reintroduce legacy `/specs` workflow guidance.
+- Keep contributor docs aligned with `openspec/`.
+- Preserve history through OpenSpec archive, not through duplicated meta-docs.
 
-1. Map each acceptance criterion to a test case
-2. Cover all boundary conditions described in specs
-3. Update `specs/testing/*.feature` if new test scenarios are needed
+### Minimal, high-signal documentation
 
----
+- Prefer one authoritative document per topic.
+- Remove stale changelog pages, duplicated contribution docs, and generic AI boilerplate.
+- Keep README and Pages useful for new users, not just comprehensive.
 
-## Code Generation Rules
+### Non-mutating automation
 
-| Rule | Description |
-|------|-------------|
-| API Changes | Must synchronously update `/specs/api/*.yaml` |
-| New Types | Must be defined in `/specs/db/schema-v1.dbml` |
-| New Features | Require product spec in `/specs/product/` |
-| Architecture Changes | Require RFC in `/specs/rfc/` |
-| Test Requirements | Must be defined in `/specs/testing/` before implementation |
+- CI should validate, not rewrite tracked files or commit back to the branch.
+- Keep workflow triggers and jobs as small as possible while preserving confidence.
 
----
+### Public-surface consistency
 
-## Spec File Naming Conventions
+- README, GitHub Pages, release notes, and GitHub metadata must describe the same project.
+- Remove unsupported roadmap promises and speculative positioning.
 
-| Type | Pattern | Example |
-|------|---------|---------|
-| Product | `<feature-name>.md` | `tiny-llm-inference-engine.md` |
-| RFC | `<NNNN>-<short-title>.md` | `0001-core-architecture.md` |
-| API | `<feature-name>.yaml` | `inference-engine.yaml` |
-| DB Schema | `schema-v<version>.dbml` | `schema-v1.dbml` |
-| Testing | `<feature-name>.feature` | `inference-engine.feature` |
+## Engineering invariants
 
----
+- **Language/toolchain:** C++17, CUDA C++17, CMake 3.18+
+- **GPU baseline:** CUDA 11.0+, Compute Capability 7.0+
+- **Error handling:** `Result<T>` for fallible operations; no exceptions for control flow
+- **CUDA safety:** use the project CUDA utilities/macros instead of silent failures
+- **Resource management:** prefer RAII wrappers over raw ownership
+- **Formatting:** `clang-format-18` with the repository `.clang-format`
+- **Editor baseline:** `clangd` + `compile_commands.json`
 
-## Current Project Context
+### Validation commands
 
-### Tiny-LLM Inference Engine
-
-A lightweight, high-performance CUDA C++ inference engine for Transformer models.
-
-**Key Components:**
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
+cmake --build build -j$(nproc)
+ctest --test-dir build --output-on-failure --timeout 300
+find . -type f \( -name '*.cpp' -o -name '*.h' -o -name '*.cu' -o -name '*.cuh' \) \
+  ! -path './build/*' | xargs clang-format-18 --dry-run --Werror
+```
 
-| Component | Location | Spec |
-|-----------|----------|------|
-| InferenceEngine | `include/tiny_llm/inference_engine.h` | `specs/api/inference-engine.yaml` |
-| KVCacheManager | `include/tiny_llm/kv_cache.h` | `specs/rfc/0001-core-architecture.md` |
-| W8A16 MatMul | `kernels/w8a16_matmul.cu` | `specs/rfc/0001-core-architecture.md` |
-| Model Types | `include/tiny_llm/types.h` | `specs/db/schema-v1.dbml` |
+`nvcc` must be available for a real configure/build.
 
-**Architecture Constraints:**
+## Practical AI-tooling guidance
 
-- CUDA 11.0+, C++17, CMake 3.18+
-- Compute Capability 7.0+ (Volta or newer)
-- W8A16 quantization: INT8 weights, FP16 activations
-- Error handling via `Result<T>` monad (no exceptions for control flow)
+- **AGENTS.md**: repository-wide rules and architecture constraints
+- **CLAUDE.md**: Claude/agent execution guidance for this repo
+- **Copilot instructions**: concise code-generation and workflow constraints
 
----
+Use a **long-running single session** for large repository hardening work. Avoid `/fleet` unless the work is clearly parallelizable and the higher token cost is justified.
 
-## Why This Matters
+Use subagents and research helpers selectively:
 
-| Benefit | Explanation |
-|---------|-------------|
-| **Prevents AI hallucination** | Forcing the first step to read `/specs` anchors the AI's thinking scope |
-| **Enforces modification path** | Declaring "modify specs before code" ensures document-code synchronization |
-| **Improves PR quality** | Implementation aligns with business logic because it follows acceptance criteria |
-| **Enables parallel work** | Specs allow multiple agents to work independently with clear contracts |
+- good fit: independent audits, workflow inspection, broad doc inventories
+- bad fit: tightly coupled refactors where one agent needs end-to-end context
 
----
+Keep MCP usage narrow. Prefer built-in GitHub tooling and `gh` unless MCP gives a clear repository-specific win.
 
-## Quick Reference
+## Repository map
 
-```bash
-# Read all specs before starting work
-cat specs/product/*.md      # Product requirements
-cat specs/rfc/*.md          # Architecture decisions
-cat specs/api/*.yaml        # API contracts
-cat specs/db/*.dbml         # Data models
-cat specs/testing/*.feature # Test specifications
-
-# After code changes, verify specs are updated
-git diff specs/             # Should show corresponding changes
+```text
+openspec/                 OpenSpec config, active changes, archived changes, specs, schemas
+include/tiny_llm/         Public headers
+src/                      Host-side C++ implementation
+kernels/                  CUDA kernels
+tests/                    Unit and property tests
+website/                  GitHub Pages site
+.github/workflows/        CI, Pages, release automation
 ```
 
----
-
-## Related Documents
+## Do not do these by default
 
-- [Contributing Guide](CONTRIBUTING.md) - Development workflow and code standards
-- [Documentation](docs/) - User and developer documentation
-- [Changelog](changelog/) - Version history
+- Do not add large new roadmap features just because they are easy to imagine.
+- Do not preserve outdated docs “for completeness”.
+- Do not commit personal-only tool config.
+- Do not rely on CI to auto-fix formatting or repository drift.
+- Do not split work across many stale branches without quick review and merge.
diff --git a/CHANGELOG.md b/CHANGELOG.md
index f83858a..4dbe83c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,55 +1,19 @@
 # Changelog
 
-All notable changes to the Tiny-LLM project are documented in the [changelog](changelog/) directory.
+Tiny-LLM keeps a deliberately short public changelog. Only meaningful release milestones belong here.
 
 English | [中文](changelog/index.zh)
 
 ---
 
-## Quick Links
+## Releases
 
-| Version | Date | Type | English | 中文 |
-|---------|------|------|---------|------|
-| v2.0.1 | 2026-04-16 | Bug Fix | [Details](changelog/en/v2.0.1) | [详情](changelog/zh/v2.0.1) |
-| v2.0.0 | 2026-03-09 | Major | [Details](changelog/en/v2.0.0) | [详情](changelog/zh/v2.0.0) |
+| Version | Date | Summary | English | 中文 |
+|---|---|---|---|---|
+| v2.0.1 | 2026-04-16 | Bug-fix release for scale-dimension handling and cleanup | [Details](changelog/en/v2.0.1) | [详情](changelog/zh/v2.0.1) |
+| v2.0.0 | 2026-03-09 | Core engine milestone with KV cache API redesign | [Details](changelog/en/v2.0.0) | [详情](changelog/zh/v2.0.0) |
 
----
-
-## Release History
-
-### [v2.0.1] - 2026-04-16
-
-#### Fixed
-- Critical `QuantizedWeight` scale dimension calculation error
-- Removed unused code in attention kernel
-
-**Details**: [English](changelog/en/v2.0.1) | [中文](changelog/zh/v2.0.1)
-
-### [v2.0.0] - 2026-03-09
-
-#### Changed (Breaking)
-- KVCache API redesign with explicit `advanceSeqLen()`
-- CMake modernization with target exports
-
-**Details**: [English](changelog/en/v2.0.0) | [中文](changelog/zh/v2.0.0)
-
-### Infrastructure Updates
-
-| Date | Type | Description |
-|------|------|-------------|
-| 2026-03-13 | Docs/CI | [Documentation & CI Standardization](changelog/en/docs-ci-standardization) |
-| 2026-03-10 | Docs/CI | [GitHub Pages Enhancement](changelog/en/pages-enhancement) |
-| 2025-02-13 | Infra | [Project Infrastructure](changelog/en/project-infrastructure) |
-
----
-
-## Format
-
-This project adheres to:
-- [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
-- [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
-- [Conventional Commits](https://www.conventionalcommits.org/)
-
----
+## Notes
 
-[Documentation](https://lessup.github.io/tiny-llm/) | [API Reference](https://lessup.github.io/tiny-llm/docs/en/API) | [Contributing](CONTRIBUTING.md)
+- Infrastructure-only or low-signal changes are intentionally omitted from the public changelog.
+- Detailed release notes live in the website changelog pages linked above.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d613d1a..c49e7fe 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,148 +1,77 @@
----
-layout: default
-title: "贡献指南 — Tiny-LLM"
-description: "如何参与 Tiny-LLM 项目开发"
----
+# Contributing to Tiny-LLM
 
-# 贡献指南
+Tiny-LLM accepts focused issues and pull requests, but the repository is now optimized for **coherent hardening work**, not broad roadmap expansion. Keep changes small, reviewable, and anchored in the current architecture.
 
-感谢你对 Tiny-LLM 项目的关注！欢迎通过 Issue 和 Pull Request 参与贡献。
+## Core rules
 
----
+1. **OpenSpec first.** Non-trivial changes start in `openspec/`, not in ad hoc docs or code-only branches.
+2. **One authoritative source per topic.** Prefer deleting or merging stale docs over adding parallel guidance.
+3. **Short-lived branches.** Avoid long-lived local/cloud drift; merge or rebase frequently.
+4. **CI validates, contributors fix.** Do not rely on automation to rewrite tracked files for you.
 
-## 开发流程
+## Required workflow
 
-本项目遵循**规范驱动开发（Spec-Driven Development）**。在编写代码之前，必须先更新或创建相应的规范文档。
+### 1. Explore when the scope is unclear
 
-1. **更新/创建 Specs**：在 `/specs` 目录下更新产品需求、RFC 或 API 定义
-2. Fork 本仓库
-3. 创建特性分支：`git checkout -b feature/your-feature`
-4. 进行更改并确保测试通过
-5. 提交更改：`git commit -m "feat: add your feature"`
-6. 推送分支：`git push origin feature/your-feature`
-7. 创建 Pull Request
+Use `/opsx:explore` for investigation, trade-off analysis, and requirement clarification.
 
-> 详细的 AI 助手工作流请参阅 [AGENTS.md](AGENTS.md)。
+### 2. Propose before cross-cutting implementation
 
----
+Use `/opsx:propose <change-name>` for repository-wide cleanup, new behavior, or architectural changes. The proposal should produce:
 
-## 构建与测试
+- `proposal.md`
+- `design.md`
+- `specs/.../spec.md`
+- `tasks.md`
 
-### 系统要求
+### 3. Implement against explicit tasks
 
-- CUDA Toolkit 11.0+
-- CMake 3.18+
-- C++17 兼容编译器 (GCC 9+, Clang 10+, MSVC 2019+)
-- NVIDIA GPU (Compute Capability 7.0+)
+Use `/opsx:apply <change-name>` and work directly from `tasks.md`. Finish tasks in dependency order and keep edits tightly scoped.
 
-### 构建
+### 4. Review before concluding major workstreams
 
-```bash
-mkdir build && cd build
-cmake .. -DCMAKE_BUILD_TYPE=Release
-make -j$(nproc)
-```
-
-### 运行测试
-
-```bash
-ctest --output-on-failure
-```
-
-### 运行 Demo
-
-```bash
-./tiny_llm_demo
-```
-
----
-
-## 代码规范
-
-### 格式化
+Use `/review` or an equivalent review pass after major workflow, documentation, or architecture changes. Do not batch unrelated cleanup into one unreviewed sweep.
 
-- 使用 `.editorconfig` 中定义的缩进和格式规则
-- 项目使用 clang-format 进行格式检查
-- CI 会自动检查代码格式
+### 5. Archive completed changes
 
-### 代码风格
+Use `/opsx:archive <change-name>` after specs, code, and docs are aligned and the repository is ready to preserve the change in `openspec/changes/archive/`.
 
-- C++17 标准特性
-- RAII 资源管理
-- `Result<T>` 错误处理（避免异常用于控制流）
-- CUDA 错误使用 `CUDA_CHECK` 宏
+## Build and validation
 
-### 测试要求
+Tiny-LLM requires a working CUDA toolchain (`nvcc` on `PATH` or an equivalent configured CUDA installation).
 
-- 新增功能需附带单元测试
-- 核心算法需附带属性测试 (RapidCheck)
-- 确保所有现有测试通过
-
----
-
-## 提交信息格式
-
-推荐使用 [Conventional Commits](https://www.conventionalcommits.org/)：
-
-| 前缀 | 说明 |
-|------|------|
-| `feat:` | 新功能 |
-| `fix:` | Bug 修复 |
-| `docs:` | 文档更新 |
-| `perf:` | 性能优化 |
-| `test:` | 测试相关 |
-| `refactor:` | 代码重构 |
-| `ci:` | CI/CD 变更 |
-
-**示例**:
-```
-feat: add top-p sampling support
-fix: correct scale tensor dimension calculation
-docs: update API reference for KVCacheManager
+```bash
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
+cmake --build build -j$(nproc)
+ctest --test-dir build --output-on-failure --timeout 300
 ```
 
----
+For formatting checks:
 
-## 项目结构
-
-```
-tiny-llm/
-├── specs/               # 规范文档 (product, RFC, API, testing)
-├── include/tiny_llm/    # 公共头文件
-├── kernels/             # CUDA Kernel (.cu, .cuh)
-├── src/                 # 主机端实现 (.cpp)
-├── tests/               # 测试文件
-├── docs/                # 文档
-├── changelog/           # 更新日志
-└── AGENTS.md            # AI 工作流定义
+```bash
+find . -type f \( -name '*.cpp' -o -name '*.h' -o -name '*.cu' -o -name '*.cuh' \) \
+  ! -path './build/*' | xargs clang-format-18 --dry-run --Werror
 ```
 
----
-
-## 添加新功能
-
-### 添加新 Kernel
-
-1. 在 `kernels/` 创建 `.cu` 和 `.cuh` 文件
-2. 在 `include/tiny_llm/` 添加公共接口声明
-3. 在 `tests/` 添加单元测试和属性测试
-4. 更新 `CMakeLists.txt`（如需要）
+## Repository hygiene
 
-### 添加新测试
+- Keep README, GitHub Pages, and GitHub metadata consistent with the actual shipped engine.
+- Treat low-value changelog entries, duplicated workflow docs, and stale roadmap promises as cleanup targets.
+- If a document references removed directories or obsolete workflow commands, fix or delete it before merging.
 
-1. 单元测试使用 GoogleTest 宏
-2. 属性测试使用 RapidCheck
-3. 测试文件命名：`test_<module>.cpp` 或 `test_<module>.cu`
+## Low-maintenance flow
 
----
+When the repository only needs focused follow-up work, use this loop:
 
-## 文档更新
+1. Keep one active OpenSpec change per meaningful workstream.
+2. Prefer short-lived branches or a single coordinated branch over parallel stale branches.
+3. Use review checkpoints after each major workstream instead of saving all review until the end.
+4. Archive the change as soon as specs, code, and docs converge so the repository returns to a calm baseline quickly.
 
-- API 变更需更新 `/specs/api/` 和 `docs/` 目录
-- 重要变更需添加 changelog 条目
-- README 变更需同步英文和中文版本
-- 新功能/修改功能需先更新 `/specs/product/` 或 `/specs/rfc/`
+## Project-specific guidance
 
----
+- **Repository workflow and architecture constraints:** [AGENTS.md](AGENTS.md)
+- **Current capabilities and requirements:** `openspec/specs/`
+- **Active and archived change history:** `openspec/changes/`
 
-[← 返回首页](./) | [API 参考](docs/API) | [更新日志](changelog/)
+Use [Conventional Commits](https://www.conventionalcommits.org/) where practical (`feat:`, `fix:`, `docs:`, `ci:`, `refactor:`), but prioritize clear, reviewable changes over ceremony.
diff --git a/README.md b/README.md
index 58660ee..16d28b8 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Tiny-LLM Inference Engine
 
-> A lightweight, high-performance CUDA C++ inference engine for Transformer models.
+> CUDA-native C++ inference engine for focused Transformer deployments.
 
 [![CI](https://github.com/LessUp/tiny-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/LessUp/tiny-llm/actions/workflows/ci.yml)
 [![Pages](https://github.com/LessUp/tiny-llm/actions/workflows/pages.yml/badge.svg)](https://lessup.github.io/tiny-llm/)
@@ -10,235 +10,103 @@
 ![C++](https://img.shields.io/badge/C%2B%2B-17-00599C?logo=c%2B%2B&logoColor=white)
 ![CMake](https://img.shields.io/badge/CMake-3.18+-064F8C?logo=cmake&logoColor=white)
 
-[English](README.md) • [简体中文](README.zh-CN.md) • [Documentation](https://lessup.github.io/tiny-llm/) • [API Reference](https://lessup.github.io/tiny-llm/docs/en/API)
+[English](README.md) • [简体中文](README.zh-CN.md) • [Documentation](https://lessup.github.io/tiny-llm/) • [Architecture](https://lessup.github.io/tiny-llm/docs/en/ARCHITECTURE) • [Changelog](https://lessup.github.io/tiny-llm/changelog/)
 
 ---
 
-## 🎯 Overview
+## Overview
 
-Tiny-LLM is a **high-performance CUDA C++ inference engine** designed for efficient Transformer model deployment on NVIDIA GPUs. It delivers production-ready inference with:
+Tiny-LLM is a lightweight inference engine for Transformer workloads on NVIDIA GPUs. It is built around a focused CUDA/C++ stack: W8A16 quantization, explicit KV cache management, hand-tuned kernels, and a repository workflow designed to keep the codebase coherent as it hardens.
 
-- **~50% memory reduction** via W8A16 quantization (INT8 weights + FP16 activations)
-- **Efficient KV Cache** management for long-context generation
-- **Optimized CUDA kernels** with Tensor Core support
-- **Zero dependencies** — pure CUDA C++ with no external runtime
+## Why Tiny-LLM
 
-Built for developers who need **fast, predictable, and portable** LLM inference without the overhead of heavy frameworks.
+- **W8A16 quantization** with INT8 weights and FP16 activations
+- **Explicit KV cache management** for incremental decoding
+- **CUDA-native kernels** with shared-memory and warp-level optimization patterns
+- **Minimal runtime surface** with `spdlog` as the primary runtime dependency
+- **OpenSpec-governed development** so architecture, docs, and changes stay aligned
 
----
-
-## ✨ Features
-
-| Feature | Description | Status |
-|---------|-------------|--------|
-| **W8A16 Quantization** | INT8 weights + FP16 activations for ~50% memory reduction | ✅ Stable |
-| **KV Cache Management** | Efficient incremental decoding with sequence management | ✅ Stable |
-| **Optimized CUDA Kernels** | Tensor Core INT8, shared memory tiling, warp shuffle reductions | ✅ Stable |
-| **Multi-Sampling Strategies** | Greedy, Temperature, Top-k, Top-p (nucleus) decoding | ✅ Stable |
-| **Result<T> Error Handling** | Monadic error handling — no exceptions for control flow | ✅ Stable |
-| **Comprehensive Testing** | GoogleTest unit tests + RapidCheck property-based tests | ✅ Stable |
-| **Bilingual Documentation** | Full documentation in English and Chinese | ✅ Complete |
-
-### Roadmap
-
-| Feature | Status | Target |
-|---------|--------|--------|
-| GGUF Runtime Loading | 🚧 In Progress | v2.1 |
-| PagedAttention | 📋 Planned | v2.2 |
-| Speculative Decoding | 🔬 Research | v2.3 |
-| FP8 Support | 🔬 Research | v3.0 |
-| Multi-GPU Parallelism | 📋 Planned | v3.0 |
-
----
-
-## ⚡ Performance
-
-Benchmarked on **NVIDIA A100-80GB** (SM 8.0), CUDA 12.4:
-
-| Model | Batch Size | Tokens/sec | Memory Usage | Speedup vs FP16 |
-|-------|-----------|------------|--------------|-----------------|
-| LLaMA-7B | 1 | ~45 t/s | ~3.5 GB | **1.8x** |
-| LLaMA-7B | 4 | ~120 t/s | ~12 GB | **1.6x** |
-| LLaMA-13B | 1 | ~25 t/s | ~6.5 GB | **1.7x** |
-
-> Full benchmarks with different configurations: [Benchmarks](https://lessup.github.io/tiny-llm/docs/en/BENCHMARKS)
+## Core capabilities
 
----
-
-## 🚀 Quick Start
+| Capability | What it covers | Status |
+|---|---|---|
+| W8A16 inference path | Quantized weights, FP16 activations, CUDA kernels | Stable |
+| KV cache manager | Sequence allocation, growth, and release | Stable |
+| Sampling utilities | Greedy, temperature, top-k, top-p | Stable |
+| Error handling | `Result<T>`-based fallible APIs | Stable |
+| Test strategy | GoogleTest + RapidCheck coverage for core paths | Active |
 
-### Requirements
+## Build from source
 
-| Component | Minimum | Recommended |
-|-----------|---------|-------------|
-| NVIDIA GPU | SM 7.0 (Volta) | SM 8.0+ (Ampere+) |
-| CUDA Toolkit | 11.0 | 12.0+ |
-| CMake | 3.18 | 3.25+ |
-| C++ Compiler | GCC 9+ / Clang 10+ | GCC 11+ |
+Tiny-LLM requires a working CUDA toolchain (`nvcc` on `PATH` or an equivalent configured install).
 
-### Build from Source
+| Component | Minimum |
+|---|---|
+| NVIDIA GPU | Compute Capability 7.0+ |
+| CUDA Toolkit | 11.0+ |
+| CMake | 3.18+ |
+| C++ Compiler | GCC 9+ or Clang 10+ |
 
 ```bash
-# Clone and build
 git clone https://github.com/LessUp/tiny-llm.git
 cd tiny-llm
-mkdir build && cd build
-cmake .. -DCMAKE_BUILD_TYPE=Release
-make -j$(nproc)
 
-# Run tests
-ctest --output-on-failure
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
+cmake --build build -j$(nproc)
+ctest --test-dir build --output-on-failure --timeout 300
 ```
 
-### Usage Example
+## Minimal usage example
 
 ```cpp
 #include <tiny_llm/inference_engine.h>
 
 int main() {
-    // Configure model
     ModelConfig config;
     config.vocab_size = 32000;
     config.hidden_dim = 4096;
     config.num_layers = 32;
 
-    // Load model with W8A16 weights
     auto engine = InferenceEngine::load("model.bin", config).value();
 
-    // Generate text
     GenerationConfig gen;
     gen.max_new_tokens = 256;
     gen.temperature = 0.7f;
     gen.top_p = 0.9f;
 
     auto output = engine.generate({1, 15043, 29892}, gen);
-    for (int token : output.tokens) {
-        std::cout << tokenizer.decode(token);
-    }
+    (void)output;
 }
 ```
 
----
-
-## 🏗️ Architecture
-
-```mermaid
-graph LR
-    A[Application] --> B[InferenceEngine]
-    B --> C[ModelLoader]
-    B --> D[KVCacheManager]
-    B --> E[TransformerLayer]
-    C --> F[(W8A16 Weights)]
-    D --> G[GPU Memory]
-    E --> H[W8A16 MatMul]
-    E --> I[Attention]
-    E --> J[RMSNorm]
-    E --> K[Elementwise]
-    H --> L[Tensor Core]
-    I --> L
-```
-
-### Core Components
-
-| Component | Responsibility |
-|-----------|---------------|
-| **InferenceEngine** | Main entry point — orchestrates loading, generation, and sampling |
-| **ModelLoader** | Loads quantized weights from binary format to GPU memory |
-| **KVCacheManager** | Manages key-value cache with sequence allocation and eviction |
-| **TransformerLayer** | Forward pass through a single transformer layer |
-| **W8A16 MatMul** | Quantized matrix multiplication using INT8 × FP16 |
-
----
-
-## 📁 Project Structure
-
-```
-tiny-llm/
-├── website/               # GitHub Pages site (Jekyll)
-│   ├── docs/              # Documentation (EN/ZH)
-│   ├── changelog/         # Version history
-│   ├── assets/            # CSS, JS, images
-│   └── _config.yml        # Jekyll configuration
-├── specs/                 # Spec-driven development documents
-│   ├── product/           # Feature requirements
-│   ├── rfc/               # Architecture decisions
-│   ├── api/               # API definitions
-│   └── testing/           # BDD test specifications
-├── include/tiny_llm/      # Public headers
-├── kernels/               # CUDA kernels (.cu, .cuh)
-├── src/                   # Host-side implementation (.cpp)
-├── tests/                 # Unit & property-based tests
-├── CMakeLists.txt         # Build configuration
-└── README.md              # This file
-```
-
----
-
-## 🔌 GPU Support
-
-| Architecture | Compute Capability | Status | Notes |
-|--------------|-------------------|--------|-------|
-| Volta | SM 7.0, 7.5 | ✅ Supported | Tensor Core INT8 available |
-| Turing | SM 7.5 | ✅ Supported | Improved INT8 performance |
-| Ampere | SM 8.0, 8.6 | ✅ Optimized | Best performance |
-| Ada Lovelace | SM 8.9 | ✅ Optimized | Full feature support |
-| Hopper | SM 9.0 | ✅ Supported | FP8 ready |
-
----
-
-## 🤝 Contributing
-
-We welcome contributions! Tiny-LLM follows **Spec-Driven Development** — specs come before code.
-
-### Quick Start
+## Repository map
 
-```bash
-# Fork and clone
-git clone https://github.com/your-username/tiny-llm.git
-cd tiny-llm
-
-# Build with tests
-mkdir build && cd build
-cmake .. -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
-make -j$(nproc)
-
-# Run checks
-ctest --output-on-failure
+```text
+openspec/                 Current specs, active changes, archived changes, schemas
+include/tiny_llm/         Public headers
+src/                      Host-side C++ implementation
+kernels/                  CUDA kernels
+tests/                    Unit and property tests
+website/                  GitHub Pages site and public docs
+.github/workflows/        CI, Pages, and release automation
 ```
 
-### Ways to Contribute
-
-| Type | How |
-|------|-----|
-| 🐛 **Bug Reports** | [Open an Issue](https://github.com/LessUp/tiny-llm/issues) with reproduction steps |
-| 💡 **Feature Requests** | [Start a Discussion](https://github.com/LessUp/tiny-llm/discussions) |
-| 🔧 **Code Contributions** | Fork → Branch → PR (follow [CONTRIBUTING.md](CONTRIBUTING.md)) |
-| 📝 **Documentation** | Improve docs in `website/docs/` |
-| 🧪 **Testing** | Add unit tests or property-based tests |
+## Documentation and specs
 
----
+- **Project site:** https://lessup.github.io/tiny-llm/
+- **Architecture guide:** https://lessup.github.io/tiny-llm/docs/en/ARCHITECTURE
+- **Developer guide:** https://lessup.github.io/tiny-llm/docs/en/DEVELOPER
+- **OpenSpec source of truth:** `openspec/specs/`
+- **Change history:** `openspec/changes/`
 
-## 📜 License
+## Contributing
 
-This project is licensed under the [MIT License](LICENSE).
+Tiny-LLM uses an OpenSpec-first workflow for non-trivial changes.
 
----
-
-## 🙏 Acknowledgments
-
-- Inspired by [llama.cpp](https://github.com/ggerganov/llama.cpp) and [vLLM](https://github.com/vllm-project/vllm)
-- Testing with [GoogleTest](https://github.com/google/googletest) and [RapidCheck](https://github.com/emil-e/rapidcheck)
-- Built with ❤️ by the [Tiny-LLM contributors](https://github.com/LessUp/tiny-llm/graphs/contributors)
-
----
+- Start with [CONTRIBUTING.md](CONTRIBUTING.md)
+- Read repository-specific constraints in [AGENTS.md](AGENTS.md)
+- Use `/opsx:propose`, `/opsx:apply`, and `/opsx:archive` for structured work
 
-<p align="center">
-  <a href="https://lessup.github.io/tiny-llm/">📖 Documentation</a> •
-  <a href="https://github.com/LessUp/tiny-llm/releases">📦 Releases</a> •
-  <a href="https://github.com/LessUp/tiny-llm/issues">🐛 Issues</a> •
-  <a href="https://github.com/LessUp/tiny-llm/discussions">💬 Discussions</a>
-</p>
+## License
 
-<p align="center">
-  <em>Made with ❤️ by the Tiny-LLM team</em>
-</p>
+Tiny-LLM is released under the [MIT License](LICENSE).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 8a8f2ff..ae3295d 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -1,6 +1,6 @@
 # Tiny-LLM 推理引擎
 
-> 轻量级、高性能 CUDA C++ Transformer 模型推理引擎。
+> 面向聚焦型 Transformer 部署场景的 CUDA 原生 C++ 推理引擎。
 
 [![CI](https://github.com/LessUp/tiny-llm/actions/workflows/ci.yml/badge.svg)](https://github.com/LessUp/tiny-llm/actions/workflows/ci.yml)
 [![Pages](https://github.com/LessUp/tiny-llm/actions/workflows/pages.yml/badge.svg)](https://lessup.github.io/tiny-llm/)
@@ -10,235 +10,103 @@
 ![C++](https://img.shields.io/badge/C%2B%2B-17-00599C?logo=c%2B%2B&logoColor=white)
 ![CMake](https://img.shields.io/badge/CMake-3.18+-064F8C?logo=cmake&logoColor=white)
 
-[English](README.md) • 简体中文 • [文档](https://lessup.github.io/tiny-llm/) • [API 参考](https://lessup.github.io/tiny-llm/docs/zh/API)
+[English](README.md) • [简体中文](README.zh-CN.md) • [文档](https://lessup.github.io/tiny-llm/) • [架构说明](https://lessup.github.io/tiny-llm/docs/zh/ARCHITECTURE) • [更新日志](https://lessup.github.io/tiny-llm/changelog/)
 
 ---
 
-## 🎯 概述
+## 项目概述
 
-Tiny-LLM 是一个为 NVIDIA GPU 设计的高性能 CUDA C++ 推理引擎，专注于高效的 Transformer 模型部署：
+Tiny-LLM 是一个面向 NVIDIA GPU 的轻量级 Transformer 推理引擎，围绕一套聚焦的 CUDA/C++ 技术栈构建：W8A16 量化、显式 KV Cache 管理、手工优化的 CUDA Kernel，以及用来约束仓库演进的 OpenSpec 工作流。
 
-- **显存减少 ~50%** — 通过 W8A16 量化（INT8 权重 + FP16 激活）
-- **高效 KV 缓存** — 支持长文本生成的缓存管理
-- **优化的 CUDA Kernel** — 支持 Tensor Core
-- **零运行时依赖** — 纯 CUDA C++，无需重型框架
+## 为什么是 Tiny-LLM
 
-为需要**快速、可预测、可移植** LLM 推理的开发者而打造。
+- **W8A16 量化路径**：INT8 权重 + FP16 激活
+- **显式 KV Cache 管理**：适合增量解码
+- **CUDA 原生 Kernel**：共享内存与 warp 级优化模式
+- **运行时依赖面很小**：主要运行时依赖为 `spdlog`
+- **OpenSpec 驱动开发**：让架构、文档和改动保持同步
 
----
-
-## ✨ 核心特性
-
-| 特性 | 说明 | 状态 |
-|---------|-------------|--------|
-| **W8A16 量化** | INT8 权重 + FP16 激活，显存减少约 50% | ✅ 稳定 |
-| **KV 缓存管理** | 高效的增量解码与序列管理 | ✅ 稳定 |
-| **优化 CUDA Kernel** | Tensor Core INT8、共享内存 tiling、warp shuffle | ✅ 稳定 |
-| **多采样策略** | 贪婪、温度、Top-k、Top-p (核) 解码 | ✅ 稳定 |
-| **Result<T> 错误处理** | 单子错误处理 — 不用异常控制流 | ✅ 稳定 |
-| **完整测试** | GoogleTest 单元测试 + RapidCheck 基于属性的测试 | ✅ 稳定 |
-| **双语文档** | 完整的中英文文档 | ✅ 完成 |
-
-### 路线图
-
-| 特性 | 状态 | 目标版本 |
-|---------|--------|--------|
-| GGUF 运行时加载 | 🚧 进行中 | v2.1 |
-| PagedAttention | 📋 计划中 | v2.2 |
-| 投机解码 | 🔬 研究中 | v2.3 |
-| FP8 支持 | 🔬 研究中 | v3.0 |
-| 多 GPU 并行 | 📋 计划中 | v3.0 |
-
----
-
-## ⚡ 性能
-
-基于 **NVIDIA A100-80GB** (SM 8.0)，CUDA 12.4 测试：
-
-| 模型 | 批大小 | Tokens/秒 | 显存使用 | 相比 FP16 加速 |
-|-------|-----------|------------|--------------|-----------------|
-| LLaMA-7B | 1 | ~45 t/s | ~3.5 GB | **1.8x** |
-| LLaMA-7B | 4 | ~120 t/s | ~12 GB | **1.6x** |
-| LLaMA-13B | 1 | ~25 t/s | ~6.5 GB | **1.7x** |
-
-> 完整性能基准测试：[性能基准](https://lessup.github.io/tiny-llm/docs/zh/BENCHMARKS)
+## 核心能力
 
----
-
-## 🚀 快速开始
+| 能力 | 说明 | 状态 |
+|---|---|---|
+| W8A16 推理路径 | 量化权重、FP16 激活、CUDA Kernel | 稳定 |
+| KV Cache 管理 | 序列分配、增长和释放 | 稳定 |
+| 采样工具 | Greedy、temperature、top-k、top-p | 稳定 |
+| 错误处理 | 基于 `Result<T>` 的可失败 API | 稳定 |
+| 测试策略 | GoogleTest + RapidCheck 覆盖核心路径 | 持续维护 |
 
-### 系统要求
+## 从源码构建
 
-| 组件 | 最低配置 | 推荐配置 |
-|-----------|---------|-------------|
-| NVIDIA GPU | SM 7.0 (Volta) | SM 8.0+ (Ampere+) |
-| CUDA Toolkit | 11.0 | 12.0+ |
-| CMake | 3.18 | 3.25+ |
-| C++ 编译器 | GCC 9+ / Clang 10+ | GCC 11+ |
+Tiny-LLM 需要可用的 CUDA 工具链（`nvcc` 在 `PATH` 中，或已正确配置的 CUDA 安装）。
 
-### 从源码构建
+| 组件 | 最低要求 |
+|---|---|
+| NVIDIA GPU | 计算能力 7.0+ |
+| CUDA Toolkit | 11.0+ |
+| CMake | 3.18+ |
+| C++ 编译器 | GCC 9+ 或 Clang 10+ |
 
 ```bash
-# 克隆并构建
 git clone https://github.com/LessUp/tiny-llm.git
 cd tiny-llm
-mkdir build && cd build
-cmake .. -DCMAKE_BUILD_TYPE=Release
-make -j$(nproc)
 
-# 运行测试
-ctest --output-on-failure
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
+cmake --build build -j$(nproc)
+ctest --test-dir build --output-on-failure --timeout 300
 ```
 
-### 使用示例
+## 最小使用示例
 
 ```cpp
 #include <tiny_llm/inference_engine.h>
 
 int main() {
-    // 配置模型
     ModelConfig config;
     config.vocab_size = 32000;
     config.hidden_dim = 4096;
     config.num_layers = 32;
 
-    // 加载 W8A16 权重
     auto engine = InferenceEngine::load("model.bin", config).value();
 
-    // 生成文本
     GenerationConfig gen;
     gen.max_new_tokens = 256;
     gen.temperature = 0.7f;
     gen.top_p = 0.9f;
 
     auto output = engine.generate({1, 15043, 29892}, gen);
-    for (int token : output.tokens) {
-        std::cout << tokenizer.decode(token);
-    }
+    (void)output;
 }
 ```
 
----
-
-## 🏗️ 架构
-
-```mermaid
-graph LR
-    A[应用程序] --> B[InferenceEngine]
-    B --> C[ModelLoader]
-    B --> D[KVCacheManager]
-    B --> E[TransformerLayer]
-    C --> F[(W8A16 权重)]
-    D --> G[GPU 显存]
-    E --> H[W8A16 MatMul]
-    E --> I[Attention]
-    E --> J[RMSNorm]
-    E --> K[Elementwise]
-    H --> L[Tensor Core]
-    I --> L
-```
-
-### 核心组件
-
-| 组件 | 职责 |
-|-----------|---------------|
-| **InferenceEngine** | 主入口 — 协调加载、生成和采样 |
-| **ModelLoader** | 将量化权重从二进制格式加载到 GPU 显存 |
-| **KVCacheManager** | 管理键值缓存，支持序列分配和驱逐 |
-| **TransformerLayer** | 单个 Transformer 层的前向传播 |
-| **W8A16 MatMul** | 使用 INT8 × FP16 的量化矩阵乘法 |
-
----
-
-## 📁 项目结构
-
-```
-tiny-llm/
-├── website/               # GitHub Pages 网站 (Jekyll)
-│   ├── docs/              # 文档 (中英)
-│   ├── changelog/         # 版本历史
-│   ├── assets/            # CSS, JS, 图片
-│   └── _config.yml        # Jekyll 配置
-├── specs/                 # 规范驱动开发文档
-│   ├── product/           # 功能需求
-│   ├── rfc/               # 架构决策
-│   ├── api/               # API 定义
-│   └── testing/           # BDD 测试规范
-├── include/tiny_llm/      # 公共头文件
-├── kernels/               # CUDA kernels (.cu, .cuh)
-├── src/                   # 主机端实现 (.cpp)
-├── tests/                 # 单元测试和属性测试
-├── CMakeLists.txt         # 构建配置
-└── README.md              # 本文件
-```
-
----
-
-## 🔌 GPU 支持
-
-| 架构 | 计算能力 | 状态 | 说明 |
-|--------------|-------------------|--------|-------|
-| Volta | SM 7.0, 7.5 | ✅ 支持 | 可用 Tensor Core INT8 |
-| Turing | SM 7.5 | ✅ 支持 | 改进的 INT8 性能 |
-| Ampere | SM 8.0, 8.6 | ✅ 优化 | 最佳性能 |
-| Ada Lovelace | SM 8.9 | ✅ 优化 | 完整功能支持 |
-| Hopper | SM 9.0 | ✅ 支持 | FP8 就绪 |
-
----
-
-## 🤝 贡献
-
-我们欢迎贡献！Tiny-LLM 遵循**规范驱动开发** — 规范先于代码。
-
-### 快速开始
+## 仓库结构
 
-```bash
-# Fork 并克隆
-git clone https://github.com/your-username/tiny-llm.git
-cd tiny-llm
-
-# 构建（含测试）
-mkdir build && cd build
-cmake .. -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
-make -j$(nproc)
-
-# 运行检查
-ctest --output-on-failure
+```text
+openspec/                 当前规范、活跃变更、归档变更、schemas
+include/tiny_llm/         公共头文件
+src/                      主机端 C++ 实现
+kernels/                  CUDA kernels
+tests/                    单元测试与属性测试
+website/                  GitHub Pages 站点与公开文档
+.github/workflows/        CI、Pages、release 自动化
 ```
 
-### 贡献方式
-
-| 类型 | 方式 |
-|------|-----|
-| 🐛 **Bug 报告** | [提交 Issue](https://github.com/LessUp/tiny-llm/issues)，附复现步骤 |
-| 💡 **功能请求** | [发起讨论](https://github.com/LessUp/tiny-llm/discussions) |
-| 🔧 **代码贡献** | Fork → 分支 → PR (遵循 [CONTRIBUTING.md](CONTRIBUTING.md)) |
-| 📝 **文档改进** | 完善 `website/docs/` 中的文档 |
-| 🧪 **测试补充** | 添加单元测试或基于属性的测试 |
+## 文档与规范
 
----
+- **项目主页：** https://lessup.github.io/tiny-llm/
+- **架构说明：** https://lessup.github.io/tiny-llm/docs/zh/ARCHITECTURE
+- **开发者指南：** https://lessup.github.io/tiny-llm/docs/zh/DEVELOPER
+- **OpenSpec 规范源：** `openspec/specs/`
+- **变更历史：** `openspec/changes/`
 
-## 📜 许可证
+## 参与贡献
 
-本项目采用 [MIT 许可证](LICENSE)。
+Tiny-LLM 对非平凡改动采用 OpenSpec-first 工作流。
 
----
-
-## 🙏 致谢
-
-- 灵感来源于 [llama.cpp](https://github.com/ggerganov/llama.cpp) 和 [vLLM](https://github.com/vllm-project/vllm)
-- 测试使用 [GoogleTest](https://github.com/google/googletest) 和 [RapidCheck](https://github.com/emil-e/rapidcheck)
-- 由 [Tiny-LLM 贡献者们](https://github.com/LessUp/tiny-llm/graphs/contributors) 用 ❤️ 打造
-
----
+- 先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)
+- 再阅读仓库级约束 [AGENTS.md](AGENTS.md)
+- 通过 `/opsx:propose`、`/opsx:apply`、`/opsx:archive` 进行结构化开发
 
-<p align="center">
-  <a href="https://lessup.github.io/tiny-llm/">📖 文档</a> •
-  <a href="https://github.com/LessUp/tiny-llm/releases">📦 发布</a> •
-  <a href="https://github.com/LessUp/tiny-llm/issues">🐛 问题</a> •
-  <a href="https://github.com/LessUp/tiny-llm/discussions">💬 讨论</a>
-</p>
+## 许可证
 
-<p align="center">
-  <em>由 Tiny-LLM 团队用 ❤️ 制作</em>
-</p>
+Tiny-LLM 采用 [MIT License](LICENSE)。

From 3d376eaed8de32b8602c1aeed4cc909118422247 Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 02:52:03 +0800
Subject: [PATCH 4/6] style: apply consistent formatting to C++/CUDA source
 files

- Reformat all headers, source files, and tests with clang-format
- Standardize code style across the codebase
- Minor CMakeLists.txt formatting update
---
 CMakeLists.txt                      |    2 +-
 include/tiny_llm/cuda_streams.h     |  198 +++--
 include/tiny_llm/cuda_utils.h       |  304 ++++---
 include/tiny_llm/gguf_parser.h      |  349 ++++----
 include/tiny_llm/inference_engine.h |  113 ++-
 include/tiny_llm/kv_cache.h         |  122 +--
 include/tiny_llm/logger.h           |  134 ++-
 include/tiny_llm/model_loader.h     |   49 +-
 include/tiny_llm/result.h           |  152 ++--
 include/tiny_llm/transformer.h      |  118 ++-
 include/tiny_llm/types.h            |  165 ++--
 include/tiny_llm/validator.h        |  519 ++++++------
 kernels/attention.cu                |  643 +++++++--------
 kernels/attention.cuh               |   28 +-
 kernels/elementwise.cu              |  110 ++-
 kernels/elementwise.cuh             |   11 +-
 kernels/rmsnorm.cu                  |  367 ++++-----
 kernels/rmsnorm.cuh                 |   17 +-
 kernels/w8a16_matmul.cu             |  356 ++++----
 kernels/w8a16_matmul.cuh            |   15 +-
 kernels/warp_utils.cuh              |  137 ++-
 src/gguf_parser.cpp                 |  930 ++++++++++-----------
 src/inference_engine.cpp            |  861 ++++++++++---------
 src/kv_cache.cpp                    |  456 +++++-----
 src/logger.cpp                      |  130 ++-
 src/main.cpp                        |  101 +--
 src/model_loader.cpp                | 1085 ++++++++++++------------
 src/transformer.cpp                 |  494 ++++++-----
 src/types.cpp                       |    2 +-
 tests/test_cuda_utils.cpp           |  238 +++---
 tests/test_inference_engine.cu      |  641 +++++++-------
 tests/test_integration.cu           |  502 ++++++-----
 tests/test_kernels.cu               | 1191 +++++++++++++--------------
 tests/test_kv_cache.cpp             |  355 ++++----
 tests/test_main.cpp                 |    4 +-
 tests/test_model_loader.cpp         |  374 +++++----
 tests/test_transformer.cu           |  730 ++++++++--------
 tests/test_types.cpp                |  181 ++--
 tests/test_w8a16_matmul.cu          |  573 +++++++------
 39 files changed, 6237 insertions(+), 6520 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index c3d80d8..1a354b1 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.18)
 project(tiny-llm
-    VERSION 2.0.0
+    VERSION 2.0.1
     DESCRIPTION "Lightweight LLM inference engine with W8A16 quantization"
     LANGUAGES CXX
 )
diff --git a/include/tiny_llm/cuda_streams.h b/include/tiny_llm/cuda_streams.h
index 73d4b97..7ff1cd9 100644
--- a/include/tiny_llm/cuda_streams.h
+++ b/include/tiny_llm/cuda_streams.h
@@ -9,131 +9,127 @@ namespace tiny_llm {
 
 // CUDA Stream pool for overlapping computation and memory transfers
 class StreamPool {
-public:
-  explicit StreamPool(int num_streams = 4) : num_streams_(num_streams) {
-    streams_.resize(num_streams);
-    for (int i = 0; i < num_streams; ++i) {
-      CUDA_CHECK(cudaStreamCreate(&streams_[i]));
+  public:
+    explicit StreamPool(int num_streams = 4) : num_streams_(num_streams) {
+        streams_.resize(num_streams);
+        for (int i = 0; i < num_streams; ++i) {
+            CUDA_CHECK(cudaStreamCreate(&streams_[i]));
+        }
     }
-  }
 
-  ~StreamPool() {
-    for (auto &stream : streams_) {
-      if (stream) {
-        cudaStreamDestroy(stream);
-      }
+    ~StreamPool() {
+        for (auto &stream : streams_) {
+            if (stream) {
+                cudaStreamDestroy(stream);
+            }
+        }
     }
-  }
-
-  // Non-copyable
-  StreamPool(const StreamPool &) = delete;
-  StreamPool &operator=(const StreamPool &) = delete;
-
-  // Move constructible
-  StreamPool(StreamPool &&other) noexcept
-      : streams_(std::move(other.streams_)), num_streams_(other.num_streams_),
-        current_idx_(other.current_idx_) {
-    other.num_streams_ = 0;
-    other.current_idx_ = 0;
-  }
-
-  // Get next stream in round-robin fashion
-  cudaStream_t getStream() {
-    cudaStream_t stream = streams_[current_idx_];
-    current_idx_ = (current_idx_ + 1) % num_streams_;
-    return stream;
-  }
-
-  // Get specific stream
-  cudaStream_t getStream(int idx) const { return streams_[idx % num_streams_]; }
-
-  // Synchronize all streams
-  void synchronizeAll() {
-    for (auto &stream : streams_) {
-      CUDA_CHECK(cudaStreamSynchronize(stream));
+
+    // Non-copyable
+    StreamPool(const StreamPool &) = delete;
+    StreamPool &operator=(const StreamPool &) = delete;
+
+    // Move constructible
+    StreamPool(StreamPool &&other) noexcept
+        : streams_(std::move(other.streams_)), num_streams_(other.num_streams_),
+          current_idx_(other.current_idx_) {
+        other.num_streams_ = 0;
+        other.current_idx_ = 0;
+    }
+
+    // Get next stream in round-robin fashion
+    cudaStream_t getStream() {
+        cudaStream_t stream = streams_[current_idx_];
+        current_idx_ = (current_idx_ + 1) % num_streams_;
+        return stream;
+    }
+
+    // Get specific stream
+    cudaStream_t getStream(int idx) const { return streams_[idx % num_streams_]; }
+
+    // Synchronize all streams
+    void synchronizeAll() {
+        for (auto &stream : streams_) {
+            CUDA_CHECK(cudaStreamSynchronize(stream));
+        }
     }
-  }
 
-  // Get number of streams
-  int numStreams() const { return num_streams_; }
+    // Get number of streams
+    int numStreams() const { return num_streams_; }
 
-private:
-  std::vector<cudaStream_t> streams_;
-  int num_streams_;
-  int current_idx_ = 0;
+  private:
+    std::vector<cudaStream_t> streams_;
+    int                       num_streams_;
+    int                       current_idx_ = 0;
 };
 
 // CUDA Event for timing and synchronization
 class CudaEvent {
-public:
-  CudaEvent() { CUDA_CHECK(cudaEventCreate(&event_)); }
+  public:
+    CudaEvent() { CUDA_CHECK(cudaEventCreate(&event_)); }
 
-  ~CudaEvent() {
-    if (event_) {
-      cudaEventDestroy(event_);
+    ~CudaEvent() {
+        if (event_) {
+            cudaEventDestroy(event_);
+        }
     }
-  }
 
-  // Non-copyable
-  CudaEvent(const CudaEvent &) = delete;
-  CudaEvent &operator=(const CudaEvent &) = delete;
+    // Non-copyable
+    CudaEvent(const CudaEvent &) = delete;
+    CudaEvent &operator=(const CudaEvent &) = delete;
 
-  // Move constructible
-  CudaEvent(CudaEvent &&other) noexcept : event_(other.event_) {
-    other.event_ = nullptr;
-  }
+    // Move constructible
+    CudaEvent(CudaEvent &&other) noexcept : event_(other.event_) { other.event_ = nullptr; }
 
-  void record(cudaStream_t stream = 0) {
-    CUDA_CHECK(cudaEventRecord(event_, stream));
-  }
+    void record(cudaStream_t stream = 0) { CUDA_CHECK(cudaEventRecord(event_, stream)); }
 
-  void synchronize() { CUDA_CHECK(cudaEventSynchronize(event_)); }
+    void synchronize() { CUDA_CHECK(cudaEventSynchronize(event_)); }
 
-  // Elapsed time in milliseconds between two events
-  static float elapsedMs(const CudaEvent &start, const CudaEvent &end) {
-    float ms = 0.0f;
-    CUDA_CHECK(cudaEventElapsedTime(&ms, start.event_, end.event_));
-    return ms;
-  }
+    // Elapsed time in milliseconds between two events
+    static float elapsedMs(const CudaEvent &start, const CudaEvent &end) {
+        float ms = 0.0f;
+        CUDA_CHECK(cudaEventElapsedTime(&ms, start.event_, end.event_));
+        return ms;
+    }
 
-  cudaEvent_t get() const { return event_; }
+    cudaEvent_t get() const { return event_; }
 
-private:
-  cudaEvent_t event_ = nullptr;
+  private:
+    cudaEvent_t event_ = nullptr;
 };
 
 // Performance configuration for kernel launches
 struct KernelConfig {
-  int block_size = 256;
-  int max_blocks = 65535;
-  int shared_mem_size = 0;
-  bool use_cooperative_groups = false;
-
-  // Auto-tune block size based on kernel requirements
-  static KernelConfig autoTune(int elements, int min_threads_per_block = 32) {
-    KernelConfig config;
-
-    // Choose block size based on element count
-    if (elements <= 256) {
-      config.block_size = 64;
-    } else if (elements <= 1024) {
-      config.block_size = 128;
-    } else if (elements <= 4096) {
-      config.block_size = 256;
-    } else {
-      config.block_size = 512;
+    int  block_size = 256;
+    int  max_blocks = 65535;
+    int  shared_mem_size = 0;
+    bool use_cooperative_groups = false;
+
+    // Auto-tune block size based on kernel requirements
+    static KernelConfig autoTune(int elements, int min_threads_per_block = 32) {
+        KernelConfig config;
+
+        // Choose block size based on element count
+        if (elements <= 256) {
+            config.block_size = 64;
+        } else if (elements <= 1024) {
+            config.block_size = 128;
+        } else if (elements <= 4096) {
+            config.block_size = 256;
+        } else {
+            config.block_size = 512;
+        }
+
+        // Ensure minimum threads
+        config.block_size = std::max(config.block_size, min_threads_per_block);
+
+        return config;
     }
-
-    // Ensure minimum threads
-    config.block_size = std::max(config.block_size, min_threads_per_block);
-
-    return config;
-  }
 };
 
 // Memory coalescing helper
 inline size_t alignTo(size_t size, size_t alignment) {
-  return (size + alignment - 1) & ~(alignment - 1);
+    return (size + alignment - 1) & ~(alignment - 1);
 }
 
 // Optimal alignment for GPU memory (128 bytes for coalesced access)
@@ -141,10 +137,10 @@ constexpr size_t GPU_MEMORY_ALIGNMENT = 128;
 
 // Aligned memory allocation
 inline void *allocateAligned(size_t size) {
-  void *ptr = nullptr;
-  size_t aligned_size = alignTo(size, GPU_MEMORY_ALIGNMENT);
-  CUDA_CHECK(cudaMalloc(&ptr, aligned_size));
-  return ptr;
+    void  *ptr = nullptr;
+    size_t aligned_size = alignTo(size, GPU_MEMORY_ALIGNMENT);
+    CUDA_CHECK(cudaMalloc(&ptr, aligned_size));
+    return ptr;
 }
 
 } // namespace tiny_llm
diff --git a/include/tiny_llm/cuda_utils.h b/include/tiny_llm/cuda_utils.h
index 50b7432..5a9b576 100644
--- a/include/tiny_llm/cuda_utils.h
+++ b/include/tiny_llm/cuda_utils.h
@@ -11,193 +11,191 @@
 namespace tiny_llm {
 
 // CUDA error checking macro (throws exception)
-#define CUDA_CHECK(call)                                                       \
-  do {                                                                         \
-    cudaError_t err = call;                                                    \
-    if (err != cudaSuccess) {                                                  \
-      throw tiny_llm::CudaException(err, __FILE__, __LINE__);                  \
-    }                                                                          \
-  } while (0)
+#define CUDA_CHECK(call)                                                                           \
+    do {                                                                                           \
+        cudaError_t err = call;                                                                    \
+        if (err != cudaSuccess) {                                                                  \
+            throw tiny_llm::CudaException(err, __FILE__, __LINE__);                                \
+        }                                                                                          \
+    } while (0)
 
 // CUDA error checking macro (returns Result<void>)
 // Use in functions that return Result<T>
-#define CUDA_CHECK_RESULT(call)                                                \
-  do {                                                                         \
-    cudaError_t err = call;                                                    \
-    if (err != cudaSuccess) {                                                  \
-      return tiny_llm::Result<void>::err(                                      \
-          std::string("CUDA error at ") + __FILE__ + ":" +                     \
-          std::to_string(__LINE__) + ": " + cudaGetErrorString(err));          \
-    }                                                                          \
-  } while (0)
+#define CUDA_CHECK_RESULT(call)                                                                    \
+    do {                                                                                           \
+        cudaError_t err = call;                                                                    \
+        if (err != cudaSuccess) {                                                                  \
+            return tiny_llm::Result<void>::err(std::string("CUDA error at ") + __FILE__ + ":" +    \
+                                               std::to_string(__LINE__) + ": " +                   \
+                                               cudaGetErrorString(err));                           \
+        }                                                                                          \
+    } while (0)
 
 // CUDA error checking for destructors (logs error, doesn't throw)
 // Requires TLLM_ERROR macro from logger.h to be available
-#define CUDA_CHECK_DESTROY(call)                                               \
-  do {                                                                         \
-    cudaError_t err = call;                                                    \
-    if (err != cudaSuccess) {                                                  \
-      /* Log error but don't throw in destructor */                            \
-      fprintf(stderr, "CUDA error in destructor at %s:%d: %s\n",               \
-              __FILE__, __LINE__, cudaGetErrorString(err));                    \
-    }                                                                          \
-  } while (0)
+#define CUDA_CHECK_DESTROY(call)                                                                   \
+    do {                                                                                           \
+        cudaError_t err = call;                                                                    \
+        if (err != cudaSuccess) {                                                                  \
+            /* Log error but don't throw in destructor */                                          \
+            fprintf(stderr, "CUDA error in destructor at %s:%d: %s\n", __FILE__, __LINE__,         \
+                    cudaGetErrorString(err));                                                      \
+        }                                                                                          \
+    } while (0)
 
 // CUDA exception class
 class CudaException : public std::exception {
-public:
-  CudaException(cudaError_t err, const char *file, int line)
-      : error_(err), file_(file), line_(line) {
-    std::ostringstream oss;
-    oss << "CUDA error " << static_cast<int>(err) << " at " << file << ":"
-        << line << ": " << cudaGetErrorString(err);
-    message_ = oss.str();
-  }
-
-  const char *what() const noexcept override { return message_.c_str(); }
-
-  cudaError_t error() const { return error_; }
-  const char *file() const { return file_; }
-  int line() const { return line_; }
-
-private:
-  cudaError_t error_;
-  const char *file_;
-  int line_;
-  std::string message_;
+  public:
+    CudaException(cudaError_t err, const char *file, int line)
+        : error_(err), file_(file), line_(line) {
+        std::ostringstream oss;
+        oss << "CUDA error " << static_cast<int>(err) << " at " << file << ":" << line << ": "
+            << cudaGetErrorString(err);
+        message_ = oss.str();
+    }
+
+    const char *what() const noexcept override { return message_.c_str(); }
+
+    cudaError_t error() const { return error_; }
+    const char *file() const { return file_; }
+    int         line() const { return line_; }
+
+  private:
+    cudaError_t error_;
+    const char *file_;
+    int         line_;
+    std::string message_;
 };
 
 // GPU memory info helper
 struct MemoryInfo {
-  size_t free;
-  size_t total;
-  size_t used;
+    size_t free;
+    size_t total;
+    size_t used;
 };
 
 inline MemoryInfo getGPUMemoryInfo() {
-  MemoryInfo info;
-  CUDA_CHECK(cudaMemGetInfo(&info.free, &info.total));
-  info.used = info.total - info.free;
-  return info;
+    MemoryInfo info;
+    CUDA_CHECK(cudaMemGetInfo(&info.free, &info.total));
+    info.used = info.total - info.free;
+    return info;
 }
 
 // CUDA stream wrapper
 class CudaStream {
-public:
-  CudaStream() { CUDA_CHECK(cudaStreamCreate(&stream_)); }
-
-  ~CudaStream() {
-    if (stream_) {
-      // Use safe check in destructor (no exceptions)
-      cudaError_t err = cudaStreamDestroy(stream_);
-      if (err != cudaSuccess) {
-        // Log error but don't throw in destructor
-        fprintf(stderr, "CUDA error in CudaStream destructor: %s\n",
-                cudaGetErrorString(err));
-      }
+  public:
+    CudaStream() { CUDA_CHECK(cudaStreamCreate(&stream_)); }
+
+    ~CudaStream() {
+        if (stream_) {
+            // Use safe check in destructor (no exceptions)
+            cudaError_t err = cudaStreamDestroy(stream_);
+            if (err != cudaSuccess) {
+                // Log error but don't throw in destructor
+                fprintf(stderr, "CUDA error in CudaStream destructor: %s\n",
+                        cudaGetErrorString(err));
+            }
+        }
     }
-  }
-
-  // Non-copyable
-  CudaStream(const CudaStream &) = delete;
-  CudaStream &operator=(const CudaStream &) = delete;
-
-  // Movable
-  CudaStream(CudaStream &&other) noexcept : stream_(other.stream_) {
-    other.stream_ = nullptr;
-  }
-
-  CudaStream &operator=(CudaStream &&other) noexcept {
-    if (this != &other) {
-      if (stream_) {
-        cudaError_t err = cudaStreamDestroy(stream_);
-        if (err != cudaSuccess) {
-          fprintf(stderr, "CUDA error in CudaStream move assignment: %s\n",
-                  cudaGetErrorString(err));
+
+    // Non-copyable
+    CudaStream(const CudaStream &) = delete;
+    CudaStream &operator=(const CudaStream &) = delete;
+
+    // Movable
+    CudaStream(CudaStream &&other) noexcept : stream_(other.stream_) { other.stream_ = nullptr; }
+
+    CudaStream &operator=(CudaStream &&other) noexcept {
+        if (this != &other) {
+            if (stream_) {
+                cudaError_t err = cudaStreamDestroy(stream_);
+                if (err != cudaSuccess) {
+                    fprintf(stderr, "CUDA error in CudaStream move assignment: %s\n",
+                            cudaGetErrorString(err));
+                }
+            }
+            stream_ = other.stream_;
+            other.stream_ = nullptr;
         }
-      }
-      stream_ = other.stream_;
-      other.stream_ = nullptr;
+        return *this;
     }
-    return *this;
-  }
 
-  cudaStream_t get() const { return stream_; }
-  operator cudaStream_t() const { return stream_; }
+    cudaStream_t get() const { return stream_; }
+    operator cudaStream_t() const { return stream_; }
 
-  void synchronize() { CUDA_CHECK(cudaStreamSynchronize(stream_)); }
+    void synchronize() { CUDA_CHECK(cudaStreamSynchronize(stream_)); }
 
-private:
-  cudaStream_t stream_ = nullptr;
+  private:
+    cudaStream_t stream_ = nullptr;
 };
 
 // Device memory RAII wrapper
-template <typename T> class DeviceBuffer {
-public:
-  DeviceBuffer() = default;
+template <typename T>
+class DeviceBuffer {
+  public:
+    DeviceBuffer() = default;
+
+    explicit DeviceBuffer(size_t count) : count_(count) {
+        if (count > 0) {
+            CUDA_CHECK(cudaMalloc(&data_, count * sizeof(T)));
+        }
+    }
 
-  explicit DeviceBuffer(size_t count) : count_(count) {
-    if (count > 0) {
-      CUDA_CHECK(cudaMalloc(&data_, count * sizeof(T)));
+    ~DeviceBuffer() {
+        if (data_) {
+            cudaError_t err = cudaFree(data_);
+            if (err != cudaSuccess) {
+                fprintf(stderr, "CUDA error in DeviceBuffer destructor: %s\n",
+                        cudaGetErrorString(err));
+            }
+        }
     }
-  }
-
-  ~DeviceBuffer() {
-    if (data_) {
-      cudaError_t err = cudaFree(data_);
-      if (err != cudaSuccess) {
-        fprintf(stderr, "CUDA error in DeviceBuffer destructor: %s\n",
-                cudaGetErrorString(err));
-      }
+
+    // Non-copyable
+    DeviceBuffer(const DeviceBuffer &) = delete;
+    DeviceBuffer &operator=(const DeviceBuffer &) = delete;
+
+    // Movable
+    DeviceBuffer(DeviceBuffer &&other) noexcept : data_(other.data_), count_(other.count_) {
+        other.data_ = nullptr;
+        other.count_ = 0;
     }
-  }
-
-  // Non-copyable
-  DeviceBuffer(const DeviceBuffer &) = delete;
-  DeviceBuffer &operator=(const DeviceBuffer &) = delete;
-
-  // Movable
-  DeviceBuffer(DeviceBuffer &&other) noexcept
-      : data_(other.data_), count_(other.count_) {
-    other.data_ = nullptr;
-    other.count_ = 0;
-  }
-
-  DeviceBuffer &operator=(DeviceBuffer &&other) noexcept {
-    if (this != &other) {
-      if (data_) {
-        cudaError_t err = cudaFree(data_);
-        if (err != cudaSuccess) {
-          fprintf(stderr, "CUDA error in DeviceBuffer move assignment: %s\n",
-                  cudaGetErrorString(err));
+
+    DeviceBuffer &operator=(DeviceBuffer &&other) noexcept {
+        if (this != &other) {
+            if (data_) {
+                cudaError_t err = cudaFree(data_);
+                if (err != cudaSuccess) {
+                    fprintf(stderr, "CUDA error in DeviceBuffer move assignment: %s\n",
+                            cudaGetErrorString(err));
+                }
+            }
+            data_ = other.data_;
+            count_ = other.count_;
+            other.data_ = nullptr;
+            other.count_ = 0;
         }
-      }
-      data_ = other.data_;
-      count_ = other.count_;
-      other.data_ = nullptr;
-      other.count_ = 0;
+        return *this;
     }
-    return *this;
-  }
-
-  T *data() { return data_; }
-  const T *data() const { return data_; }
-  size_t size() const { return count_; }
-  size_t bytes() const { return count_ * sizeof(T); }
-
-  void copyFromHost(const T *host_data, size_t count, cudaStream_t stream = 0) {
-    CUDA_CHECK(cudaMemcpyAsync(data_, host_data, count * sizeof(T),
-                               cudaMemcpyHostToDevice, stream));
-  }
-
-  void copyToHost(T *host_data, size_t count, cudaStream_t stream = 0) const {
-    CUDA_CHECK(cudaMemcpyAsync(host_data, data_, count * sizeof(T),
-                               cudaMemcpyDeviceToHost, stream));
-  }
-
-private:
-  T *data_ = nullptr;
-  size_t count_ = 0;
+
+    T       *data() { return data_; }
+    const T *data() const { return data_; }
+    size_t   size() const { return count_; }
+    size_t   bytes() const { return count_ * sizeof(T); }
+
+    void copyFromHost(const T *host_data, size_t count, cudaStream_t stream = 0) {
+        CUDA_CHECK(
+            cudaMemcpyAsync(data_, host_data, count * sizeof(T), cudaMemcpyHostToDevice, stream));
+    }
+
+    void copyToHost(T *host_data, size_t count, cudaStream_t stream = 0) const {
+        CUDA_CHECK(
+            cudaMemcpyAsync(host_data, data_, count * sizeof(T), cudaMemcpyDeviceToHost, stream));
+    }
+
+  private:
+    T     *data_ = nullptr;
+    size_t count_ = 0;
 };
 
 } // namespace tiny_llm
diff --git a/include/tiny_llm/gguf_parser.h b/include/tiny_llm/gguf_parser.h
index 22d436c..dbddbcf 100644
--- a/include/tiny_llm/gguf_parser.h
+++ b/include/tiny_llm/gguf_parser.h
@@ -17,124 +17,123 @@ constexpr uint32_t GGUF_MAGIC = 0x46554747; // "GGUF" in little-endian
 
 // GGUF value types (as defined in GGUF spec)
 enum class GGUFType : uint32_t {
-  UINT8 = 0,
-  INT8 = 1,
-  UINT16 = 2,
-  INT16 = 3,
-  UINT32 = 4,
-  INT32 = 5,
-  FLOAT32 = 6,
-  BOOL = 7,
-  STRING = 8,
-  ARRAY = 9,
-  UINT64 = 10,
-  INT64 = 11,
-  FLOAT64 = 12,
+    UINT8 = 0,
+    INT8 = 1,
+    UINT16 = 2,
+    INT16 = 3,
+    UINT32 = 4,
+    INT32 = 5,
+    FLOAT32 = 6,
+    BOOL = 7,
+    STRING = 8,
+    ARRAY = 9,
+    UINT64 = 10,
+    INT64 = 11,
+    FLOAT64 = 12,
 };
 
 // GGML tensor types
 enum class GGMLType : uint32_t {
-  F32 = 0,
-  F16 = 1,
-  Q4_0 = 2,
-  Q4_1 = 3,
-  Q4_2 = 4, // Removed, keep for compatibility
-  Q4_3 = 5, // Removed, keep for compatibility
-  Q5_0 = 6,
-  Q5_1 = 7,
-  Q8_0 = 8,
-  Q8_1 = 9,
-  Q2_K = 10,
-  Q3_K = 11,
-  Q4_K = 12,
-  Q5_K = 13,
-  Q6_K = 14,
-  Q8_K = 15,
-  IQ2_XXS = 16,
-  IQ2_XS = 17,
-  IQ3_XXS = 18,
-  IQ1_S = 19,
-  IQ4_NL = 20,
-  IQ3_S = 21,
-  IQ2_S = 22,
-  IQ4_XS = 23,
-  I8 = 24,
-  I16 = 25,
-  I32 = 26,
-  I64 = 27,
-  F64 = 28,
+    F32 = 0,
+    F16 = 1,
+    Q4_0 = 2,
+    Q4_1 = 3,
+    Q4_2 = 4, // Removed, keep for compatibility
+    Q4_3 = 5, // Removed, keep for compatibility
+    Q5_0 = 6,
+    Q5_1 = 7,
+    Q8_0 = 8,
+    Q8_1 = 9,
+    Q2_K = 10,
+    Q3_K = 11,
+    Q4_K = 12,
+    Q5_K = 13,
+    Q6_K = 14,
+    Q8_K = 15,
+    IQ2_XXS = 16,
+    IQ2_XS = 17,
+    IQ3_XXS = 18,
+    IQ1_S = 19,
+    IQ4_NL = 20,
+    IQ3_S = 21,
+    IQ2_S = 22,
+    IQ4_XS = 23,
+    I8 = 24,
+    I16 = 25,
+    I32 = 26,
+    I64 = 27,
+    F64 = 28,
 };
 
 /**
  * @brief GGUF metadata value (variant type)
  */
-using GGUFValue = std::variant<uint8_t, int8_t, uint16_t, int16_t, uint32_t,
-                               int32_t, uint64_t, int64_t, float, double, bool,
-                               std::string, std::vector<uint8_t>,
-                               std::vector<int8_t>, std::vector<uint16_t>,
-                               std::vector<int16_t>, std::vector<uint32_t>,
-                               std::vector<int32_t>, std::vector<uint64_t>,
-                               std::vector<int64_t>, std::vector<float>,
-                               std::vector<double>, std::vector<std::string>>;
+using GGUFValue =
+    std::variant<uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t, uint64_t, int64_t, float,
+                 double, bool, std::string, std::vector<uint8_t>, std::vector<int8_t>,
+                 std::vector<uint16_t>, std::vector<int16_t>, std::vector<uint32_t>,
+                 std::vector<int32_t>, std::vector<uint64_t>, std::vector<int64_t>,
+                 std::vector<float>, std::vector<double>, std::vector<std::string>>;
 
 /**
  * @brief GGUF metadata container
  */
 struct GGUFMetadata {
-  std::unordered_map<std::string, GGUFValue> kv;
-
-  /**
-   * @brief Check if key exists
-   */
-  bool has(const std::string &key) const;
-
-  /**
-   * @brief Get value with type conversion
-   * @tparam T Expected type
-   * @param key Key to look up
-   * @return Result with value or error
-   */
-  template <typename T> Result<T> get(const std::string &key) const;
-
-  /**
-   * @brief Get value with default
-   * @tparam T Expected type
-   * @param key Key to look up
-   * @param default_value Default if not found
-   * @return Value or default
-   */
-  template <typename T>
-  T getOr(const std::string &key, T default_value) const;
+    std::unordered_map<std::string, GGUFValue> kv;
+
+    /**
+     * @brief Check if key exists
+     */
+    bool has(const std::string &key) const;
+
+    /**
+     * @brief Get value with type conversion
+     * @tparam T Expected type
+     * @param key Key to look up
+     * @return Result with value or error
+     */
+    template <typename T>
+    Result<T> get(const std::string &key) const;
+
+    /**
+     * @brief Get value with default
+     * @tparam T Expected type
+     * @param key Key to look up
+     * @param default_value Default if not found
+     * @return Value or default
+     */
+    template <typename T>
+    T getOr(const std::string &key, T default_value) const;
 };
 
 /**
  * @brief GGUF tensor information
  */
 struct GGUFTensorInfo {
-  std::string name;
-  std::vector<uint64_t> dimensions;
-  GGMLType type;
-  uint64_t offset;
-
-  /**
-   * @brief Calculate tensor size in bytes
-   */
-  size_t calculateSize() const;
-
-  /**
-   * @brief Get number of elements
-   */
-  size_t numElements() const;
+    std::string           name;
+    std::vector<uint64_t> dimensions;
+    GGMLType              type;
+    uint64_t              offset;
+
+    /**
+     * @brief Calculate tensor size in bytes
+     */
+    size_t calculateSize() const;
+
+    /**
+     * @brief Get number of elements
+     */
+    size_t numElements() const;
 };
 
 /**
  * @brief GGUF file header
  */
 struct GGUFHeader {
-  uint32_t magic;
-  uint32_t version;
-  uint64_t tensor_count;
-  uint64_t metadata_kv_count;
+    uint32_t magic;
+    uint32_t version;
+    uint64_t tensor_count;
+    uint64_t metadata_kv_count;
 };
 
 /**
@@ -154,100 +153,100 @@ struct GGUFHeader {
  * @endcode
  */
 class GGUFParser {
-public:
-  explicit GGUFParser(const std::string &path);
-
-  /**
-   * @brief Parse the GGUF file
-   * @return Result indicating success or error
-   */
-  Result<void> parse();
-
-  /**
-   * @brief Get the parsed metadata
-   */
-  const GGUFMetadata &getMetadata() const { return metadata_; }
-
-  /**
-   * @brief Get the tensor information
-   */
-  const std::vector<GGUFTensorInfo> &getTensors() const { return tensors_; }
-
-  /**
-   * @brief Get the file header
-   */
-  const GGUFHeader &getHeader() const { return header_; }
-
-  /**
-   * @brief Extract model configuration from metadata
-   * @return ModelConfig or error
-   */
-  Result<ModelConfig> extractModelConfig() const;
-
-  /**
-   * @brief Get tensor by name
-   * @param name Tensor name
-   * @return Pointer to tensor info or nullptr if not found
-   */
-  const GGUFTensorInfo *getTensorByName(const std::string &name) const;
-
-  /**
-   * @brief Read tensor data from file
-   * @param tensor Tensor information
-   * @return Raw tensor data or error
-   */
-  Result<std::vector<uint8_t>> readTensorData(const GGUFTensorInfo &tensor);
-
-  /**
-   * @brief Get the data section offset in file
-   */
-  uint64_t getDataOffset() const { return data_offset_; }
-
-private:
-  // Parse methods
-  Result<void> parseHeader(std::ifstream &file);
-  Result<void> parseMetadata(std::ifstream &file);
-  Result<void> parseTensorInfo(std::ifstream &file);
-
-  // Read methods
-  Result<GGUFValue> readValue(std::ifstream &file, GGUFType type);
-  Result<GGUFValue> readArray(std::ifstream &file);
-  Result<std::string> readString(std::ifstream &file);
-  Result<GGUFTensorInfo> readTensorInfoEntry(std::ifstream &file);
-
-  // Calculate alignment padding
-  uint64_t alignOffset(uint64_t offset) const;
-
-  std::string path_;
-  GGUFHeader header_{};
-  GGUFMetadata metadata_;
-  std::vector<GGUFTensorInfo> tensors_;
-  std::unordered_map<std::string, size_t> tensor_name_map_;
-  uint64_t data_offset_ = 0;
-
-  // Alignment (32 bytes as per GGUF spec)
-  static constexpr uint64_t ALIGNMENT = 32;
+  public:
+    explicit GGUFParser(const std::string &path);
+
+    /**
+     * @brief Parse the GGUF file
+     * @return Result indicating success or error
+     */
+    Result<void> parse();
+
+    /**
+     * @brief Get the parsed metadata
+     */
+    const GGUFMetadata &getMetadata() const { return metadata_; }
+
+    /**
+     * @brief Get the tensor information
+     */
+    const std::vector<GGUFTensorInfo> &getTensors() const { return tensors_; }
+
+    /**
+     * @brief Get the file header
+     */
+    const GGUFHeader &getHeader() const { return header_; }
+
+    /**
+     * @brief Extract model configuration from metadata
+     * @return ModelConfig or error
+     */
+    Result<ModelConfig> extractModelConfig() const;
+
+    /**
+     * @brief Get tensor by name
+     * @param name Tensor name
+     * @return Pointer to tensor info or nullptr if not found
+     */
+    const GGUFTensorInfo *getTensorByName(const std::string &name) const;
+
+    /**
+     * @brief Read tensor data from file
+     * @param tensor Tensor information
+     * @return Raw tensor data or error
+     */
+    Result<std::vector<uint8_t>> readTensorData(const GGUFTensorInfo &tensor);
+
+    /**
+     * @brief Get the data section offset in file
+     */
+    uint64_t getDataOffset() const { return data_offset_; }
+
+  private:
+    // Parse methods
+    Result<void> parseHeader(std::ifstream &file);
+    Result<void> parseMetadata(std::ifstream &file);
+    Result<void> parseTensorInfo(std::ifstream &file);
+
+    // Read methods
+    Result<GGUFValue>      readValue(std::ifstream &file, GGUFType type);
+    Result<GGUFValue>      readArray(std::ifstream &file);
+    Result<std::string>    readString(std::ifstream &file);
+    Result<GGUFTensorInfo> readTensorInfoEntry(std::ifstream &file);
+
+    // Calculate alignment padding
+    uint64_t alignOffset(uint64_t offset) const;
+
+    std::string                             path_;
+    GGUFHeader                              header_{};
+    GGUFMetadata                            metadata_;
+    std::vector<GGUFTensorInfo>             tensors_;
+    std::unordered_map<std::string, size_t> tensor_name_map_;
+    uint64_t                                data_offset_ = 0;
+
+    // Alignment (32 bytes as per GGUF spec)
+    static constexpr uint64_t ALIGNMENT = 32;
 };
 
 // Template implementations
 template <typename T>
 Result<T> GGUFMetadata::get(const std::string &key) const {
-  auto it = kv.find(key);
-  if (it == kv.end()) {
-    return Result<T>::err("Key not found: " + key);
-  }
+    auto it = kv.find(key);
+    if (it == kv.end()) {
+        return Result<T>::err("Key not found: " + key);
+    }
 
-  if (auto *val = std::get_if<T>(&it->second)) {
-    return Result<T>::ok(*val);
-  }
+    if (auto *val = std::get_if<T>(&it->second)) {
+        return Result<T>::ok(*val);
+    }
 
-  return Result<T>::err("Type mismatch for key: " + key);
+    return Result<T>::err("Type mismatch for key: " + key);
 }
 
 template <typename T>
 T GGUFMetadata::getOr(const std::string &key, T default_value) const {
-  auto result = get<T>(key);
-  return result.isOk() ? result.value() : default_value;
+    auto result = get<T>(key);
+    return result.isOk() ? result.value() : default_value;
 }
 
 } // namespace tiny_llm
diff --git a/include/tiny_llm/inference_engine.h b/include/tiny_llm/inference_engine.h
index b22821d..cfcde3a 100644
--- a/include/tiny_llm/inference_engine.h
+++ b/include/tiny_llm/inference_engine.h
@@ -14,84 +14,83 @@ namespace tiny_llm {
 
 // Sampling strategies
 enum class SamplingStrategy {
-  GREEDY,      // argmax
-  TEMPERATURE, // temperature scaling + multinomial
-  TOP_K,       // top-k filtering
-  TOP_P        // nucleus sampling
+    GREEDY,      // argmax
+    TEMPERATURE, // temperature scaling + multinomial
+    TOP_K,       // top-k filtering
+    TOP_P        // nucleus sampling
 };
 
 // Inference engine for LLM text generation
 class InferenceEngine {
-public:
-  // Load model from file
-  static Result<std::unique_ptr<InferenceEngine>>
-  load(const std::string &model_path, const ModelConfig &config);
+  public:
+    // Load model from file
+    static Result<std::unique_ptr<InferenceEngine>> load(const std::string &model_path,
+                                                         const ModelConfig &config);
 
-  // Constructor with pre-loaded weights
-  InferenceEngine(const ModelConfig &config, ModelWeights &&weights);
-  ~InferenceEngine();
+    // Constructor with pre-loaded weights
+    InferenceEngine(const ModelConfig &config, ModelWeights &&weights);
+    ~InferenceEngine();
 
-  // Non-copyable
-  InferenceEngine(const InferenceEngine &) = delete;
-  InferenceEngine &operator=(const InferenceEngine &) = delete;
+    // Non-copyable
+    InferenceEngine(const InferenceEngine &) = delete;
+    InferenceEngine &operator=(const InferenceEngine &) = delete;
 
-  // Generate tokens from prompt
-  // Returns Result<vector<int>> with generated tokens or error
-  Result<std::vector<int>> generate(const std::vector<int> &prompt_tokens,
-                                     const GenerationConfig &config);
+    // Generate tokens from prompt
+    // Returns Result<vector<int>> with generated tokens or error
+    Result<std::vector<int>> generate(const std::vector<int> &prompt_tokens,
+                                      const GenerationConfig &config);
 
-  // Get generation statistics
-  const GenerationStats &getStats() const { return stats_; }
+    // Get generation statistics
+    const GenerationStats &getStats() const { return stats_; }
 
-  // Reset statistics
-  void resetStats() { stats_ = GenerationStats{}; }
+    // Reset statistics
+    void resetStats() { stats_ = GenerationStats{}; }
 
-  // Sampling functions (public for testing)
-  static int sampleGreedy(const half *logits, int vocab_size);
-  static int sampleTemperature(const half *logits, int vocab_size,
-                               float temperature, unsigned seed = 0);
-  static int sampleTopK(const half *logits, int vocab_size, int k,
-                        float temperature, unsigned seed = 0);
-  static int sampleTopP(const half *logits, int vocab_size, float p,
-                        float temperature, unsigned seed = 0);
+    // Sampling functions (public for testing)
+    static int sampleGreedy(const half *logits, int vocab_size);
+    static int sampleTemperature(const half *logits, int vocab_size, float temperature,
+                                 unsigned seed = 0);
+    static int sampleTopK(const half *logits, int vocab_size, int k, float temperature,
+                          unsigned seed = 0);
+    static int sampleTopP(const half *logits, int vocab_size, float p, float temperature,
+                          unsigned seed = 0);
 
-private:
-  // Prefill phase: process all prompt tokens
-  void prefill(const std::vector<int> &tokens, int seq_id);
+  private:
+    // Prefill phase: process all prompt tokens
+    void prefill(const std::vector<int> &tokens, int seq_id);
 
-  // Decode phase: generate one token
-  int decodeStep(int seq_id, int position, int token_id,
-                 const GenerationConfig &config);
+    // Decode phase: generate one token
+    int decodeStep(int seq_id, int position, int token_id, const GenerationConfig &config);
 
-  // Sample from a single hidden state
-  int sampleFromHidden(half *hidden_state, const GenerationConfig &config);
+    // Sample from a single hidden state
+    int sampleFromHidden(half *hidden_state, const GenerationConfig &config);
 
-  // Sample from logits based on config
-  int sample(const half *logits, const GenerationConfig &config);
+    // Sample from logits based on config
+    int sample(const half *logits, const GenerationConfig &config);
 
-  // Embedding lookup
-  void embedTokens(const int *tokens, int num_tokens, half *output);
+    // Embedding lookup
+    void embedTokens(const int *tokens, int num_tokens, half *output);
 
-  // Compute logits from hidden states
-  void computeLogits(const half *hidden_states, int num_tokens, half *logits);
+    // Compute logits from hidden states
+    void computeLogits(const half *hidden_states, int num_tokens, half *logits);
 
-  // Apply RMSNorm
-  void finalNorm(const half *input, half *output, int num_tokens);
+    // Apply RMSNorm
+    void finalNorm(const half *input, half *output, int num_tokens);
 
-  ModelConfig config_;
-  ModelWeights weights_;
-  std::vector<std::unique_ptr<TransformerLayer>> layers_;
-  std::unique_ptr<KVCacheManager> kv_cache_;
+    ModelConfig                                    config_;
+    ModelWeights                                   weights_;
+    std::vector<std::unique_ptr<TransformerLayer>> layers_;
+    std::unique_ptr<KVCacheManager>                kv_cache_;
 
-  // Buffers
-  half *hidden_states_ = nullptr;
-  half *logits_ = nullptr;
+    // Buffers
+    half *hidden_states_ = nullptr;
+    half *logits_ = nullptr;
 
-  // CUDA stream
-  cudaStream_t stream_ = 0;
+    // CUDA stream
+    cudaStream_t stream_ = 0;
 
-  // Statistics
-  GenerationStats stats_;
+    // Statistics
+    GenerationStats stats_;
 };
 
 } // namespace tiny_llm
diff --git a/include/tiny_llm/kv_cache.h b/include/tiny_llm/kv_cache.h
index 88b57ac..5362ad0 100644
--- a/include/tiny_llm/kv_cache.h
+++ b/include/tiny_llm/kv_cache.h
@@ -12,91 +12,91 @@ namespace tiny_llm {
 
 // Per-sequence cache state
 struct SequenceCache {
-  int seq_id = -1;
-  int current_len = 0;
-  int max_len = 0;
-  bool active = false;
+    int  seq_id = -1;
+    int  current_len = 0;
+    int  max_len = 0;
+    bool active = false;
 };
 
 // KV Cache Manager
 // Manages GPU memory for key-value caches across all layers and sequences
 class KVCacheManager {
-public:
-  explicit KVCacheManager(const KVCacheConfig &config);
-  ~KVCacheManager();
+  public:
+    explicit KVCacheManager(const KVCacheConfig &config);
+    ~KVCacheManager();
 
-  // Non-copyable
-  KVCacheManager(const KVCacheManager &) = delete;
-  KVCacheManager &operator=(const KVCacheManager &) = delete;
+    // Non-copyable
+    KVCacheManager(const KVCacheManager &) = delete;
+    KVCacheManager &operator=(const KVCacheManager &) = delete;
 
-  // Allocate cache for a new sequence
-  // Returns sequence ID on success, error on failure
-  Result<int> allocateSequence(int max_len);
+    // Allocate cache for a new sequence
+    // Returns sequence ID on success, error on failure
+    Result<int> allocateSequence(int max_len);
 
-  // Release cache for completed sequence
-  // Returns error if sequence not found
-  Result<void> releaseSequence(int seq_id);
+    // Release cache for completed sequence
+    // Returns error if sequence not found
+    Result<void> releaseSequence(int seq_id);
 
-  // Get cache pointers for a sequence at specific layer
-  // Returns (k_cache, v_cache) pointers
-  std::pair<half *, half *> getCache(int seq_id, int layer_idx);
+    // Get cache pointers for a sequence at specific layer
+    // Returns (k_cache, v_cache) pointers
+    std::pair<half *, half *> getCache(int seq_id, int layer_idx);
 
-  // Get cache pointers with error checking
-  // Returns error if sequence not found or invalid layer
-  Result<std::pair<half *, half *>> getCacheChecked(int seq_id, int layer_idx);
+    // Get cache pointers with error checking
+    // Returns error if sequence not found or invalid layer
+    Result<std::pair<half *, half *>> getCacheChecked(int seq_id, int layer_idx);
 
-  // Append new KV pairs to cache (does NOT advance seq_len).
-  // The newly appended tokens are written at the current visible tail and may be
-  // consumed by the same step's decode attention before advanceSeqLen() is
-  // called, but getSeqLen() remains unchanged until the explicit advance.
-  // Returns error on invalid input or cache overflow.
-  Result<void> appendKV(int seq_id, int layer_idx, const half *new_k,
-                        const half *new_v, int num_tokens, cudaStream_t stream = 0);
+    // Append new KV pairs to cache (does NOT advance seq_len).
+    // The newly appended tokens are written at the current visible tail and may be
+    // consumed by the same step's decode attention before advanceSeqLen() is
+    // called, but getSeqLen() remains unchanged until the explicit advance.
+    // Returns error on invalid input or cache overflow.
+    Result<void> appendKV(int seq_id, int layer_idx, const half *new_k, const half *new_v,
+                          int num_tokens, cudaStream_t stream = 0);
 
-  // Advance sequence length after all layers have appended.
-  // Call exactly ONCE per logical step, after all layers' appendKV calls.
-  // Returns error if sequence not found or invalid num_tokens.
-  Result<void> advanceSeqLen(int seq_id, int num_tokens);
+    // Advance sequence length after all layers have appended.
+    // Call exactly ONCE per logical step, after all layers' appendKV calls.
+    // Returns error if sequence not found or invalid num_tokens.
+    Result<void> advanceSeqLen(int seq_id, int num_tokens);
 
-  // Get current sequence length
-  int getSeqLen(int seq_id) const;
+    // Get current sequence length
+    int getSeqLen(int seq_id) const;
 
-  // Check if sequence exists
-  bool hasSequence(int seq_id) const;
+    // Check if sequence exists
+    bool hasSequence(int seq_id) const;
 
-  // Memory statistics
-  size_t getUsedMemory() const;
-  size_t getTotalMemory() const;
-  size_t getFreeMemory() const;
+    // Memory statistics
+    size_t getUsedMemory() const;
+    size_t getTotalMemory() const;
+    size_t getFreeMemory() const;
 
-  // Get number of active sequences
-  int getActiveSequenceCount() const;
+    // Get number of active sequences
+    int getActiveSequenceCount() const;
 
-  // Get config
-  const KVCacheConfig &getConfig() const { return config_; }
+    // Get config
+    const KVCacheConfig &getConfig() const { return config_; }
 
-private:
-  // Calculate memory offset for a specific sequence, layer, and type (K or V)
-  size_t calculateOffset(int slot_idx, int layer_idx, bool is_value) const;
+  private:
+    // Calculate memory offset for a specific sequence, layer, and type (K or V)
+    size_t calculateOffset(int slot_idx, int layer_idx, bool is_value) const;
 
-  // Find free slot
-  int findFreeSlot() const;
+    // Find free slot
+    int findFreeSlot() const;
 
-  KVCacheConfig config_;
+    KVCacheConfig config_;
 
-  // GPU memory pool
-  half *memory_pool_ = nullptr;
-  size_t pool_size_ = 0;
+    // GPU memory pool
+    half  *memory_pool_ = nullptr;
+    size_t pool_size_ = 0;
 
-  // Slot management
-  std::vector<SequenceCache> slots_;
-  std::unordered_map<int, int> seq_to_slot_; // seq_id -> slot_idx
+    // Slot management
+    std::vector<SequenceCache>   slots_;
+    std::unordered_map<int, int> seq_to_slot_; // seq_id -> slot_idx
 
-  // Next sequence ID
-  int next_seq_id_ = 0;
+    // Next sequence ID
+    int next_seq_id_ = 0;
 
-  // Per-slot memory size
-  size_t slot_size_ = 0;
+    // Per-slot memory size
+    size_t slot_size_ = 0;
 };
 
 } // namespace tiny_llm
diff --git a/include/tiny_llm/logger.h b/include/tiny_llm/logger.h
index 7d18a48..fddff42 100644
--- a/include/tiny_llm/logger.h
+++ b/include/tiny_llm/logger.h
@@ -16,15 +16,7 @@ namespace tiny_llm {
 /**
  * @brief Log level enumeration
  */
-enum class LogLevel {
-  TRACE = 0,
-  DEBUG = 1,
-  INFO = 2,
-  WARN = 3,
-  ERROR = 4,
-  CRITICAL = 5,
-  OFF = 6
-};
+enum class LogLevel { TRACE = 0, DEBUG = 1, INFO = 2, WARN = 3, ERROR = 4, CRITICAL = 5, OFF = 6 };
 
 /**
  * @brief Logger singleton for tiny-llm
@@ -50,51 +42,51 @@ enum class LogLevel {
  * @endcode
  */
 class Logger {
-public:
-  /**
-   * @brief Initialize the logging system
-   * @param level Minimum log level to output
-   * @param log_file Optional path for file logging (empty = console only)
-   * @param async Enable asynchronous logging for better performance
-   */
-  static void init(LogLevel level = LogLevel::INFO,
-                   const std::string &log_file = "", bool async = false);
-
-  /**
-   * @brief Shutdown the logging system
-   *
-   * Should be called before program exit to flush all logs.
-   */
-  static void shutdown();
-
-  /**
-   * @brief Get the underlying spdlog logger
-   * @return Shared pointer to the logger instance
-   *
-   * If not initialized, initializes with default settings.
-   */
-  static std::shared_ptr<spdlog::logger> get();
-
-  /**
-   * @brief Set the log level
-   * @param level New minimum log level
-   */
-  static void setLevel(LogLevel level);
-
-  /**
-   * @brief Flush all pending log messages
-   */
-  static void flush();
-
-  /**
-   * @brief Check if logger is initialized
-   * @return true if initialized, false otherwise
-   */
-  static bool isInitialized() { return initialized_; }
-
-private:
-  static std::shared_ptr<spdlog::logger> logger_;
-  static bool initialized_;
+  public:
+    /**
+     * @brief Initialize the logging system
+     * @param level Minimum log level to output
+     * @param log_file Optional path for file logging (empty = console only)
+     * @param async Enable asynchronous logging for better performance
+     */
+    static void init(LogLevel level = LogLevel::INFO, const std::string &log_file = "",
+                     bool async = false);
+
+    /**
+     * @brief Shutdown the logging system
+     *
+     * Should be called before program exit to flush all logs.
+     */
+    static void shutdown();
+
+    /**
+     * @brief Get the underlying spdlog logger
+     * @return Shared pointer to the logger instance
+     *
+     * If not initialized, initializes with default settings.
+     */
+    static std::shared_ptr<spdlog::logger> get();
+
+    /**
+     * @brief Set the log level
+     * @param level New minimum log level
+     */
+    static void setLevel(LogLevel level);
+
+    /**
+     * @brief Flush all pending log messages
+     */
+    static void flush();
+
+    /**
+     * @brief Check if logger is initialized
+     * @return true if initialized, false otherwise
+     */
+    static bool isInitialized() { return initialized_; }
+
+  private:
+    static std::shared_ptr<spdlog::logger> logger_;
+    static bool                            initialized_;
 };
 
 } // namespace tiny_llm
@@ -104,25 +96,19 @@ class Logger {
 // Include spdlog header for macros
 #include <spdlog/spdlog.h>
 
-#define TLLM_TRACE(...)                                                        \
-  SPDLOG_LOGGER_TRACE(tiny_llm::Logger::get(), __VA_ARGS__)
-#define TLLM_DEBUG(...)                                                        \
-  SPDLOG_LOGGER_DEBUG(tiny_llm::Logger::get(), __VA_ARGS__)
-#define TLLM_INFO(...)                                                         \
-  SPDLOG_LOGGER_INFO(tiny_llm::Logger::get(), __VA_ARGS__)
-#define TLLM_WARN(...)                                                         \
-  SPDLOG_LOGGER_WARN(tiny_llm::Logger::get(), __VA_ARGS__)
-#define TLLM_ERROR(...)                                                        \
-  SPDLOG_LOGGER_ERROR(tiny_llm::Logger::get(), __VA_ARGS__)
-#define TLLM_CRITICAL(...)                                                     \
-  SPDLOG_LOGGER_CRITICAL(tiny_llm::Logger::get(), __VA_ARGS__)
+#define TLLM_TRACE(...)    SPDLOG_LOGGER_TRACE(tiny_llm::Logger::get(), __VA_ARGS__)
+#define TLLM_DEBUG(...)    SPDLOG_LOGGER_DEBUG(tiny_llm::Logger::get(), __VA_ARGS__)
+#define TLLM_INFO(...)     SPDLOG_LOGGER_INFO(tiny_llm::Logger::get(), __VA_ARGS__)
+#define TLLM_WARN(...)     SPDLOG_LOGGER_WARN(tiny_llm::Logger::get(), __VA_ARGS__)
+#define TLLM_ERROR(...)    SPDLOG_LOGGER_ERROR(tiny_llm::Logger::get(), __VA_ARGS__)
+#define TLLM_CRITICAL(...) SPDLOG_LOGGER_CRITICAL(tiny_llm::Logger::get(), __VA_ARGS__)
 
 // Conditional logging (for performance-critical paths)
-#define TLLM_TRACE_IF(cond, ...)                                               \
-  if (tiny_llm::Logger::get()->should_log(spdlog::level::trace)) {             \
-    TLLM_TRACE(__VA_ARGS__);                                                   \
-  }
-#define TLLM_DEBUG_IF(cond, ...)                                               \
-  if (tiny_llm::Logger::get()->should_log(spdlog::level::debug)) {             \
-    TLLM_DEBUG(__VA_ARGS__);                                                   \
-  }
+#define TLLM_TRACE_IF(cond, ...)                                                                   \
+    if (tiny_llm::Logger::get()->should_log(spdlog::level::trace)) {                               \
+        TLLM_TRACE(__VA_ARGS__);                                                                   \
+    }
+#define TLLM_DEBUG_IF(cond, ...)                                                                   \
+    if (tiny_llm::Logger::get()->should_log(spdlog::level::debug)) {                               \
+        TLLM_DEBUG(__VA_ARGS__);                                                                   \
+    }
diff --git a/include/tiny_llm/model_loader.h b/include/tiny_llm/model_loader.h
index f71c73d..2c29d51 100644
--- a/include/tiny_llm/model_loader.h
+++ b/include/tiny_llm/model_loader.h
@@ -14,38 +14,35 @@ namespace tiny_llm {
 
 // Model loader class
 class ModelLoader {
-public:
-  // Load model from GGUF format
-  static Result<ModelWeights> loadGGUF(const std::string &path,
-                                       ModelConfig &config);
-
-  // Load model from simple binary format
-  static Result<ModelWeights> loadBin(const std::string &path,
-                                      const ModelConfig &config);
-
-  // Free model weights from GPU
-  static void freeWeights(ModelWeights &weights);
-
-private:
-  // Binary format helpers
-  static Result<QuantizedWeight>
-  loadQuantizedTensor(std::ifstream &file, int rows, int cols, int group_size);
-
-  // GPU transfer
-  static Result<void> transferToDevice(ModelWeights &weights,
-                                       const ModelConfig &config);
-  static Result<QuantizedWeight>
-  allocateAndTransferQuantized(const int8_t *host_data, const half *host_scales,
-                               int rows, int cols, int group_size);
+  public:
+    // Load model from GGUF format
+    static Result<ModelWeights> loadGGUF(const std::string &path, ModelConfig &config);
+
+    // Load model from simple binary format
+    static Result<ModelWeights> loadBin(const std::string &path, const ModelConfig &config);
+
+    // Free model weights from GPU
+    static void freeWeights(ModelWeights &weights);
+
+  private:
+    // Binary format helpers
+    static Result<QuantizedWeight> loadQuantizedTensor(std::ifstream &file, int rows, int cols,
+                                                       int group_size);
+
+    // GPU transfer
+    static Result<void> transferToDevice(ModelWeights &weights, const ModelConfig &config);
+    static Result<QuantizedWeight> allocateAndTransferQuantized(const int8_t *host_data,
+                                                                const half *host_scales, int rows,
+                                                                int cols, int group_size);
 };
 
 // Simple binary format for testing
 // Header: magic (4 bytes) + version (4 bytes) + config (ModelConfig)
 // Then: embedding, layers, final_norm, lm_head
 struct BinHeader {
-  uint32_t magic; // "TLLM"
-  uint32_t version;
-  ModelConfig config;
+    uint32_t    magic; // "TLLM"
+    uint32_t    version;
+    ModelConfig config;
 };
 
 constexpr uint32_t BIN_MAGIC = 0x4D4C4C54; // "TLLM"
diff --git a/include/tiny_llm/result.h b/include/tiny_llm/result.h
index 8d9da44..d391592 100644
--- a/include/tiny_llm/result.h
+++ b/include/tiny_llm/result.h
@@ -7,111 +7,107 @@
 namespace tiny_llm {
 
 // Result type for error propagation without exceptions
-template <typename T> class Result {
-public:
-  // Factory methods
-  static Result<T> ok(T value) { return Result(std::move(value)); }
+template <typename T>
+class Result {
+  public:
+    // Factory methods
+    static Result<T> ok(T value) { return Result(std::move(value)); }
 
-  static Result<T> err(std::string message) {
-    return Result(Error{std::move(message)});
-  }
+    static Result<T> err(std::string message) { return Result(Error{std::move(message)}); }
 
-  // Status checks
-  bool isOk() const { return std::holds_alternative<T>(data_); }
+    // Status checks
+    bool isOk() const { return std::holds_alternative<T>(data_); }
 
-  bool isErr() const { return !isOk(); }
+    bool isErr() const { return !isOk(); }
 
-  // Value access (throws if error)
-  T &value() {
-    if (isErr()) {
-      throw std::runtime_error("Attempted to access value of error Result: " +
-                               error());
+    // Value access (throws if error)
+    T &value() {
+        if (isErr()) {
+            throw std::runtime_error("Attempted to access value of error Result: " + error());
+        }
+        return std::get<T>(data_);
     }
-    return std::get<T>(data_);
-  }
 
-  const T &value() const {
-    if (isErr()) {
-      throw std::runtime_error("Attempted to access value of error Result: " +
-                               error());
+    const T &value() const {
+        if (isErr()) {
+            throw std::runtime_error("Attempted to access value of error Result: " + error());
+        }
+        return std::get<T>(data_);
     }
-    return std::get<T>(data_);
-  }
 
-  // Error access (throws if ok)
-  const std::string &error() const {
-    if (isOk()) {
-      throw std::runtime_error("Attempted to access error of ok Result");
+    // Error access (throws if ok)
+    const std::string &error() const {
+        if (isOk()) {
+            throw std::runtime_error("Attempted to access error of ok Result");
+        }
+        return std::get<Error>(data_).message;
     }
-    return std::get<Error>(data_).message;
-  }
 
-  // Value access with default
-  T valueOr(T default_value) const {
-    if (isOk()) {
-      return std::get<T>(data_);
+    // Value access with default
+    T valueOr(T default_value) const {
+        if (isOk()) {
+            return std::get<T>(data_);
+        }
+        return default_value;
     }
-    return default_value;
-  }
-
-  // Monadic operations
-  template <typename F>
-  auto map(F &&f) -> Result<decltype(f(std::declval<T>()))> {
-    using U = decltype(f(std::declval<T>()));
-    if (isOk()) {
-      return Result<U>::ok(f(value()));
+
+    // Monadic operations
+    template <typename F>
+    auto map(F &&f) -> Result<decltype(f(std::declval<T>()))> {
+        using U = decltype(f(std::declval<T>()));
+        if (isOk()) {
+            return Result<U>::ok(f(value()));
+        }
+        return Result<U>::err(error());
     }
-    return Result<U>::err(error());
-  }
 
-  template <typename F> auto flatMap(F &&f) -> decltype(f(std::declval<T>())) {
-    if (isOk()) {
-      return f(value());
+    template <typename F>
+    auto flatMap(F &&f) -> decltype(f(std::declval<T>())) {
+        if (isOk()) {
+            return f(value());
+        }
+        using U = typename decltype(f(std::declval<T>()))::ValueType;
+        return Result<U>::err(error());
     }
-    using U = typename decltype(f(std::declval<T>()))::ValueType;
-    return Result<U>::err(error());
-  }
 
-  // Type alias for flatMap
-  using ValueType = T;
+    // Type alias for flatMap
+    using ValueType = T;
 
-private:
-  struct Error {
-    std::string message;
-  };
+  private:
+    struct Error {
+        std::string message;
+    };
 
-  explicit Result(T value) : data_(std::move(value)) {}
-  explicit Result(Error error) : data_(std::move(error)) {}
+    explicit Result(T value) : data_(std::move(value)) {}
+    explicit Result(Error error) : data_(std::move(error)) {}
 
-  std::variant<T, Error> data_;
+    std::variant<T, Error> data_;
 };
 
 // Specialization for void
-template <> class Result<void> {
-public:
-  static Result<void> ok() { return Result(true); }
+template <>
+class Result<void> {
+  public:
+    static Result<void> ok() { return Result(true); }
 
-  static Result<void> err(std::string message) {
-    return Result(std::move(message));
-  }
+    static Result<void> err(std::string message) { return Result(std::move(message)); }
 
-  bool isOk() const { return is_ok_; }
-  bool isErr() const { return !is_ok_; }
+    bool isOk() const { return is_ok_; }
+    bool isErr() const { return !is_ok_; }
 
-  const std::string &error() const {
-    if (isOk()) {
-      throw std::runtime_error("Attempted to access error of ok Result");
+    const std::string &error() const {
+        if (isOk()) {
+            throw std::runtime_error("Attempted to access error of ok Result");
+        }
+        return error_;
     }
-    return error_;
-  }
 
-private:
-  explicit Result(bool) : is_ok_(true) {}
-  explicit Result(std::string error)
-      : is_ok_(false), error_(std::move(error)) {}
+  private:
+    explicit Result(bool) : is_ok_(true) {}
+    explicit Result(std::string error) : is_ok_(false), error_(std::move(error)) {}
 
-  bool is_ok_;
-  std::string error_;
+    bool        is_ok_;
+    std::string error_;
 };
 
 } // namespace tiny_llm
diff --git a/include/tiny_llm/transformer.h b/include/tiny_llm/transformer.h
index 4721ddc..a405c36 100644
--- a/include/tiny_llm/transformer.h
+++ b/include/tiny_llm/transformer.h
@@ -10,66 +10,64 @@ namespace tiny_llm {
 // TransformerLayer implements a single transformer decoder layer
 // with W8A16 quantized weights and KV cache support
 class TransformerLayer {
-public:
-  TransformerLayer(int layer_idx, const TransformerWeights &weights,
-                   const ModelConfig &config);
-  ~TransformerLayer();
-
-  // Non-copyable
-  TransformerLayer(const TransformerLayer &) = delete;
-  TransformerLayer &operator=(const TransformerLayer &) = delete;
-
-  // Move constructible
-  TransformerLayer(TransformerLayer &&other) noexcept;
-  TransformerLayer &operator=(TransformerLayer &&other) noexcept;
-
-  // Forward pass for single token (decode phase)
-  // hidden_states: [batch_size, hidden_dim] - input and output
-  void forward(half *hidden_states, KVCacheManager &kv_cache, int seq_id,
-               int position, cudaStream_t stream = 0);
-
-  // Forward pass for multiple tokens (prefill phase)
-  // hidden_states: [batch_size, seq_len, hidden_dim] - input and output
-  void forwardPrefill(half *hidden_states, KVCacheManager &kv_cache, int seq_id,
-                      int seq_len, cudaStream_t stream = 0);
-
-  // Get layer index
-  int getLayerIdx() const { return layer_idx_; }
-
-private:
-  // Attention sublayer
-  void attention(const half *x, half *output, KVCacheManager &kv_cache,
-                 int seq_id, int position, int num_tokens, cudaStream_t stream);
-
-  // Feed-forward network sublayer (SwiGLU)
-  void feedForward(const half *x, half *output, int num_tokens,
-                   cudaStream_t stream);
-
-  // RMSNorm helper
-  void rmsNorm(const half *x, const half *weight, half *output, int num_tokens,
-               cudaStream_t stream);
-
-  // Allocate intermediate buffers
-  void allocateBuffers();
-  void freeBuffers();
-
-  int layer_idx_;
-  const TransformerWeights &weights_;
-  const ModelConfig &config_;
-
-  // Intermediate buffers (GPU memory)
-  half *norm_output_ = nullptr; // [max_batch, hidden_dim]
-  half *q_buf_ = nullptr;       // [max_batch, num_heads * head_dim]
-  half *k_buf_ = nullptr;       // [max_batch, num_kv_heads * head_dim]
-  half *v_buf_ = nullptr;       // [max_batch, num_kv_heads * head_dim]
-  half *attn_output_ = nullptr; // [max_batch, hidden_dim]
-  half *ffn_gate_ = nullptr;    // [max_batch, intermediate_dim]
-  half *ffn_up_ = nullptr;      // [max_batch, intermediate_dim]
-  half *ffn_output_ = nullptr;  // [max_batch, hidden_dim]
-
-  // Buffer sizes
-  size_t max_batch_tokens_ = 0;
-  bool buffers_allocated_ = false;
+  public:
+    TransformerLayer(int layer_idx, const TransformerWeights &weights, const ModelConfig &config);
+    ~TransformerLayer();
+
+    // Non-copyable
+    TransformerLayer(const TransformerLayer &) = delete;
+    TransformerLayer &operator=(const TransformerLayer &) = delete;
+
+    // Move constructible
+    TransformerLayer(TransformerLayer &&other) noexcept;
+    TransformerLayer &operator=(TransformerLayer &&other) noexcept;
+
+    // Forward pass for single token (decode phase)
+    // hidden_states: [batch_size, hidden_dim] - input and output
+    void forward(half *hidden_states, KVCacheManager &kv_cache, int seq_id, int position,
+                 cudaStream_t stream = 0);
+
+    // Forward pass for multiple tokens (prefill phase)
+    // hidden_states: [batch_size, seq_len, hidden_dim] - input and output
+    void forwardPrefill(half *hidden_states, KVCacheManager &kv_cache, int seq_id, int seq_len,
+                        cudaStream_t stream = 0);
+
+    // Get layer index
+    int getLayerIdx() const { return layer_idx_; }
+
+  private:
+    // Attention sublayer
+    void attention(const half *x, half *output, KVCacheManager &kv_cache, int seq_id, int position,
+                   int num_tokens, cudaStream_t stream);
+
+    // Feed-forward network sublayer (SwiGLU)
+    void feedForward(const half *x, half *output, int num_tokens, cudaStream_t stream);
+
+    // RMSNorm helper
+    void rmsNorm(const half *x, const half *weight, half *output, int num_tokens,
+                 cudaStream_t stream);
+
+    // Allocate intermediate buffers
+    void allocateBuffers();
+    void freeBuffers();
+
+    int                       layer_idx_;
+    const TransformerWeights &weights_;
+    const ModelConfig        &config_;
+
+    // Intermediate buffers (GPU memory)
+    half *norm_output_ = nullptr; // [max_batch, hidden_dim]
+    half *q_buf_ = nullptr;       // [max_batch, num_heads * head_dim]
+    half *k_buf_ = nullptr;       // [max_batch, num_kv_heads * head_dim]
+    half *v_buf_ = nullptr;       // [max_batch, num_kv_heads * head_dim]
+    half *attn_output_ = nullptr; // [max_batch, hidden_dim]
+    half *ffn_gate_ = nullptr;    // [max_batch, intermediate_dim]
+    half *ffn_up_ = nullptr;      // [max_batch, intermediate_dim]
+    half *ffn_output_ = nullptr;  // [max_batch, hidden_dim]
+
+    // Buffer sizes
+    size_t max_batch_tokens_ = 0;
+    bool   buffers_allocated_ = false;
 };
 
 } // namespace tiny_llm
diff --git a/include/tiny_llm/types.h b/include/tiny_llm/types.h
index 4dc2548..9ed850e 100644
--- a/include/tiny_llm/types.h
+++ b/include/tiny_llm/types.h
@@ -11,85 +11,82 @@ namespace tiny_llm {
 
 // Model configuration
 struct ModelConfig {
-  int vocab_size = 32000;
-  int hidden_dim = 4096;
-  int num_layers = 32;
-  int num_heads = 32;
-  int num_kv_heads = 32; // For GQA support
-  int head_dim = 128;
-  int intermediate_dim = 11008;
-  int max_seq_len = 2048;
-  float rope_theta = 10000.0f;
-  float rms_norm_eps = 1e-5f;
-  int eos_token_id = 2;
-  int bos_token_id = 1;
+    int   vocab_size = 32000;
+    int   hidden_dim = 4096;
+    int   num_layers = 32;
+    int   num_heads = 32;
+    int   num_kv_heads = 32; // For GQA support
+    int   head_dim = 128;
+    int   intermediate_dim = 11008;
+    int   max_seq_len = 2048;
+    float rope_theta = 10000.0f;
+    float rms_norm_eps = 1e-5f;
+    int   eos_token_id = 2;
+    int   bos_token_id = 1;
 };
 
 // Quantization parameters
 struct QuantizationParams {
-  int group_size = 128;  // Elements per scale factor
-  bool symmetric = true; // Symmetric quantization (no zero point)
+    int  group_size = 128; // Elements per scale factor
+    bool symmetric = true; // Symmetric quantization (no zero point)
 };
 
 // Quantized weight tensor
 struct QuantizedWeight {
-  int8_t *data = nullptr; // INT8 quantized weights [rows, cols]
-  half *scales = nullptr; // Scale factors [ceil(rows/group_size), cols]
-  int rows = 0;
-  int cols = 0;
-  int group_size = 128;
-
-  // Calculate expected scale dimensions
-  int scaleRows() const { return (rows + group_size - 1) / group_size; }
-  int scaleCols() const { return cols; }
-
-  // Total elements
-  size_t weightElements() const { return static_cast<size_t>(rows) * cols; }
-  size_t scaleElements() const {
-    return static_cast<size_t>(scaleRows()) * scaleCols();
-  }
-
-  // Memory sizes
-  size_t weightBytes() const { return weightElements() * sizeof(int8_t); }
-  size_t scaleBytes() const { return scaleElements() * sizeof(half); }
-  size_t totalBytes() const { return weightBytes() + scaleBytes(); }
-
-  // Validate dimensions
-  bool isValid() const {
-    return data != nullptr && scales != nullptr && rows > 0 && cols > 0 &&
-           group_size > 0;
-  }
+    int8_t *data = nullptr;   // INT8 quantized weights [rows, cols]
+    half   *scales = nullptr; // Scale factors [ceil(rows/group_size), cols]
+    int     rows = 0;
+    int     cols = 0;
+    int     group_size = 128;
+
+    // Calculate expected scale dimensions
+    int scaleRows() const { return (rows + group_size - 1) / group_size; }
+    int scaleCols() const { return cols; }
+
+    // Total elements
+    size_t weightElements() const { return static_cast<size_t>(rows) * cols; }
+    size_t scaleElements() const { return static_cast<size_t>(scaleRows()) * scaleCols(); }
+
+    // Memory sizes
+    size_t weightBytes() const { return weightElements() * sizeof(int8_t); }
+    size_t scaleBytes() const { return scaleElements() * sizeof(half); }
+    size_t totalBytes() const { return weightBytes() + scaleBytes(); }
+
+    // Validate dimensions
+    bool isValid() const {
+        return data != nullptr && scales != nullptr && rows > 0 && cols > 0 && group_size > 0;
+    }
 };
 
 // Transformer layer weights
 struct TransformerWeights {
-  // Attention weights
-  QuantizedWeight wq; // Query projection [hidden_dim, hidden_dim]
-  QuantizedWeight wk; // Key projection [hidden_dim, kv_dim]
-  QuantizedWeight wv; // Value projection [hidden_dim, kv_dim]
-  QuantizedWeight wo; // Output projection [hidden_dim, hidden_dim]
-
-  // FFN weights (SwiGLU)
-  QuantizedWeight w1; // Gate projection [hidden_dim, intermediate_dim]
-  QuantizedWeight w2; // Down projection [intermediate_dim, hidden_dim]
-  QuantizedWeight w3; // Up projection [hidden_dim, intermediate_dim]
-
-  // Normalization weights (FP16)
-  half *rms_att_weight = nullptr; // [hidden_dim]
-  half *rms_ffn_weight = nullptr; // [hidden_dim]
+    // Attention weights
+    QuantizedWeight wq; // Query projection [hidden_dim, hidden_dim]
+    QuantizedWeight wk; // Key projection [hidden_dim, kv_dim]
+    QuantizedWeight wv; // Value projection [hidden_dim, kv_dim]
+    QuantizedWeight wo; // Output projection [hidden_dim, hidden_dim]
+
+    // FFN weights (SwiGLU)
+    QuantizedWeight w1; // Gate projection [hidden_dim, intermediate_dim]
+    QuantizedWeight w2; // Down projection [intermediate_dim, hidden_dim]
+    QuantizedWeight w3; // Up projection [hidden_dim, intermediate_dim]
+
+    // Normalization weights (FP16)
+    half *rms_att_weight = nullptr; // [hidden_dim]
+    half *rms_ffn_weight = nullptr; // [hidden_dim]
 };
 
 // Complete model weights
 struct ModelWeights {
-  // Token embedding [vocab_size, hidden_dim]
-  half *token_embedding = nullptr;
+    // Token embedding [vocab_size, hidden_dim]
+    half *token_embedding = nullptr;
 
-  // Per-layer weights
-  std::vector<TransformerWeights> layers;
+    // Per-layer weights
+    std::vector<TransformerWeights> layers;
 
-  // Output
-  half *final_norm_weight = nullptr; // [hidden_dim]
-  QuantizedWeight lm_head;           // [hidden_dim, vocab_size]
+    // Output
+    half           *final_norm_weight = nullptr; // [hidden_dim]
+    QuantizedWeight lm_head;                     // [hidden_dim, vocab_size]
 };
 
 // Forward declaration
@@ -97,37 +94,37 @@ class Validator;
 
 // Generation configuration
 struct GenerationConfig {
-  int max_new_tokens = 256;
-  float temperature = 1.0f;
-  int top_k = 50;
-  float top_p = 0.9f;
-  bool do_sample = false; // false = greedy
-  float repetition_penalty = 1.0f;
-
-  /**
-   * @brief Validate the configuration
-   * @return Result<void> indicating success or error with message
-   */
-  Result<void> validate() const;
+    int   max_new_tokens = 256;
+    float temperature = 1.0f;
+    int   top_k = 50;
+    float top_p = 0.9f;
+    bool  do_sample = false; // false = greedy
+    float repetition_penalty = 1.0f;
+
+    /**
+     * @brief Validate the configuration
+     * @return Result<void> indicating success or error with message
+     */
+    Result<void> validate() const;
 };
 
 // Generation statistics
 struct GenerationStats {
-  float prefill_time_ms = 0.0f;
-  float decode_time_ms = 0.0f;
-  int prompt_tokens = 0;
-  int tokens_generated = 0;
-  float tokens_per_second = 0.0f;
-  size_t peak_memory_bytes = 0;
+    float  prefill_time_ms = 0.0f;
+    float  decode_time_ms = 0.0f;
+    int    prompt_tokens = 0;
+    int    tokens_generated = 0;
+    float  tokens_per_second = 0.0f;
+    size_t peak_memory_bytes = 0;
 };
 
 // KV Cache configuration
 struct KVCacheConfig {
-  int num_layers = 32;
-  int num_heads = 32;
-  int head_dim = 128;
-  int max_seq_len = 2048;
-  int max_batch_size = 1;
+    int num_layers = 32;
+    int num_heads = 32;
+    int head_dim = 128;
+    int max_seq_len = 2048;
+    int max_batch_size = 1;
 };
 
 } // namespace tiny_llm
diff --git a/include/tiny_llm/validator.h b/include/tiny_llm/validator.h
index 6c58224..b446416 100644
--- a/include/tiny_llm/validator.h
+++ b/include/tiny_llm/validator.h
@@ -27,294 +27,271 @@ namespace tiny_llm {
  * @endcode
  */
 class Validator {
-public:
-  // ── Token Validation ─────────────────────────────────────────────
+  public:
+    // ── Token Validation ─────────────────────────────────────────────
 
-  /**
-   * @brief Validate a single token ID
-   * @param token_id Token ID to validate
-   * @param vocab_size Vocabulary size (valid range: 0 to vocab_size-1)
-   * @param context Optional context string for error messages
-   * @return Result<void> indicating success or error with message
-   */
-  static Result<void> validateTokenId(int token_id, int vocab_size,
-                                       const std::string &context = "") {
-    if (vocab_size <= 0) {
-      return Result<void>::err(
-          buildContext(context, "Invalid vocab_size: " +
-                                     std::to_string(vocab_size) +
-                                     " (must be positive)"));
-    }
-    if (token_id < 0 || token_id >= vocab_size) {
-      return Result<void>::err(buildContext(
-          context, "Invalid token ID: " + std::to_string(token_id) +
-                       " (valid range: 0-" + std::to_string(vocab_size - 1) +
-                       ")"));
+    /**
+     * @brief Validate a single token ID
+     * @param token_id Token ID to validate
+     * @param vocab_size Vocabulary size (valid range: 0 to vocab_size-1)
+     * @param context Optional context string for error messages
+     * @return Result<void> indicating success or error with message
+     */
+    static Result<void> validateTokenId(int token_id, int vocab_size,
+                                        const std::string &context = "") {
+        if (vocab_size <= 0) {
+            return Result<void>::err(
+                buildContext(context, "Invalid vocab_size: " + std::to_string(vocab_size) +
+                                          " (must be positive)"));
+        }
+        if (token_id < 0 || token_id >= vocab_size) {
+            return Result<void>::err(buildContext(
+                context, "Invalid token ID: " + std::to_string(token_id) + " (valid range: 0-" +
+                             std::to_string(vocab_size - 1) + ")"));
+        }
+        return Result<void>::ok();
     }
-    return Result<void>::ok();
-  }
 
-  /**
-   * @brief Validate a sequence of token IDs
-   * @param tokens Vector of token IDs to validate
-   * @param vocab_size Vocabulary size
-   * @param context Optional context string for error messages
-   * @return Result<void> indicating success or error with message
-   */
-  static Result<void> validateTokenSequence(const std::vector<int> &tokens,
-                                             int vocab_size,
-                                             const std::string &context = "") {
-    if (tokens.empty()) {
-      return Result<void>::err(buildContext(context, "Token sequence is empty"));
+    /**
+     * @brief Validate a sequence of token IDs
+     * @param tokens Vector of token IDs to validate
+     * @param vocab_size Vocabulary size
+     * @param context Optional context string for error messages
+     * @return Result<void> indicating success or error with message
+     */
+    static Result<void> validateTokenSequence(const std::vector<int> &tokens, int vocab_size,
+                                              const std::string &context = "") {
+        if (tokens.empty()) {
+            return Result<void>::err(buildContext(context, "Token sequence is empty"));
+        }
+        for (size_t i = 0; i < tokens.size(); ++i) {
+            auto result = validateTokenId(tokens[i], vocab_size,
+                                          context + " token[" + std::to_string(i) + "]");
+            if (result.isErr()) {
+                return result;
+            }
+        }
+        return Result<void>::ok();
     }
-    for (size_t i = 0; i < tokens.size(); ++i) {
-      auto result = validateTokenId(
-          tokens[i], vocab_size,
-          context + " token[" + std::to_string(i) + "]");
-      if (result.isErr()) {
-        return result;
-      }
-    }
-    return Result<void>::ok();
-  }
 
-  // ── Configuration Validation ──────────────────────────────────────
+    // ── Configuration Validation ──────────────────────────────────────
 
-  /**
-   * @brief Validate generation configuration
-   * @param config Generation configuration to validate
-   * @return Result<void> indicating success or error with message
-   */
-  static Result<void>
-  validateGenerationConfig(const GenerationConfig &config) {
-    if (config.max_new_tokens <= 0) {
-      return Result<void>::err(
-          "max_new_tokens must be positive: " +
-          std::to_string(config.max_new_tokens));
-    }
-    if (config.temperature <= 0.0f) {
-      return Result<void>::err("temperature must be positive: " +
-                                std::to_string(config.temperature));
+    /**
+     * @brief Validate generation configuration
+     * @param config Generation configuration to validate
+     * @return Result<void> indicating success or error with message
+     */
+    static Result<void> validateGenerationConfig(const GenerationConfig &config) {
+        if (config.max_new_tokens <= 0) {
+            return Result<void>::err("max_new_tokens must be positive: " +
+                                     std::to_string(config.max_new_tokens));
+        }
+        if (config.temperature <= 0.0f) {
+            return Result<void>::err("temperature must be positive: " +
+                                     std::to_string(config.temperature));
+        }
+        if (config.top_k < 0) {
+            return Result<void>::err("top_k must be non-negative: " + std::to_string(config.top_k));
+        }
+        if (config.top_p <= 0.0f || config.top_p > 1.0f) {
+            return Result<void>::err("top_p must be in (0, 1]: " + std::to_string(config.top_p));
+        }
+        if (config.repetition_penalty <= 0.0f) {
+            return Result<void>::err("repetition_penalty must be positive: " +
+                                     std::to_string(config.repetition_penalty));
+        }
+        return Result<void>::ok();
     }
-    if (config.top_k < 0) {
-      return Result<void>::err("top_k must be non-negative: " +
-                                std::to_string(config.top_k));
-    }
-    if (config.top_p <= 0.0f || config.top_p > 1.0f) {
-      return Result<void>::err("top_p must be in (0, 1]: " +
-                                std::to_string(config.top_p));
-    }
-    if (config.repetition_penalty <= 0.0f) {
-      return Result<void>::err("repetition_penalty must be positive: " +
-                                std::to_string(config.repetition_penalty));
-    }
-    return Result<void>::ok();
-  }
 
-  /**
-   * @brief Validate model configuration
-   * @param config Model configuration to validate
-   * @return Result<void> indicating success or error with message
-   */
-  static Result<void> validateModelConfig(const ModelConfig &config) {
-    if (config.vocab_size <= 0) {
-      return Result<void>::err("vocab_size must be positive: " +
-                                std::to_string(config.vocab_size));
-    }
-    if (config.hidden_dim <= 0) {
-      return Result<void>::err("hidden_dim must be positive: " +
-                                std::to_string(config.hidden_dim));
-    }
-    if (config.num_layers <= 0) {
-      return Result<void>::err("num_layers must be positive: " +
-                                std::to_string(config.num_layers));
+    /**
+     * @brief Validate model configuration
+     * @param config Model configuration to validate
+     * @return Result<void> indicating success or error with message
+     */
+    static Result<void> validateModelConfig(const ModelConfig &config) {
+        if (config.vocab_size <= 0) {
+            return Result<void>::err("vocab_size must be positive: " +
+                                     std::to_string(config.vocab_size));
+        }
+        if (config.hidden_dim <= 0) {
+            return Result<void>::err("hidden_dim must be positive: " +
+                                     std::to_string(config.hidden_dim));
+        }
+        if (config.num_layers <= 0) {
+            return Result<void>::err("num_layers must be positive: " +
+                                     std::to_string(config.num_layers));
+        }
+        if (config.num_heads <= 0) {
+            return Result<void>::err("num_heads must be positive: " +
+                                     std::to_string(config.num_heads));
+        }
+        if (config.num_kv_heads <= 0) {
+            return Result<void>::err("num_kv_heads must be positive: " +
+                                     std::to_string(config.num_kv_heads));
+        }
+        if (config.head_dim <= 0) {
+            return Result<void>::err("head_dim must be positive: " +
+                                     std::to_string(config.head_dim));
+        }
+        if (config.max_seq_len <= 0) {
+            return Result<void>::err("max_seq_len must be positive: " +
+                                     std::to_string(config.max_seq_len));
+        }
+        if (config.rms_norm_eps <= 0.0f) {
+            return Result<void>::err("rms_norm_eps must be positive: " +
+                                     std::to_string(config.rms_norm_eps));
+        }
+        return Result<void>::ok();
     }
-    if (config.num_heads <= 0) {
-      return Result<void>::err("num_heads must be positive: " +
-                                std::to_string(config.num_heads));
-    }
-    if (config.num_kv_heads <= 0) {
-      return Result<void>::err("num_kv_heads must be positive: " +
-                                std::to_string(config.num_kv_heads));
-    }
-    if (config.head_dim <= 0) {
-      return Result<void>::err("head_dim must be positive: " +
-                                std::to_string(config.head_dim));
-    }
-    if (config.max_seq_len <= 0) {
-      return Result<void>::err("max_seq_len must be positive: " +
-                                std::to_string(config.max_seq_len));
-    }
-    if (config.rms_norm_eps <= 0.0f) {
-      return Result<void>::err("rms_norm_eps must be positive: " +
-                                std::to_string(config.rms_norm_eps));
-    }
-    return Result<void>::ok();
-  }
 
-  // ── Position/Length Validation ────────────────────────────────────
+    // ── Position/Length Validation ────────────────────────────────────
 
-  /**
-   * @brief Validate position index
-   * @param position Position index to validate
-   * @param max_seq_len Maximum sequence length
-   * @param context Optional context string for error messages
-   * @return Result<void> indicating success or error with message
-   */
-  static Result<void> validatePosition(int position, int max_seq_len,
-                                        const std::string &context = "") {
-    if (position < 0 || position >= max_seq_len) {
-      return Result<void>::err(
-          buildContext(context, "Invalid position: " +
-                                     std::to_string(position) +
-                                     " (valid range: 0-" +
-                                     std::to_string(max_seq_len - 1) + ")"));
+    /**
+     * @brief Validate position index
+     * @param position Position index to validate
+     * @param max_seq_len Maximum sequence length
+     * @param context Optional context string for error messages
+     * @return Result<void> indicating success or error with message
+     */
+    static Result<void> validatePosition(int position, int max_seq_len,
+                                         const std::string &context = "") {
+        if (position < 0 || position >= max_seq_len) {
+            return Result<void>::err(buildContext(
+                context, "Invalid position: " + std::to_string(position) + " (valid range: 0-" +
+                             std::to_string(max_seq_len - 1) + ")"));
+        }
+        return Result<void>::ok();
     }
-    return Result<void>::ok();
-  }
 
-  /**
-   * @brief Validate sequence length
-   * @param seq_len Sequence length to validate
-   * @param max_seq_len Maximum sequence length
-   * @param context Optional context string for error messages
-   * @return Result<void> indicating success or error with message
-   */
-  static Result<void> validateSeqLen(int seq_len, int max_seq_len,
-                                      const std::string &context = "") {
-    if (seq_len <= 0) {
-      return Result<void>::err(
-          buildContext(context, "seq_len must be positive: " +
-                                     std::to_string(seq_len)));
-    }
-    if (seq_len > max_seq_len) {
-      return Result<void>::err(
-          buildContext(context, "seq_len " + std::to_string(seq_len) +
-                                     " exceeds max_seq_len " +
-                                     std::to_string(max_seq_len)));
+    /**
+     * @brief Validate sequence length
+     * @param seq_len Sequence length to validate
+     * @param max_seq_len Maximum sequence length
+     * @param context Optional context string for error messages
+     * @return Result<void> indicating success or error with message
+     */
+    static Result<void> validateSeqLen(int seq_len, int max_seq_len,
+                                       const std::string &context = "") {
+        if (seq_len <= 0) {
+            return Result<void>::err(
+                buildContext(context, "seq_len must be positive: " + std::to_string(seq_len)));
+        }
+        if (seq_len > max_seq_len) {
+            return Result<void>::err(buildContext(context, "seq_len " + std::to_string(seq_len) +
+                                                               " exceeds max_seq_len " +
+                                                               std::to_string(max_seq_len)));
+        }
+        return Result<void>::ok();
     }
-    return Result<void>::ok();
-  }
 
-  /**
-   * @brief Validate that prompt length doesn't exceed max_seq_len
-   * @param prompt_len Prompt length
-   * @param max_new_tokens Maximum new tokens to generate
-   * @param max_seq_len Maximum sequence length
-   * @return Result<void> indicating success or error with message
-   */
-  static Result<void> validatePromptLength(int prompt_len, int max_new_tokens,
-                                            int max_seq_len) {
-    if (prompt_len <= 0) {
-      return Result<void>::err("Prompt length must be positive: " +
-                                std::to_string(prompt_len));
-    }
-    if (prompt_len >= max_seq_len) {
-      return Result<void>::err(
-          "Prompt length " + std::to_string(prompt_len) +
-          " exceeds max_seq_len " + std::to_string(max_seq_len));
-    }
-    int total_len = prompt_len + max_new_tokens;
-    if (total_len > max_seq_len) {
-      return Result<void>::err("Total length (prompt + max_new_tokens = " +
-                                std::to_string(total_len) +
-                                ") exceeds max_seq_len " +
-                                std::to_string(max_seq_len));
+    /**
+     * @brief Validate that prompt length doesn't exceed max_seq_len
+     * @param prompt_len Prompt length
+     * @param max_new_tokens Maximum new tokens to generate
+     * @param max_seq_len Maximum sequence length
+     * @return Result<void> indicating success or error with message
+     */
+    static Result<void> validatePromptLength(int prompt_len, int max_new_tokens, int max_seq_len) {
+        if (prompt_len <= 0) {
+            return Result<void>::err("Prompt length must be positive: " +
+                                     std::to_string(prompt_len));
+        }
+        if (prompt_len >= max_seq_len) {
+            return Result<void>::err("Prompt length " + std::to_string(prompt_len) +
+                                     " exceeds max_seq_len " + std::to_string(max_seq_len));
+        }
+        int total_len = prompt_len + max_new_tokens;
+        if (total_len > max_seq_len) {
+            return Result<void>::err(
+                "Total length (prompt + max_new_tokens = " + std::to_string(total_len) +
+                ") exceeds max_seq_len " + std::to_string(max_seq_len));
+        }
+        return Result<void>::ok();
     }
-    return Result<void>::ok();
-  }
 
-  // ── Pointer Validation ────────────────────────────────────────────
+    // ── Pointer Validation ────────────────────────────────────────────
 
-  /**
-   * @brief Validate that a pointer is not null
-   * @tparam T Pointer type
-   * @param ptr Pointer to validate
-   * @param name Name of the pointer for error message
-   * @return Result<void> indicating success or error with message
-   */
-  template <typename T>
-  static Result<void> validateNotNull(const T *ptr,
-                                       const std::string &name) {
-    if (ptr == nullptr) {
-      return Result<void>::err(name + " is null");
+    /**
+     * @brief Validate that a pointer is not null
+     * @tparam T Pointer type
+     * @param ptr Pointer to validate
+     * @param name Name of the pointer for error message
+     * @return Result<void> indicating success or error with message
+     */
+    template <typename T>
+    static Result<void> validateNotNull(const T *ptr, const std::string &name) {
+        if (ptr == nullptr) {
+            return Result<void>::err(name + " is null");
+        }
+        return Result<void>::ok();
     }
-    return Result<void>::ok();
-  }
 
-  // ── Range Validation ──────────────────────────────────────────────
+    // ── Range Validation ──────────────────────────────────────────────
 
-  /**
-   * @brief Validate that a value is within a range
-   * @param value Value to validate
-   * @param min Minimum value (inclusive)
-   * @param max Maximum value (inclusive)
-   * @param name Name for error message
-   * @return Result<void> indicating success or error with message
-   */
-  static Result<void> validateRange(int value, int min, int max,
-                                     const std::string &name) {
-    if (value < min || value > max) {
-      return Result<void>::err(name + " value " + std::to_string(value) +
-                                " out of range [" + std::to_string(min) +
-                                ", " + std::to_string(max) + "]");
+    /**
+     * @brief Validate that a value is within a range
+     * @param value Value to validate
+     * @param min Minimum value (inclusive)
+     * @param max Maximum value (inclusive)
+     * @param name Name for error message
+     * @return Result<void> indicating success or error with message
+     */
+    static Result<void> validateRange(int value, int min, int max, const std::string &name) {
+        if (value < min || value > max) {
+            return Result<void>::err(name + " value " + std::to_string(value) + " out of range [" +
+                                     std::to_string(min) + ", " + std::to_string(max) + "]");
+        }
+        return Result<void>::ok();
     }
-    return Result<void>::ok();
-  }
 
-  /**
-   * @brief Validate that a float value is within a range
-   * @param value Value to validate
-   * @param min Minimum value (inclusive)
-   * @param max Maximum value (inclusive)
-   * @param name Name for error message
-   * @return Result<void> indicating success or error with message
-   */
-  static Result<void> validateRange(float value, float min, float max,
-                                     const std::string &name) {
-    if (value < min || value > max) {
-      return Result<void>::err(name + " value " + std::to_string(value) +
-                                " out of range [" + std::to_string(min) +
-                                ", " + std::to_string(max) + "]");
+    /**
+     * @brief Validate that a float value is within a range
+     * @param value Value to validate
+     * @param min Minimum value (inclusive)
+     * @param max Maximum value (inclusive)
+     * @param name Name for error message
+     * @return Result<void> indicating success or error with message
+     */
+    static Result<void> validateRange(float value, float min, float max, const std::string &name) {
+        if (value < min || value > max) {
+            return Result<void>::err(name + " value " + std::to_string(value) + " out of range [" +
+                                     std::to_string(min) + ", " + std::to_string(max) + "]");
+        }
+        return Result<void>::ok();
     }
-    return Result<void>::ok();
-  }
 
-  // ── Layer Index Validation ────────────────────────────────────────
+    // ── Layer Index Validation ────────────────────────────────────────
 
-  /**
-   * @brief Validate layer index
-   * @param layer_idx Layer index to validate
-   * @param num_layers Total number of layers
-   * @param context Optional context string for error messages
-   * @return Result<void> indicating success or error with message
-   */
-  static Result<void> validateLayerIndex(int layer_idx, int num_layers,
-                                          const std::string &context = "") {
-    if (layer_idx < 0 || layer_idx >= num_layers) {
-      return Result<void>::err(
-          buildContext(context, "Invalid layer_idx: " +
-                                     std::to_string(layer_idx) +
-                                     " (valid range: 0-" +
-                                     std::to_string(num_layers - 1) + ")"));
+    /**
+     * @brief Validate layer index
+     * @param layer_idx Layer index to validate
+     * @param num_layers Total number of layers
+     * @param context Optional context string for error messages
+     * @return Result<void> indicating success or error with message
+     */
+    static Result<void> validateLayerIndex(int layer_idx, int num_layers,
+                                           const std::string &context = "") {
+        if (layer_idx < 0 || layer_idx >= num_layers) {
+            return Result<void>::err(buildContext(
+                context, "Invalid layer_idx: " + std::to_string(layer_idx) + " (valid range: 0-" +
+                             std::to_string(num_layers - 1) + ")"));
+        }
+        return Result<void>::ok();
     }
-    return Result<void>::ok();
-  }
 
-private:
-  /**
-   * @brief Build context-prefixed error message
-   * @param context Context prefix
-   * @param message Error message
-   * @return Combined error message
-   */
-  static std::string buildContext(const std::string &context,
-                                   const std::string &message) {
-    if (context.empty()) {
-      return message;
+  private:
+    /**
+     * @brief Build context-prefixed error message
+     * @param context Context prefix
+     * @param message Error message
+     * @return Combined error message
+     */
+    static std::string buildContext(const std::string &context, const std::string &message) {
+        if (context.empty()) {
+            return message;
+        }
+        return context + ": " + message;
     }
-    return context + ": " + message;
-  }
 };
 
 // ── Convenience Macros ────────────────────────────────────────────────
@@ -324,22 +301,22 @@ class Validator {
  * @param condition Condition to validate
  * @param message Error message if condition is false
  */
-#define TLLM_VALIDATE(condition, message)                                       \
-  do {                                                                          \
-    if (!(condition)) {                                                         \
-      return tiny_llm::Result<void>::err(message);                              \
-    }                                                                           \
-  } while (0)
+#define TLLM_VALIDATE(condition, message)                                                          \
+    do {                                                                                           \
+        if (!(condition)) {                                                                        \
+            return tiny_llm::Result<void>::err(message);                                           \
+        }                                                                                          \
+    } while (0)
 
 /**
  * @brief Validate and propagate error if any
  * @param result Result to check
  */
-#define TLLM_VALIDATE_RESULT(result)                                            \
-  do {                                                                          \
-    if ((result).isErr()) {                                                     \
-      return tiny_llm::Result<void>::err((result).error());                     \
-    }                                                                           \
-  } while (0)
+#define TLLM_VALIDATE_RESULT(result)                                                               \
+    do {                                                                                           \
+        if ((result).isErr()) {                                                                    \
+            return tiny_llm::Result<void>::err((result).error());                                  \
+        }                                                                                          \
+    } while (0)
 
 } // namespace tiny_llm
diff --git a/kernels/attention.cu b/kernels/attention.cu
index e0d4c0e..0d81907 100644
--- a/kernels/attention.cu
+++ b/kernels/attention.cu
@@ -8,374 +8,349 @@ namespace kernels {
 
 // Decode attention kernel - one block per (batch, head)
 // Each block computes attention for one query against all keys
-__global__ void attention_decode_kernel(
-    const half *__restrict__ query,   // [batch, num_heads, 1, head_dim]
-    const half *__restrict__ k_cache, // [batch, num_heads, seq_len, head_dim]
-    const half *__restrict__ v_cache, // [batch, num_heads, seq_len, head_dim]
-    half *__restrict__ output,        // [batch, num_heads, 1, head_dim]
-    float scale, int num_heads, int seq_len, int head_dim) {
-  int batch_idx = blockIdx.x / num_heads;
-  int head_idx = blockIdx.x % num_heads;
-  int tid = threadIdx.x;
-  int block_size = blockDim.x;
-
-  // Pointers for this batch and head
-  const half *q = query + (batch_idx * num_heads + head_idx) * head_dim;
-  const half *k =
-      k_cache + (batch_idx * num_heads + head_idx) * seq_len * head_dim;
-  const half *v =
-      v_cache + (batch_idx * num_heads + head_idx) * seq_len * head_dim;
-  half *o = output + (batch_idx * num_heads + head_idx) * head_dim;
-
-  // Shared memory for scores and intermediate results
-  extern __shared__ float shared[];
-  float *scores = shared;                  // [seq_len]
-  float *shared_reduce = shared + seq_len; // [32] for reduction
-
-  // Compute attention scores: Q @ K^T
-  for (int pos = tid; pos < seq_len; pos += block_size) {
-    float score = 0.0f;
-    for (int d = 0; d < head_dim; ++d) {
-      float q_val = __half2float(q[d]);
-      float k_val = __half2float(k[pos * head_dim + d]);
-      score += q_val * k_val;
+__global__ void
+attention_decode_kernel(const half *__restrict__ query,   // [batch, num_heads, 1, head_dim]
+                        const half *__restrict__ k_cache, // [batch, num_heads, seq_len, head_dim]
+                        const half *__restrict__ v_cache, // [batch, num_heads, seq_len, head_dim]
+                        half *__restrict__ output,        // [batch, num_heads, 1, head_dim]
+                        float scale, int num_heads, int seq_len, int head_dim) {
+    int batch_idx = blockIdx.x / num_heads;
+    int head_idx = blockIdx.x % num_heads;
+    int tid = threadIdx.x;
+    int block_size = blockDim.x;
+
+    // Pointers for this batch and head
+    const half *q = query + (batch_idx * num_heads + head_idx) * head_dim;
+    const half *k = k_cache + (batch_idx * num_heads + head_idx) * seq_len * head_dim;
+    const half *v = v_cache + (batch_idx * num_heads + head_idx) * seq_len * head_dim;
+    half       *o = output + (batch_idx * num_heads + head_idx) * head_dim;
+
+    // Shared memory for scores and intermediate results
+    extern __shared__ float shared[];
+    float                  *scores = shared;                  // [seq_len]
+    float                  *shared_reduce = shared + seq_len; // [32] for reduction
+
+    // Compute attention scores: Q @ K^T
+    for (int pos = tid; pos < seq_len; pos += block_size) {
+        float score = 0.0f;
+        for (int d = 0; d < head_dim; ++d) {
+            float q_val = __half2float(q[d]);
+            float k_val = __half2float(k[pos * head_dim + d]);
+            score += q_val * k_val;
+        }
+        scores[pos] = score * scale;
     }
-    scores[pos] = score * scale;
-  }
-  __syncthreads();
-
-  // Softmax: find max
-  float max_score = -FLT_MAX;
-  for (int pos = tid; pos < seq_len; pos += block_size) {
-    max_score = fmaxf(max_score, scores[pos]);
-  }
-
-  // Reduce max across block
-  max_score = warp_reduce_max(max_score);
-  int lane = tid % 32;
-  int warp_id = tid / 32;
-  if (lane == 0) {
-    shared_reduce[warp_id] = max_score;
-  }
-  __syncthreads();
-
-  int num_warps = (block_size + 31) / 32;
-  if (warp_id == 0) {
-    max_score = (lane < num_warps) ? shared_reduce[lane] : -FLT_MAX;
+    __syncthreads();
+
+    // Softmax: find max
+    float max_score = -FLT_MAX;
+    for (int pos = tid; pos < seq_len; pos += block_size) {
+        max_score = fmaxf(max_score, scores[pos]);
+    }
+
+    // Reduce max across block
     max_score = warp_reduce_max(max_score);
-  }
-  __shared__ float global_max;
-  if (tid == 0) {
-    global_max = max_score;
-  }
-  __syncthreads();
-
-  // Softmax: compute exp and sum
-  float sum_exp = 0.0f;
-  for (int pos = tid; pos < seq_len; pos += block_size) {
-    float exp_score = expf(scores[pos] - global_max);
-    scores[pos] = exp_score;
-    sum_exp += exp_score;
-  }
-
-  // Reduce sum
-  sum_exp = warp_reduce_sum(sum_exp);
-  if (lane == 0) {
-    shared_reduce[warp_id] = sum_exp;
-  }
-  __syncthreads();
-
-  if (warp_id == 0) {
-    sum_exp = (lane < num_warps) ? shared_reduce[lane] : 0.0f;
+    int lane = tid % 32;
+    int warp_id = tid / 32;
+    if (lane == 0) {
+        shared_reduce[warp_id] = max_score;
+    }
+    __syncthreads();
+
+    int num_warps = (block_size + 31) / 32;
+    if (warp_id == 0) {
+        max_score = (lane < num_warps) ? shared_reduce[lane] : -FLT_MAX;
+        max_score = warp_reduce_max(max_score);
+    }
+    __shared__ float global_max;
+    if (tid == 0) {
+        global_max = max_score;
+    }
+    __syncthreads();
+
+    // Softmax: compute exp and sum
+    float sum_exp = 0.0f;
+    for (int pos = tid; pos < seq_len; pos += block_size) {
+        float exp_score = expf(scores[pos] - global_max);
+        scores[pos] = exp_score;
+        sum_exp += exp_score;
+    }
+
+    // Reduce sum
     sum_exp = warp_reduce_sum(sum_exp);
-  }
-  __shared__ float global_sum;
-  if (tid == 0) {
-    global_sum = sum_exp;
-  }
-  __syncthreads();
-
-  // Normalize scores
-  float inv_sum = 1.0f / (global_sum + 1e-6f);
-  for (int pos = tid; pos < seq_len; pos += block_size) {
-    scores[pos] *= inv_sum;
-  }
-  __syncthreads();
-
-  // Compute output: softmax(scores) @ V
-  for (int d = tid; d < head_dim; d += block_size) {
-    float out_val = 0.0f;
-    for (int pos = 0; pos < seq_len; ++pos) {
-      float v_val = __half2float(v[pos * head_dim + d]);
-      out_val += scores[pos] * v_val;
+    if (lane == 0) {
+        shared_reduce[warp_id] = sum_exp;
+    }
+    __syncthreads();
+
+    if (warp_id == 0) {
+        sum_exp = (lane < num_warps) ? shared_reduce[lane] : 0.0f;
+        sum_exp = warp_reduce_sum(sum_exp);
+    }
+    __shared__ float global_sum;
+    if (tid == 0) {
+        global_sum = sum_exp;
+    }
+    __syncthreads();
+
+    // Normalize scores
+    float inv_sum = 1.0f / (global_sum + 1e-6f);
+    for (int pos = tid; pos < seq_len; pos += block_size) {
+        scores[pos] *= inv_sum;
+    }
+    __syncthreads();
+
+    // Compute output: softmax(scores) @ V
+    for (int d = tid; d < head_dim; d += block_size) {
+        float out_val = 0.0f;
+        for (int pos = 0; pos < seq_len; ++pos) {
+            float v_val = __half2float(v[pos * head_dim + d]);
+            out_val += scores[pos] * v_val;
+        }
+        o[d] = __float2half(out_val);
     }
-    o[d] = __float2half(out_val);
-  }
 }
 
-void attention_decode(const half *query, const half *k_cache,
-                      const half *v_cache, half *output, float scale,
-                      int batch_size, int num_heads, int seq_len, int head_dim,
+void attention_decode(const half *query, const half *k_cache, const half *v_cache, half *output,
+                      float scale, int batch_size, int num_heads, int seq_len, int head_dim,
                       cudaStream_t stream) {
-  if (batch_size <= 0 || num_heads <= 0 || seq_len <= 0 || head_dim <= 0) {
-    return;
-  }
-  
-  int num_blocks = batch_size * num_heads;
-  int block_size = 256;
+    if (batch_size <= 0 || num_heads <= 0 || seq_len <= 0 || head_dim <= 0) {
+        return;
+    }
+
+    int num_blocks = batch_size * num_heads;
+    int block_size = 256;
 
-  size_t shared_size = (seq_len + 32) * sizeof(float);
+    size_t shared_size = (seq_len + 32) * sizeof(float);
 
-  attention_decode_kernel<<<num_blocks, block_size, shared_size, stream>>>(
-      query, k_cache, v_cache, output, scale, num_heads, seq_len, head_dim);
+    attention_decode_kernel<<<num_blocks, block_size, shared_size, stream>>>(
+        query, k_cache, v_cache, output, scale, num_heads, seq_len, head_dim);
 }
 
 // Prefill attention kernel with causal masking
 __global__ void attention_prefill_kernel(const half *__restrict__ query,
                                          const half *__restrict__ key,
-                                         const half *__restrict__ value,
-                                         half *__restrict__ output, float scale,
-                                         int num_heads, int seq_len,
-                                         int head_dim) {
-  int batch_idx = blockIdx.z;
-  int head_idx = blockIdx.y;
-  int query_pos = blockIdx.x;
-  int tid = threadIdx.x;
-  int block_size = blockDim.x;
-
-  // Pointers
-  const half *q =
-      query +
-      ((batch_idx * num_heads + head_idx) * seq_len + query_pos) * head_dim;
-  const half *k = key + (batch_idx * num_heads + head_idx) * seq_len * head_dim;
-  const half *v =
-      value + (batch_idx * num_heads + head_idx) * seq_len * head_dim;
-  half *o =
-      output +
-      ((batch_idx * num_heads + head_idx) * seq_len + query_pos) * head_dim;
-
-  extern __shared__ float shared[];
-  float *scores = shared;
-  float *shared_reduce = shared + seq_len;
-
-  // Compute attention scores with causal mask
-  for (int key_pos = tid; key_pos < seq_len; key_pos += block_size) {
-    if (key_pos <= query_pos) {
-      float score = 0.0f;
-      for (int d = 0; d < head_dim; ++d) {
-        float q_val = __half2float(q[d]);
-        float k_val = __half2float(k[key_pos * head_dim + d]);
-        score += q_val * k_val;
-      }
-      scores[key_pos] = score * scale;
-    } else {
-      scores[key_pos] = -FLT_MAX; // Causal mask
+                                         const half *__restrict__ value, half *__restrict__ output,
+                                         float scale, int num_heads, int seq_len, int head_dim) {
+    int batch_idx = blockIdx.z;
+    int head_idx = blockIdx.y;
+    int query_pos = blockIdx.x;
+    int tid = threadIdx.x;
+    int block_size = blockDim.x;
+
+    // Pointers
+    const half *q = query + ((batch_idx * num_heads + head_idx) * seq_len + query_pos) * head_dim;
+    const half *k = key + (batch_idx * num_heads + head_idx) * seq_len * head_dim;
+    const half *v = value + (batch_idx * num_heads + head_idx) * seq_len * head_dim;
+    half       *o = output + ((batch_idx * num_heads + head_idx) * seq_len + query_pos) * head_dim;
+
+    extern __shared__ float shared[];
+    float                  *scores = shared;
+    float                  *shared_reduce = shared + seq_len;
+
+    // Compute attention scores with causal mask
+    for (int key_pos = tid; key_pos < seq_len; key_pos += block_size) {
+        if (key_pos <= query_pos) {
+            float score = 0.0f;
+            for (int d = 0; d < head_dim; ++d) {
+                float q_val = __half2float(q[d]);
+                float k_val = __half2float(k[key_pos * head_dim + d]);
+                score += q_val * k_val;
+            }
+            scores[key_pos] = score * scale;
+        } else {
+            scores[key_pos] = -FLT_MAX; // Causal mask
+        }
+    }
+    __syncthreads();
+
+    // Softmax
+    float max_score = -FLT_MAX;
+    for (int pos = tid; pos < seq_len; pos += block_size) {
+        max_score = fmaxf(max_score, scores[pos]);
     }
-  }
-  __syncthreads();
-
-  // Softmax
-  float max_score = -FLT_MAX;
-  for (int pos = tid; pos < seq_len; pos += block_size) {
-    max_score = fmaxf(max_score, scores[pos]);
-  }
-
-  max_score = warp_reduce_max(max_score);
-  int lane = tid % 32;
-  int warp_id = tid / 32;
-  if (lane == 0)
-    shared_reduce[warp_id] = max_score;
-  __syncthreads();
-
-  int num_warps = (block_size + 31) / 32;
-  if (warp_id == 0) {
-    max_score = (lane < num_warps) ? shared_reduce[lane] : -FLT_MAX;
+
     max_score = warp_reduce_max(max_score);
-  }
-  __shared__ float global_max;
-  if (tid == 0)
-    global_max = max_score;
-  __syncthreads();
-
-  float sum_exp = 0.0f;
-  for (int pos = tid; pos < seq_len; pos += block_size) {
-    float exp_score = expf(scores[pos] - global_max);
-    scores[pos] = exp_score;
-    sum_exp += exp_score;
-  }
-
-  sum_exp = warp_reduce_sum(sum_exp);
-  if (lane == 0)
-    shared_reduce[warp_id] = sum_exp;
-  __syncthreads();
-
-  if (warp_id == 0) {
-    sum_exp = (lane < num_warps) ? shared_reduce[lane] : 0.0f;
+    int lane = tid % 32;
+    int warp_id = tid / 32;
+    if (lane == 0) shared_reduce[warp_id] = max_score;
+    __syncthreads();
+
+    int num_warps = (block_size + 31) / 32;
+    if (warp_id == 0) {
+        max_score = (lane < num_warps) ? shared_reduce[lane] : -FLT_MAX;
+        max_score = warp_reduce_max(max_score);
+    }
+    __shared__ float global_max;
+    if (tid == 0) global_max = max_score;
+    __syncthreads();
+
+    float sum_exp = 0.0f;
+    for (int pos = tid; pos < seq_len; pos += block_size) {
+        float exp_score = expf(scores[pos] - global_max);
+        scores[pos] = exp_score;
+        sum_exp += exp_score;
+    }
+
     sum_exp = warp_reduce_sum(sum_exp);
-  }
-  __shared__ float global_sum;
-  if (tid == 0)
-    global_sum = sum_exp;
-  __syncthreads();
-
-  float inv_sum = 1.0f / (global_sum + 1e-6f);
-  for (int pos = tid; pos < seq_len; pos += block_size) {
-    scores[pos] *= inv_sum;
-  }
-  __syncthreads();
-
-  // Output
-  for (int d = tid; d < head_dim; d += block_size) {
-    float out_val = 0.0f;
-    for (int pos = 0; pos < seq_len; ++pos) {
-      float v_val = __half2float(v[pos * head_dim + d]);
-      out_val += scores[pos] * v_val;
+    if (lane == 0) shared_reduce[warp_id] = sum_exp;
+    __syncthreads();
+
+    if (warp_id == 0) {
+        sum_exp = (lane < num_warps) ? shared_reduce[lane] : 0.0f;
+        sum_exp = warp_reduce_sum(sum_exp);
+    }
+    __shared__ float global_sum;
+    if (tid == 0) global_sum = sum_exp;
+    __syncthreads();
+
+    float inv_sum = 1.0f / (global_sum + 1e-6f);
+    for (int pos = tid; pos < seq_len; pos += block_size) {
+        scores[pos] *= inv_sum;
+    }
+    __syncthreads();
+
+    // Output
+    for (int d = tid; d < head_dim; d += block_size) {
+        float out_val = 0.0f;
+        for (int pos = 0; pos < seq_len; ++pos) {
+            float v_val = __half2float(v[pos * head_dim + d]);
+            out_val += scores[pos] * v_val;
+        }
+        o[d] = __float2half(out_val);
     }
-    o[d] = __float2half(out_val);
-  }
 }
 
-void attention_prefill(const half *query, const half *key, const half *value,
-                       half *output, float scale, int batch_size, int num_heads,
-                       int seq_len, int head_dim, cudaStream_t stream) {
-  if (batch_size <= 0 || num_heads <= 0 || seq_len <= 0 || head_dim <= 0) {
-    return;
-  }
-  
-  dim3 grid(seq_len, num_heads, batch_size);
-  int block_size = 256;
-  size_t shared_size = (seq_len + 32) * sizeof(float);
-
-  attention_prefill_kernel<<<grid, block_size, shared_size, stream>>>(
-      query, key, value, output, scale, num_heads, seq_len, head_dim);
+void attention_prefill(const half *query, const half *key, const half *value, half *output,
+                       float scale, int batch_size, int num_heads, int seq_len, int head_dim,
+                       cudaStream_t stream) {
+    if (batch_size <= 0 || num_heads <= 0 || seq_len <= 0 || head_dim <= 0) {
+        return;
+    }
+
+    dim3   grid(seq_len, num_heads, batch_size);
+    int    block_size = 256;
+    size_t shared_size = (seq_len + 32) * sizeof(float);
+
+    attention_prefill_kernel<<<grid, block_size, shared_size, stream>>>(
+        query, key, value, output, scale, num_heads, seq_len, head_dim);
 }
 
 // Get attention weights (for testing causal mask)
-__global__ void get_attention_weights_kernel(
-    const half *__restrict__ query, const half *__restrict__ key,
-    half *__restrict__ weights, float scale, int num_heads, int query_len,
-    int key_len, int head_dim, bool apply_causal_mask) {
-  int batch_idx = blockIdx.z;
-  int head_idx = blockIdx.y;
-  int query_pos = blockIdx.x;
-  int tid = threadIdx.x;
-  int block_size = blockDim.x;
-
-  const half *q =
-      query +
-      ((batch_idx * num_heads + head_idx) * query_len + query_pos) * head_dim;
-  const half *k = key + (batch_idx * num_heads + head_idx) * key_len * head_dim;
-  half *w =
-      weights +
-      ((batch_idx * num_heads + head_idx) * query_len + query_pos) * key_len;
-
-  for (int key_pos = tid; key_pos < key_len; key_pos += block_size) {
-    if (apply_causal_mask && key_pos > query_pos) {
-      w[key_pos] = __float2half(0.0f);
-    } else {
-      float score = 0.0f;
-      for (int d = 0; d < head_dim; ++d) {
-        float q_val = __half2float(q[d]);
-        float k_val = __half2float(k[key_pos * head_dim + d]);
-        score += q_val * k_val;
-      }
-      w[key_pos] = __float2half(score * scale);
+__global__ void get_attention_weights_kernel(const half *__restrict__ query,
+                                             const half *__restrict__ key,
+                                             half *__restrict__ weights, float scale, int num_heads,
+                                             int query_len, int key_len, int head_dim,
+                                             bool apply_causal_mask) {
+    int batch_idx = blockIdx.z;
+    int head_idx = blockIdx.y;
+    int query_pos = blockIdx.x;
+    int tid = threadIdx.x;
+    int block_size = blockDim.x;
+
+    const half *q = query + ((batch_idx * num_heads + head_idx) * query_len + query_pos) * head_dim;
+    const half *k = key + (batch_idx * num_heads + head_idx) * key_len * head_dim;
+    half *w = weights + ((batch_idx * num_heads + head_idx) * query_len + query_pos) * key_len;
+
+    for (int key_pos = tid; key_pos < key_len; key_pos += block_size) {
+        if (apply_causal_mask && key_pos > query_pos) {
+            w[key_pos] = __float2half(0.0f);
+        } else {
+            float score = 0.0f;
+            for (int d = 0; d < head_dim; ++d) {
+                float q_val = __half2float(q[d]);
+                float k_val = __half2float(k[key_pos * head_dim + d]);
+                score += q_val * k_val;
+            }
+            w[key_pos] = __float2half(score * scale);
+        }
     }
-  }
 }
 
-void get_attention_weights(const half *query, const half *key, half *weights,
-                           float scale, int batch_size, int num_heads,
-                           int query_len, int key_len, int head_dim,
+void get_attention_weights(const half *query, const half *key, half *weights, float scale,
+                           int batch_size, int num_heads, int query_len, int key_len, int head_dim,
                            bool apply_causal_mask, cudaStream_t stream) {
-  if (batch_size <= 0 || num_heads <= 0 || query_len <= 0 || key_len <= 0 || head_dim <= 0) {
-    return;
-  }
-  
-  dim3 grid(query_len, num_heads, batch_size);
-  int block_size = 256;
-
-  get_attention_weights_kernel<<<grid, block_size, 0, stream>>>(
-      query, key, weights, scale, num_heads, query_len, key_len, head_dim,
-      apply_causal_mask);
+    if (batch_size <= 0 || num_heads <= 0 || query_len <= 0 || key_len <= 0 || head_dim <= 0) {
+        return;
+    }
+
+    dim3 grid(query_len, num_heads, batch_size);
+    int  block_size = 256;
+
+    get_attention_weights_kernel<<<grid, block_size, 0, stream>>>(
+        query, key, weights, scale, num_heads, query_len, key_len, head_dim, apply_causal_mask);
 }
 
 // Simple softmax kernel
-__global__ void softmax_kernel(const half *__restrict__ input,
-                               half *__restrict__ output, int seq_len) {
-  int row = blockIdx.x;
-  int tid = threadIdx.x;
-  int block_size = blockDim.x;
-
-  const half *x = input + row * seq_len;
-  half *y = output + row * seq_len;
-
-  extern __shared__ float shared[];
-
-  // Find max
-  float max_val = -FLT_MAX;
-  for (int i = tid; i < seq_len; i += block_size) {
-    max_val = fmaxf(max_val, __half2float(x[i]));
-  }
-  max_val = warp_reduce_max(max_val);
-
-  int lane = tid % 32;
-  int warp_id = tid / 32;
-  if (lane == 0)
-    shared[warp_id] = max_val;
-  __syncthreads();
-
-  int num_warps = (block_size + 31) / 32;
-  if (warp_id == 0) {
-    max_val = (lane < num_warps) ? shared[lane] : -FLT_MAX;
+__global__ void softmax_kernel(const half *__restrict__ input, half *__restrict__ output,
+                               int seq_len) {
+    int row = blockIdx.x;
+    int tid = threadIdx.x;
+    int block_size = blockDim.x;
+
+    const half *x = input + row * seq_len;
+    half       *y = output + row * seq_len;
+
+    extern __shared__ float shared[];
+
+    // Find max
+    float max_val = -FLT_MAX;
+    for (int i = tid; i < seq_len; i += block_size) {
+        max_val = fmaxf(max_val, __half2float(x[i]));
+    }
     max_val = warp_reduce_max(max_val);
-  }
-  __shared__ float global_max;
-  if (tid == 0)
-    global_max = max_val;
-  __syncthreads();
-
-  // Compute exp and sum
-  float sum = 0.0f;
-  for (int i = tid; i < seq_len; i += block_size) {
-    float exp_val = expf(__half2float(x[i]) - global_max);
-    shared[i] = exp_val;
-    sum += exp_val;
-  }
-  __syncthreads();
-
-  sum = warp_reduce_sum(sum);
-  if (lane == 0)
-    shared[seq_len + warp_id] = sum;
-  __syncthreads();
-
-  if (warp_id == 0) {
-    sum = (lane < num_warps) ? shared[seq_len + lane] : 0.0f;
+
+    int lane = tid % 32;
+    int warp_id = tid / 32;
+    if (lane == 0) shared[warp_id] = max_val;
+    __syncthreads();
+
+    int num_warps = (block_size + 31) / 32;
+    if (warp_id == 0) {
+        max_val = (lane < num_warps) ? shared[lane] : -FLT_MAX;
+        max_val = warp_reduce_max(max_val);
+    }
+    __shared__ float global_max;
+    if (tid == 0) global_max = max_val;
+    __syncthreads();
+
+    // Compute exp and sum
+    float sum = 0.0f;
+    for (int i = tid; i < seq_len; i += block_size) {
+        float exp_val = expf(__half2float(x[i]) - global_max);
+        shared[i] = exp_val;
+        sum += exp_val;
+    }
+    __syncthreads();
+
     sum = warp_reduce_sum(sum);
-  }
-  __shared__ float global_sum;
-  if (tid == 0)
-    global_sum = sum;
-  __syncthreads();
-
-  // Normalize
-  float inv_sum = 1.0f / (global_sum + 1e-6f);
-  for (int i = tid; i < seq_len; i += block_size) {
-    y[i] = __float2half(shared[i] * inv_sum);
-  }
+    if (lane == 0) shared[seq_len + warp_id] = sum;
+    __syncthreads();
+
+    if (warp_id == 0) {
+        sum = (lane < num_warps) ? shared[seq_len + lane] : 0.0f;
+        sum = warp_reduce_sum(sum);
+    }
+    __shared__ float global_sum;
+    if (tid == 0) global_sum = sum;
+    __syncthreads();
+
+    // Normalize
+    float inv_sum = 1.0f / (global_sum + 1e-6f);
+    for (int i = tid; i < seq_len; i += block_size) {
+        y[i] = __float2half(shared[i] * inv_sum);
+    }
 }
 
-void softmax(const half *input, half *output, int batch_size, int seq_len,
-             cudaStream_t stream) {
-  if (batch_size <= 0 || seq_len <= 0) {
-    return;
-  }
-  
-  int block_size = 256;
-  size_t shared_size = (seq_len + 32) * sizeof(float);
-
-  softmax_kernel<<<batch_size, block_size, shared_size, stream>>>(input, output,
-                                                                  seq_len);
+void softmax(const half *input, half *output, int batch_size, int seq_len, cudaStream_t stream) {
+    if (batch_size <= 0 || seq_len <= 0) {
+        return;
+    }
+
+    int    block_size = 256;
+    size_t shared_size = (seq_len + 32) * sizeof(float);
+
+    softmax_kernel<<<batch_size, block_size, shared_size, stream>>>(input, output, seq_len);
 }
 
 } // namespace kernels
diff --git a/kernels/attention.cuh b/kernels/attention.cuh
index b3ea80a..7443a99 100644
--- a/kernels/attention.cuh
+++ b/kernels/attention.cuh
@@ -12,33 +12,27 @@ namespace kernels {
 // V: [batch, num_heads, seq_len, head_dim] - cached values
 // O: [batch, num_heads, 1, head_dim] - output
 
-void attention_decode(const half *__restrict__ query,
-                      const half *__restrict__ k_cache,
-                      const half *__restrict__ v_cache,
-                      half *__restrict__ output, float scale, int batch_size,
-                      int num_heads, int seq_len, int head_dim,
+void attention_decode(const half *__restrict__ query, const half *__restrict__ k_cache,
+                      const half *__restrict__ v_cache, half *__restrict__ output, float scale,
+                      int batch_size, int num_heads, int seq_len, int head_dim,
                       cudaStream_t stream = 0);
 
 // Prefill attention (full sequence)
 // Q, K, V: [batch, num_heads, seq_len, head_dim]
 // O: [batch, num_heads, seq_len, head_dim]
-void attention_prefill(const half *__restrict__ query,
-                       const half *__restrict__ key,
-                       const half *__restrict__ value,
-                       half *__restrict__ output, float scale, int batch_size,
-                       int num_heads, int seq_len, int head_dim,
+void attention_prefill(const half *__restrict__ query, const half *__restrict__ key,
+                       const half *__restrict__ value, half *__restrict__ output, float scale,
+                       int batch_size, int num_heads, int seq_len, int head_dim,
                        cudaStream_t stream = 0);
 
 // Softmax kernel (for testing)
-void softmax(const half *__restrict__ input, half *__restrict__ output,
-             int batch_size, int seq_len, cudaStream_t stream = 0);
+void softmax(const half *__restrict__ input, half *__restrict__ output, int batch_size, int seq_len,
+             cudaStream_t stream = 0);
 
 // Get attention weights for testing causal mask
-void get_attention_weights(const half *__restrict__ query,
-                           const half *__restrict__ key,
-                           half *__restrict__ weights, float scale,
-                           int batch_size, int num_heads, int query_len,
-                           int key_len, int head_dim, bool apply_causal_mask,
+void get_attention_weights(const half *__restrict__ query, const half *__restrict__ key,
+                           half *__restrict__ weights, float scale, int batch_size, int num_heads,
+                           int query_len, int key_len, int head_dim, bool apply_causal_mask,
                            cudaStream_t stream = 0);
 
 } // namespace kernels
diff --git a/kernels/elementwise.cu b/kernels/elementwise.cu
index 65cab84..b91dea6 100644
--- a/kernels/elementwise.cu
+++ b/kernels/elementwise.cu
@@ -4,79 +4,69 @@ namespace tiny_llm {
 namespace kernels {
 
 namespace {
-__global__ void add_inplace_kernel(half *data, const half *add,
-                                   int num_elements) {
-  int idx = blockIdx.x * blockDim.x + threadIdx.x;
-  if (idx < num_elements) {
-    float a = __half2float(data[idx]);
-    float b = __half2float(add[idx]);
-    data[idx] = __float2half(a + b);
-  }
+__global__ void add_inplace_kernel(half *data, const half *add, int num_elements) {
+    int idx = blockIdx.x * blockDim.x + threadIdx.x;
+    if (idx < num_elements) {
+        float a = __half2float(data[idx]);
+        float b = __half2float(add[idx]);
+        data[idx] = __float2half(a + b);
+    }
 }
 
-__global__ void silu_mul_inplace_kernel(half *gate, const half *up,
-                                        int num_elements) {
-  int idx = blockIdx.x * blockDim.x + threadIdx.x;
-  if (idx < num_elements) {
-    float g = __half2float(gate[idx]);
-    float u = __half2float(up[idx]);
-    float silu = g / (1.0f + expf(-g));
-    gate[idx] = __float2half(silu * u);
-  }
+__global__ void silu_mul_inplace_kernel(half *gate, const half *up, int num_elements) {
+    int idx = blockIdx.x * blockDim.x + threadIdx.x;
+    if (idx < num_elements) {
+        float g = __half2float(gate[idx]);
+        float u = __half2float(up[idx]);
+        float silu = g / (1.0f + expf(-g));
+        gate[idx] = __float2half(silu * u);
+    }
 }
 
-__global__ void gather_embeddings_kernel(const int *tokens, const half *embedding,
-                                         half *output, int num_tokens,
-                                         int hidden_dim, int vocab_size) {
-  int idx = blockIdx.x * blockDim.x + threadIdx.x;
-  int total = num_tokens * hidden_dim;
-  if (idx >= total) {
-    return;
-  }
+__global__ void gather_embeddings_kernel(const int *tokens, const half *embedding, half *output,
+                                         int num_tokens, int hidden_dim, int vocab_size) {
+    int idx = blockIdx.x * blockDim.x + threadIdx.x;
+    int total = num_tokens * hidden_dim;
+    if (idx >= total) {
+        return;
+    }
 
-  int token_idx = idx / hidden_dim;
-  int hidden_idx = idx % hidden_dim;
-  int token_id = tokens[token_idx];
+    int token_idx = idx / hidden_dim;
+    int hidden_idx = idx % hidden_dim;
+    int token_id = tokens[token_idx];
 
-  if (token_id >= 0 && token_id < vocab_size) {
-    output[idx] = embedding[token_id * hidden_dim + hidden_idx];
-  } else {
-    output[idx] = __float2half(0.0f);
-  }
+    if (token_id >= 0 && token_id < vocab_size) {
+        output[idx] = embedding[token_id * hidden_dim + hidden_idx];
+    } else {
+        output[idx] = __float2half(0.0f);
+    }
 }
 } // namespace
 
-void add_inplace(half *data, const half *add, int num_elements,
-                 cudaStream_t stream) {
-  if (num_elements <= 0)
-    return;
-  int block_size = 256;
-  int grid_size = (num_elements + block_size - 1) / block_size;
-  add_inplace_kernel<<<grid_size, block_size, 0, stream>>>(data, add,
-                                                           num_elements);
+void add_inplace(half *data, const half *add, int num_elements, cudaStream_t stream) {
+    if (num_elements <= 0) return;
+    int block_size = 256;
+    int grid_size = (num_elements + block_size - 1) / block_size;
+    add_inplace_kernel<<<grid_size, block_size, 0, stream>>>(data, add, num_elements);
 }
 
-void silu_mul_inplace(half *gate, const half *up, int num_elements,
-                      cudaStream_t stream) {
-  if (num_elements <= 0)
-    return;
-  int block_size = 256;
-  int grid_size = (num_elements + block_size - 1) / block_size;
-  silu_mul_inplace_kernel<<<grid_size, block_size, 0, stream>>>(gate, up,
-                                                                num_elements);
+void silu_mul_inplace(half *gate, const half *up, int num_elements, cudaStream_t stream) {
+    if (num_elements <= 0) return;
+    int block_size = 256;
+    int grid_size = (num_elements + block_size - 1) / block_size;
+    silu_mul_inplace_kernel<<<grid_size, block_size, 0, stream>>>(gate, up, num_elements);
 }
 
-void gather_embeddings(const int *tokens, const half *embedding, half *output,
-                       int num_tokens, int hidden_dim, int vocab_size,
-                       cudaStream_t stream) {
-  if (num_tokens <= 0 || hidden_dim <= 0 || !tokens || !embedding || !output) {
-    return;
-  }
-  int total = num_tokens * hidden_dim;
-  int block_size = 256;
-  int grid_size = (total + block_size - 1) / block_size;
-  gather_embeddings_kernel<<<grid_size, block_size, 0, stream>>>(
-      tokens, embedding, output, num_tokens, hidden_dim, vocab_size);
+void gather_embeddings(const int *tokens, const half *embedding, half *output, int num_tokens,
+                       int hidden_dim, int vocab_size, cudaStream_t stream) {
+    if (num_tokens <= 0 || hidden_dim <= 0 || !tokens || !embedding || !output) {
+        return;
+    }
+    int total = num_tokens * hidden_dim;
+    int block_size = 256;
+    int grid_size = (total + block_size - 1) / block_size;
+    gather_embeddings_kernel<<<grid_size, block_size, 0, stream>>>(
+        tokens, embedding, output, num_tokens, hidden_dim, vocab_size);
 }
 
 } // namespace kernels
diff --git a/kernels/elementwise.cuh b/kernels/elementwise.cuh
index 5b83280..d73c9ba 100644
--- a/kernels/elementwise.cuh
+++ b/kernels/elementwise.cuh
@@ -7,17 +7,14 @@ namespace tiny_llm {
 namespace kernels {
 
 // In-place elementwise add: data[i] += add[i]
-void add_inplace(half *data, const half *add, int num_elements,
-                 cudaStream_t stream = 0);
+void add_inplace(half *data, const half *add, int num_elements, cudaStream_t stream = 0);
 
 // In-place SiLU + multiply: gate[i] = silu(gate[i]) * up[i]
-void silu_mul_inplace(half *gate, const half *up, int num_elements,
-                      cudaStream_t stream = 0);
+void silu_mul_inplace(half *gate, const half *up, int num_elements, cudaStream_t stream = 0);
 
 // Embedding gather: output[token_idx, hidden_idx] = embedding[token_id, hidden_idx]
-void gather_embeddings(const int *tokens, const half *embedding, half *output,
-                       int num_tokens, int hidden_dim, int vocab_size,
-                       cudaStream_t stream = 0);
+void gather_embeddings(const int *tokens, const half *embedding, half *output, int num_tokens,
+                       int hidden_dim, int vocab_size, cudaStream_t stream = 0);
 
 } // namespace kernels
 } // namespace tiny_llm
diff --git a/kernels/rmsnorm.cu b/kernels/rmsnorm.cu
index dbc06d3..a02fac5 100644
--- a/kernels/rmsnorm.cu
+++ b/kernels/rmsnorm.cu
@@ -7,215 +7,202 @@ namespace kernels {
 
 // RMSNorm kernel - one block per row
 // Uses warp shuffle for efficient reduction
-__global__ void rmsnorm_kernel(const half *__restrict__ input,
-                               const half *__restrict__ weight,
-                               half *__restrict__ output, int hidden_dim,
-                               float eps) {
-  int row = blockIdx.x;
-  int tid = threadIdx.x;
-  int block_size = blockDim.x;
-
-  const half *x = input + row * hidden_dim;
-  half *y = output + row * hidden_dim;
-
-  // Compute sum of squares
-  float sum_sq = 0.0f;
-  for (int i = tid; i < hidden_dim; i += block_size) {
-    float val = __half2float(x[i]);
-    sum_sq += val * val;
-  }
-
-  // Block-level reduction
-  __shared__ float shared_mem[32]; // One per warp
-
-  // Warp reduction
-  sum_sq = warp_reduce_sum(sum_sq);
-
-  // Write warp results to shared memory
-  int lane = tid % 32;
-  int warp_id = tid / 32;
-  if (lane == 0) {
-    shared_mem[warp_id] = sum_sq;
-  }
-  __syncthreads();
-
-  // Final reduction in first warp
-  int num_warps = (block_size + 31) / 32;
-  if (warp_id == 0) {
-    sum_sq = (lane < num_warps) ? shared_mem[lane] : 0.0f;
+__global__ void rmsnorm_kernel(const half *__restrict__ input, const half *__restrict__ weight,
+                               half *__restrict__ output, int hidden_dim, float eps) {
+    int row = blockIdx.x;
+    int tid = threadIdx.x;
+    int block_size = blockDim.x;
+
+    const half *x = input + row * hidden_dim;
+    half       *y = output + row * hidden_dim;
+
+    // Compute sum of squares
+    float sum_sq = 0.0f;
+    for (int i = tid; i < hidden_dim; i += block_size) {
+        float val = __half2float(x[i]);
+        sum_sq += val * val;
+    }
+
+    // Block-level reduction
+    __shared__ float shared_mem[32]; // One per warp
+
+    // Warp reduction
     sum_sq = warp_reduce_sum(sum_sq);
-  }
-
-  // Broadcast result
-  __shared__ float rms_inv;
-  if (tid == 0) {
-    float mean_sq = sum_sq / hidden_dim;
-    rms_inv = rsqrtf(mean_sq + eps);
-  }
-  __syncthreads();
-
-  // Apply normalization and weight
-  for (int i = tid; i < hidden_dim; i += block_size) {
-    float val = __half2float(x[i]);
-    float w = __half2float(weight[i]);
-    float normalized = val * rms_inv * w;
-    y[i] = __float2half(normalized);
-  }
+
+    // Write warp results to shared memory
+    int lane = tid % 32;
+    int warp_id = tid / 32;
+    if (lane == 0) {
+        shared_mem[warp_id] = sum_sq;
+    }
+    __syncthreads();
+
+    // Final reduction in first warp
+    int num_warps = (block_size + 31) / 32;
+    if (warp_id == 0) {
+        sum_sq = (lane < num_warps) ? shared_mem[lane] : 0.0f;
+        sum_sq = warp_reduce_sum(sum_sq);
+    }
+
+    // Broadcast result
+    __shared__ float rms_inv;
+    if (tid == 0) {
+        float mean_sq = sum_sq / hidden_dim;
+        rms_inv = rsqrtf(mean_sq + eps);
+    }
+    __syncthreads();
+
+    // Apply normalization and weight
+    for (int i = tid; i < hidden_dim; i += block_size) {
+        float val = __half2float(x[i]);
+        float w = __half2float(weight[i]);
+        float normalized = val * rms_inv * w;
+        y[i] = __float2half(normalized);
+    }
 }
 
-void rmsnorm(const half *input, const half *weight, half *output,
-             int batch_size, int hidden_dim, float eps, cudaStream_t stream) {
-  if (batch_size <= 0 || hidden_dim <= 0) {
-    return;
-  }
-  
-  int block_size = 256;
-  if (hidden_dim <= 256)
-    block_size = 128;
-  if (hidden_dim <= 128)
-    block_size = 64;
-
-  rmsnorm_kernel<<<batch_size, block_size, 0, stream>>>(input, weight, output,
-                                                        hidden_dim, eps);
+void rmsnorm(const half *input, const half *weight, half *output, int batch_size, int hidden_dim,
+             float eps, cudaStream_t stream) {
+    if (batch_size <= 0 || hidden_dim <= 0) {
+        return;
+    }
+
+    int block_size = 256;
+    if (hidden_dim <= 256) block_size = 128;
+    if (hidden_dim <= 128) block_size = 64;
+
+    rmsnorm_kernel<<<batch_size, block_size, 0, stream>>>(input, weight, output, hidden_dim, eps);
 }
 
 // In-place version
-__global__ void rmsnorm_inplace_kernel(half *__restrict__ x,
-                                       const half *__restrict__ weight,
+__global__ void rmsnorm_inplace_kernel(half *__restrict__ x, const half *__restrict__ weight,
                                        int hidden_dim, float eps) {
-  int row = blockIdx.x;
-  int tid = threadIdx.x;
-  int block_size = blockDim.x;
-
-  half *data = x + row * hidden_dim;
-
-  // Compute sum of squares
-  float sum_sq = 0.0f;
-  for (int i = tid; i < hidden_dim; i += block_size) {
-    float val = __half2float(data[i]);
-    sum_sq += val * val;
-  }
-
-  // Block-level reduction
-  __shared__ float shared_mem[32];
-
-  sum_sq = warp_reduce_sum(sum_sq);
-
-  int lane = tid % 32;
-  int warp_id = tid / 32;
-  if (lane == 0) {
-    shared_mem[warp_id] = sum_sq;
-  }
-  __syncthreads();
-
-  int num_warps = (block_size + 31) / 32;
-  if (warp_id == 0) {
-    sum_sq = (lane < num_warps) ? shared_mem[lane] : 0.0f;
+    int row = blockIdx.x;
+    int tid = threadIdx.x;
+    int block_size = blockDim.x;
+
+    half *data = x + row * hidden_dim;
+
+    // Compute sum of squares
+    float sum_sq = 0.0f;
+    for (int i = tid; i < hidden_dim; i += block_size) {
+        float val = __half2float(data[i]);
+        sum_sq += val * val;
+    }
+
+    // Block-level reduction
+    __shared__ float shared_mem[32];
+
     sum_sq = warp_reduce_sum(sum_sq);
-  }
-
-  __shared__ float rms_inv;
-  if (tid == 0) {
-    float mean_sq = sum_sq / hidden_dim;
-    rms_inv = rsqrtf(mean_sq + eps);
-  }
-  __syncthreads();
-
-  // Apply normalization and weight in-place
-  for (int i = tid; i < hidden_dim; i += block_size) {
-    float val = __half2float(data[i]);
-    float w = __half2float(weight[i]);
-    float normalized = val * rms_inv * w;
-    data[i] = __float2half(normalized);
-  }
+
+    int lane = tid % 32;
+    int warp_id = tid / 32;
+    if (lane == 0) {
+        shared_mem[warp_id] = sum_sq;
+    }
+    __syncthreads();
+
+    int num_warps = (block_size + 31) / 32;
+    if (warp_id == 0) {
+        sum_sq = (lane < num_warps) ? shared_mem[lane] : 0.0f;
+        sum_sq = warp_reduce_sum(sum_sq);
+    }
+
+    __shared__ float rms_inv;
+    if (tid == 0) {
+        float mean_sq = sum_sq / hidden_dim;
+        rms_inv = rsqrtf(mean_sq + eps);
+    }
+    __syncthreads();
+
+    // Apply normalization and weight in-place
+    for (int i = tid; i < hidden_dim; i += block_size) {
+        float val = __half2float(data[i]);
+        float w = __half2float(weight[i]);
+        float normalized = val * rms_inv * w;
+        data[i] = __float2half(normalized);
+    }
 }
 
-void rmsnorm_inplace(half *x, const half *weight, int batch_size,
-                     int hidden_dim, float eps, cudaStream_t stream) {
-  if (batch_size <= 0 || hidden_dim <= 0) {
-    return;
-  }
-  
-  int block_size = 256;
-  if (hidden_dim <= 256)
-    block_size = 128;
-  if (hidden_dim <= 128)
-    block_size = 64;
-
-  rmsnorm_inplace_kernel<<<batch_size, block_size, 0, stream>>>(
-      x, weight, hidden_dim, eps);
+void rmsnorm_inplace(half *x, const half *weight, int batch_size, int hidden_dim, float eps,
+                     cudaStream_t stream) {
+    if (batch_size <= 0 || hidden_dim <= 0) {
+        return;
+    }
+
+    int block_size = 256;
+    if (hidden_dim <= 256) block_size = 128;
+    if (hidden_dim <= 128) block_size = 64;
+
+    rmsnorm_inplace_kernel<<<batch_size, block_size, 0, stream>>>(x, weight, hidden_dim, eps);
 }
 
 // Fused RMSNorm + residual
 __global__ void rmsnorm_residual_kernel(const half *__restrict__ input,
                                         const half *__restrict__ residual,
-                                        const half *__restrict__ weight,
-                                        half *__restrict__ output,
+                                        const half *__restrict__ weight, half *__restrict__ output,
                                         int hidden_dim, float eps) {
-  int row = blockIdx.x;
-  int tid = threadIdx.x;
-  int block_size = blockDim.x;
-
-  const half *x = input + row * hidden_dim;
-  const half *r = residual + row * hidden_dim;
-  half *y = output + row * hidden_dim;
-
-  // First pass: compute sum of squares of (x + residual)
-  float sum_sq = 0.0f;
-  for (int i = tid; i < hidden_dim; i += block_size) {
-    float val = __half2float(x[i]) + __half2float(r[i]);
-    sum_sq += val * val;
-  }
-
-  // Block-level reduction
-  __shared__ float shared_mem[32];
-
-  sum_sq = warp_reduce_sum(sum_sq);
-
-  int lane = tid % 32;
-  int warp_id = tid / 32;
-  if (lane == 0) {
-    shared_mem[warp_id] = sum_sq;
-  }
-  __syncthreads();
-
-  int num_warps = (block_size + 31) / 32;
-  if (warp_id == 0) {
-    sum_sq = (lane < num_warps) ? shared_mem[lane] : 0.0f;
+    int row = blockIdx.x;
+    int tid = threadIdx.x;
+    int block_size = blockDim.x;
+
+    const half *x = input + row * hidden_dim;
+    const half *r = residual + row * hidden_dim;
+    half       *y = output + row * hidden_dim;
+
+    // First pass: compute sum of squares of (x + residual)
+    float sum_sq = 0.0f;
+    for (int i = tid; i < hidden_dim; i += block_size) {
+        float val = __half2float(x[i]) + __half2float(r[i]);
+        sum_sq += val * val;
+    }
+
+    // Block-level reduction
+    __shared__ float shared_mem[32];
+
     sum_sq = warp_reduce_sum(sum_sq);
-  }
-
-  __shared__ float rms_inv;
-  if (tid == 0) {
-    float mean_sq = sum_sq / hidden_dim;
-    rms_inv = rsqrtf(mean_sq + eps);
-  }
-  __syncthreads();
-
-  // Second pass: apply normalization
-  for (int i = tid; i < hidden_dim; i += block_size) {
-    float val = __half2float(x[i]) + __half2float(r[i]);
-    float w = __half2float(weight[i]);
-    float normalized = val * rms_inv * w;
-    y[i] = __float2half(normalized);
-  }
+
+    int lane = tid % 32;
+    int warp_id = tid / 32;
+    if (lane == 0) {
+        shared_mem[warp_id] = sum_sq;
+    }
+    __syncthreads();
+
+    int num_warps = (block_size + 31) / 32;
+    if (warp_id == 0) {
+        sum_sq = (lane < num_warps) ? shared_mem[lane] : 0.0f;
+        sum_sq = warp_reduce_sum(sum_sq);
+    }
+
+    __shared__ float rms_inv;
+    if (tid == 0) {
+        float mean_sq = sum_sq / hidden_dim;
+        rms_inv = rsqrtf(mean_sq + eps);
+    }
+    __syncthreads();
+
+    // Second pass: apply normalization
+    for (int i = tid; i < hidden_dim; i += block_size) {
+        float val = __half2float(x[i]) + __half2float(r[i]);
+        float w = __half2float(weight[i]);
+        float normalized = val * rms_inv * w;
+        y[i] = __float2half(normalized);
+    }
 }
 
-void rmsnorm_residual(const half *input, const half *residual,
-                      const half *weight, half *output, int batch_size,
-                      int hidden_dim, float eps, cudaStream_t stream) {
-  if (batch_size <= 0 || hidden_dim <= 0) {
-    return;
-  }
-  
-  int block_size = 256;
-  if (hidden_dim <= 256)
-    block_size = 128;
-  if (hidden_dim <= 128)
-    block_size = 64;
-
-  rmsnorm_residual_kernel<<<batch_size, block_size, 0, stream>>>(
-      input, residual, weight, output, hidden_dim, eps);
+void rmsnorm_residual(const half *input, const half *residual, const half *weight, half *output,
+                      int batch_size, int hidden_dim, float eps, cudaStream_t stream) {
+    if (batch_size <= 0 || hidden_dim <= 0) {
+        return;
+    }
+
+    int block_size = 256;
+    if (hidden_dim <= 256) block_size = 128;
+    if (hidden_dim <= 128) block_size = 64;
+
+    rmsnorm_residual_kernel<<<batch_size, block_size, 0, stream>>>(input, residual, weight, output,
+                                                                   hidden_dim, eps);
 }
 
 } // namespace kernels
diff --git a/kernels/rmsnorm.cuh b/kernels/rmsnorm.cuh
index 2bb8082..2c4885f 100644
--- a/kernels/rmsnorm.cuh
+++ b/kernels/rmsnorm.cuh
@@ -12,21 +12,18 @@ namespace kernels {
 // Output: y      [batch, hidden_dim] or [hidden_dim]
 
 void rmsnorm(const half *__restrict__ input, const half *__restrict__ weight,
-             half *__restrict__ output, int batch_size, int hidden_dim,
-             float eps, cudaStream_t stream = 0);
+             half *__restrict__ output, int batch_size, int hidden_dim, float eps,
+             cudaStream_t stream = 0);
 
 // In-place RMSNorm (output overwrites input)
-void rmsnorm_inplace(half *__restrict__ x, const half *__restrict__ weight,
-                     int batch_size, int hidden_dim, float eps,
-                     cudaStream_t stream = 0);
+void rmsnorm_inplace(half *__restrict__ x, const half *__restrict__ weight, int batch_size,
+                     int hidden_dim, float eps, cudaStream_t stream = 0);
 
 // Fused RMSNorm + residual add
 // output = rmsnorm(x + residual)
-void rmsnorm_residual(const half *__restrict__ input,
-                      const half *__restrict__ residual,
-                      const half *__restrict__ weight,
-                      half *__restrict__ output, int batch_size, int hidden_dim,
-                      float eps, cudaStream_t stream = 0);
+void rmsnorm_residual(const half *__restrict__ input, const half *__restrict__ residual,
+                      const half *__restrict__ weight, half *__restrict__ output, int batch_size,
+                      int hidden_dim, float eps, cudaStream_t stream = 0);
 
 } // namespace kernels
 } // namespace tiny_llm
diff --git a/kernels/w8a16_matmul.cu b/kernels/w8a16_matmul.cu
index aa40464..6a51499 100644
--- a/kernels/w8a16_matmul.cu
+++ b/kernels/w8a16_matmul.cu
@@ -6,112 +6,108 @@ namespace kernels {
 
 // Dequantization kernel
 __global__ void dequantize_kernel(const int8_t *__restrict__ weight_int8,
-                                  const half *__restrict__ scales,
-                                  half *__restrict__ weight_fp16, int K, int N,
-                                  int group_size) {
-  int idx = blockIdx.x * blockDim.x + threadIdx.x;
-  int total = K * N;
-
-  if (idx < total) {
-    int k = idx / N;
-    int n = idx % N;
-
-    int group_idx = k / group_size;
-    int scale_idx = group_idx * N + n;
-
-    float w_int = static_cast<float>(weight_int8[idx]);
-    float s = __half2float(scales[scale_idx]);
-    weight_fp16[idx] = __float2half(w_int * s);
-  }
+                                  const half *__restrict__ scales, half *__restrict__ weight_fp16,
+                                  int K, int N, int group_size) {
+    int idx = blockIdx.x * blockDim.x + threadIdx.x;
+    int total = K * N;
+
+    if (idx < total) {
+        int k = idx / N;
+        int n = idx % N;
+
+        int group_idx = k / group_size;
+        int scale_idx = group_idx * N + n;
+
+        float w_int = static_cast<float>(weight_int8[idx]);
+        float s = __half2float(scales[scale_idx]);
+        weight_fp16[idx] = __float2half(w_int * s);
+    }
 }
 
-void dequantize_weights(const int8_t *weight_int8, const half *scales,
-                        half *weight_fp16, int K, int N, int group_size,
-                        cudaStream_t stream) {
-  if (K <= 0 || N <= 0 || group_size <= 0) {
-    return;
-  }
-  
-  int total = K * N;
-  int block_size = 256;
-  int grid_size = (total + block_size - 1) / block_size;
-
-  dequantize_kernel<<<grid_size, block_size, 0, stream>>>(
-      weight_int8, scales, weight_fp16, K, N, group_size);
+void dequantize_weights(const int8_t *weight_int8, const half *scales, half *weight_fp16, int K,
+                        int N, int group_size, cudaStream_t stream) {
+    if (K <= 0 || N <= 0 || group_size <= 0) {
+        return;
+    }
+
+    int total = K * N;
+    int block_size = 256;
+    int grid_size = (total + block_size - 1) / block_size;
+
+    dequantize_kernel<<<grid_size, block_size, 0, stream>>>(weight_int8, scales, weight_fp16, K, N,
+                                                            group_size);
 }
 
 // Simple FP16 matmul reference kernel
-__global__ void fp16_matmul_kernel(const half *__restrict__ A,
-                                   const half *__restrict__ B,
+__global__ void fp16_matmul_kernel(const half *__restrict__ A, const half *__restrict__ B,
                                    half *__restrict__ C, int M, int N, int K) {
-  int row = blockIdx.y * blockDim.y + threadIdx.y;
-  int col = blockIdx.x * blockDim.x + threadIdx.x;
-
-  if (row < M && col < N) {
-    float sum = 0.0f;
-    for (int k = 0; k < K; ++k) {
-      float a = __half2float(A[row * K + k]);
-      float b = __half2float(B[k * N + col]);
-      sum += a * b;
+    int row = blockIdx.y * blockDim.y + threadIdx.y;
+    int col = blockIdx.x * blockDim.x + threadIdx.x;
+
+    if (row < M && col < N) {
+        float sum = 0.0f;
+        for (int k = 0; k < K; ++k) {
+            float a = __half2float(A[row * K + k]);
+            float b = __half2float(B[k * N + col]);
+            sum += a * b;
+        }
+        C[row * N + col] = __float2half(sum);
     }
-    C[row * N + col] = __float2half(sum);
-  }
 }
 
-void fp16_matmul_reference(const half *input, const half *weight, half *output,
-                           int M, int N, int K, cudaStream_t stream) {
-  if (M <= 0 || N <= 0 || K <= 0) {
-    return;
-  }
-  
-  dim3 block(16, 16);
-  dim3 grid((N + 15) / 16, (M + 15) / 16);
-
-  fp16_matmul_kernel<<<grid, block, 0, stream>>>(input, weight, output, M, N,
-                                                 K);
+void fp16_matmul_reference(const half *input, const half *weight, half *output, int M, int N, int K,
+                           cudaStream_t stream) {
+    if (M <= 0 || N <= 0 || K <= 0) {
+        return;
+    }
+
+    dim3 block(16, 16);
+    dim3 grid((N + 15) / 16, (M + 15) / 16);
+
+    fp16_matmul_kernel<<<grid, block, 0, stream>>>(input, weight, output, M, N, K);
 }
 
 // W8A16 reference kernel (simple but correct)
 __global__ void w8a16_matmul_reference_kernel(const half *__restrict__ input,
                                               const int8_t *__restrict__ weight,
                                               const half *__restrict__ scales,
-                                              half *__restrict__ output, int M,
-                                              int N, int K, int group_size) {
-  int row = blockIdx.y * blockDim.y + threadIdx.y;
-  int col = blockIdx.x * blockDim.x + threadIdx.x;
+                                              half *__restrict__ output, int M, int N, int K,
+                                              int group_size) {
+    int row = blockIdx.y * blockDim.y + threadIdx.y;
+    int col = blockIdx.x * blockDim.x + threadIdx.x;
 
-  if (row < M && col < N) {
-    float sum = 0.0f;
+    if (row < M && col < N) {
+        float sum = 0.0f;
 
-    for (int k = 0; k < K; ++k) {
-      // Load input
-      float a = __half2float(input[row * K + k]);
+        for (int k = 0; k < K; ++k) {
+            // Load input
+            float a = __half2float(input[row * K + k]);
 
-      // Load and dequantize weight
-      int8_t w_int = weight[k * N + col];
-      int group_idx = k / group_size;
-      float scale = __half2float(scales[group_idx * N + col]);
-      float w = static_cast<float>(w_int) * scale;
+            // Load and dequantize weight
+            int8_t w_int = weight[k * N + col];
+            int    group_idx = k / group_size;
+            float  scale = __half2float(scales[group_idx * N + col]);
+            float  w = static_cast<float>(w_int) * scale;
 
-      sum += a * w;
-    }
+            sum += a * w;
+        }
 
-    output[row * N + col] = __float2half(sum);
-  }
+        output[row * N + col] = __float2half(sum);
+    }
 }
 
-void w8a16_matmul_reference(const half *input, const int8_t *weight,
-                            const half *scales, half *output, int M, int N,
-                            int K, int group_size, cudaStream_t stream) {
-  if (M <= 0 || N <= 0 || K <= 0 || group_size <= 0) {
-    return;
-  }
-  
-  dim3 block(16, 16);
-  dim3 grid((N + 15) / 16, (M + 15) / 16);
-
-  w8a16_matmul_reference_kernel<<<grid, block, 0, stream>>>(
-      input, weight, scales, output, M, N, K, group_size);
+void w8a16_matmul_reference(const half *input, const int8_t *weight, const half *scales,
+                            half *output, int M, int N, int K, int group_size,
+                            cudaStream_t stream) {
+    if (M <= 0 || N <= 0 || K <= 0 || group_size <= 0) {
+        return;
+    }
+
+    dim3 block(16, 16);
+    dim3 grid((N + 15) / 16, (M + 15) / 16);
+
+    w8a16_matmul_reference_kernel<<<grid, block, 0, stream>>>(input, weight, scales, output, M, N,
+                                                              K, group_size);
 }
 
 // Optimized W8A16 kernel with shared memory tiling
@@ -123,121 +119,119 @@ constexpr int BLOCK_K = 32;
 __global__ void w8a16_matmul_tiled_kernel(const half *__restrict__ input,
                                           const int8_t *__restrict__ weight,
                                           const half *__restrict__ scales,
-                                          half *__restrict__ output, int M,
-                                          int N, int K, int group_size) {
-  // Shared memory for input tile and weight tile
-  __shared__ half smem_input[TILE_M][BLOCK_K + 1]; // +1 to avoid bank conflicts
-  __shared__ int8_t smem_weight[BLOCK_K][TILE_N + 4]; // +4 for alignment
-
-  int bx = blockIdx.x;
-  int by = blockIdx.y;
-  int tx = threadIdx.x;
-  int ty = threadIdx.y;
-
-  // Each thread computes multiple output elements
-  // Thread block is (TILE_N, TILE_M/4) = (64, 16)
-  // Each thread handles 4 rows
-  int global_col = bx * TILE_N + tx;
-
-  // Thread-local accumulators for 4 rows
-  float acc[4] = {0.0f, 0.0f, 0.0f, 0.0f};
-
-  // Number of tiles along K dimension
-  int num_k_tiles = (K + BLOCK_K - 1) / BLOCK_K;
-
-  for (int k_tile = 0; k_tile < num_k_tiles; ++k_tile) {
-    int k_start = k_tile * BLOCK_K;
-
-    // Cooperative load of input tile
-    // Each thread loads multiple elements
-    for (int i = ty; i < TILE_M; i += blockDim.y) {
-      for (int j = tx; j < BLOCK_K; j += blockDim.x) {
-        int global_row = by * TILE_M + i;
-        int global_k = k_start + j;
-
-        if (global_row < M && global_k < K) {
-          smem_input[i][j] = input[global_row * K + global_k];
-        } else {
-          smem_input[i][j] = __float2half(0.0f);
+                                          half *__restrict__ output, int M, int N, int K,
+                                          int group_size) {
+    // Shared memory for input tile and weight tile
+    __shared__ half   smem_input[TILE_M][BLOCK_K + 1];  // +1 to avoid bank conflicts
+    __shared__ int8_t smem_weight[BLOCK_K][TILE_N + 4]; // +4 for alignment
+
+    int bx = blockIdx.x;
+    int by = blockIdx.y;
+    int tx = threadIdx.x;
+    int ty = threadIdx.y;
+
+    // Each thread computes multiple output elements
+    // Thread block is (TILE_N, TILE_M/4) = (64, 16)
+    // Each thread handles 4 rows
+    int global_col = bx * TILE_N + tx;
+
+    // Thread-local accumulators for 4 rows
+    float acc[4] = {0.0f, 0.0f, 0.0f, 0.0f};
+
+    // Number of tiles along K dimension
+    int num_k_tiles = (K + BLOCK_K - 1) / BLOCK_K;
+
+    for (int k_tile = 0; k_tile < num_k_tiles; ++k_tile) {
+        int k_start = k_tile * BLOCK_K;
+
+        // Cooperative load of input tile
+        // Each thread loads multiple elements
+        for (int i = ty; i < TILE_M; i += blockDim.y) {
+            for (int j = tx; j < BLOCK_K; j += blockDim.x) {
+                int global_row = by * TILE_M + i;
+                int global_k = k_start + j;
+
+                if (global_row < M && global_k < K) {
+                    smem_input[i][j] = input[global_row * K + global_k];
+                } else {
+                    smem_input[i][j] = __float2half(0.0f);
+                }
+            }
         }
-      }
-    }
-
-    // Cooperative load of weight tile
-    for (int i = ty; i < BLOCK_K; i += blockDim.y) {
-      for (int j = tx; j < TILE_N; j += blockDim.x) {
-        int global_k = k_start + i;
-        int g_col = bx * TILE_N + j;
 
-        if (global_k < K && g_col < N) {
-          smem_weight[i][j] = weight[global_k * N + g_col];
-        } else {
-          smem_weight[i][j] = 0;
+        // Cooperative load of weight tile
+        for (int i = ty; i < BLOCK_K; i += blockDim.y) {
+            for (int j = tx; j < TILE_N; j += blockDim.x) {
+                int global_k = k_start + i;
+                int g_col = bx * TILE_N + j;
+
+                if (global_k < K && g_col < N) {
+                    smem_weight[i][j] = weight[global_k * N + g_col];
+                } else {
+                    smem_weight[i][j] = 0;
+                }
+            }
         }
-      }
-    }
 
-    __syncthreads();
+        __syncthreads();
 
-    // Compute partial products for 4 rows per thread
-    if (global_col < N) {
+        // Compute partial products for 4 rows per thread
+        if (global_col < N) {
 #pragma unroll
-      for (int k = 0; k < BLOCK_K; ++k) {
-        int global_k = k_start + k;
-        if (global_k < K) {
-          // Get the correct scale for this k position
-          int group_idx = global_k / group_size;
-          float scale = __half2float(scales[group_idx * N + global_col]);
-          float w = static_cast<float>(smem_weight[k][tx]) * scale;
+            for (int k = 0; k < BLOCK_K; ++k) {
+                int global_k = k_start + k;
+                if (global_k < K) {
+                    // Get the correct scale for this k position
+                    int   group_idx = global_k / group_size;
+                    float scale = __half2float(scales[group_idx * N + global_col]);
+                    float w = static_cast<float>(smem_weight[k][tx]) * scale;
 
 // Accumulate for 4 rows
 #pragma unroll
-          for (int r = 0; r < 4; ++r) {
+                    for (int r = 0; r < 4; ++r) {
+                        int local_row = ty * 4 + r;
+                        int global_row = by * TILE_M + local_row;
+                        if (global_row < M && local_row < TILE_M) {
+                            float a = __half2float(smem_input[local_row][k]);
+                            acc[r] += a * w;
+                        }
+                    }
+                }
+            }
+        }
+
+        __syncthreads();
+    }
+
+    // Write output for 4 rows
+    if (global_col < N) {
+#pragma unroll
+        for (int r = 0; r < 4; ++r) {
             int local_row = ty * 4 + r;
             int global_row = by * TILE_M + local_row;
-            if (global_row < M && local_row < TILE_M) {
-              float a = __half2float(smem_input[local_row][k]);
-              acc[r] += a * w;
+            if (global_row < M) {
+                output[global_row * N + global_col] = __float2half(acc[r]);
             }
-          }
         }
-      }
     }
+}
 
-    __syncthreads();
-  }
+void w8a16_matmul(const half *input, const int8_t *weight, const half *scales, half *output, int M,
+                  int N, int K, int group_size, cudaStream_t stream) {
+    if (M <= 0 || N <= 0 || K <= 0 || group_size <= 0) {
+        return;
+    }
 
-  // Write output for 4 rows
-  if (global_col < N) {
-#pragma unroll
-    for (int r = 0; r < 4; ++r) {
-      int local_row = ty * 4 + r;
-      int global_row = by * TILE_M + local_row;
-      if (global_row < M) {
-        output[global_row * N + global_col] = __float2half(acc[r]);
-      }
+    if (M * N < 4096) {
+        w8a16_matmul_reference(input, weight, scales, output, M, N, K, group_size, stream);
+        return;
     }
-  }
-}
 
-void w8a16_matmul(const half *input, const int8_t *weight, const half *scales,
-                  half *output, int M, int N, int K, int group_size,
-                  cudaStream_t stream) {
-  if (M <= 0 || N <= 0 || K <= 0 || group_size <= 0) {
-    return;
-  }
-  
-  if (M * N < 4096) {
-    w8a16_matmul_reference(input, weight, scales, output, M, N, K, group_size,
-                           stream);
-    return;
-  }
-
-  dim3 block(TILE_N, TILE_M / 4);
-  dim3 grid((N + TILE_N - 1) / TILE_N, (M + TILE_M - 1) / TILE_M);
-
-  w8a16_matmul_tiled_kernel<<<grid, block, 0, stream>>>(
-      input, weight, scales, output, M, N, K, group_size);
+    dim3 block(TILE_N, TILE_M / 4);
+    dim3 grid((N + TILE_N - 1) / TILE_N, (M + TILE_M - 1) / TILE_M);
+
+    w8a16_matmul_tiled_kernel<<<grid, block, 0, stream>>>(input, weight, scales, output, M, N, K,
+                                                          group_size);
 }
 
 } // namespace kernels
diff --git a/kernels/w8a16_matmul.cuh b/kernels/w8a16_matmul.cuh
index 0486c65..14fa80d 100644
--- a/kernels/w8a16_matmul.cuh
+++ b/kernels/w8a16_matmul.cuh
@@ -26,18 +26,17 @@ void w8a16_matmul(const half *__restrict__ input,    // [M, K] FP16
                   int M, int N, int K, int group_size, cudaStream_t stream = 0);
 
 // Reference implementation for testing (slower but correct)
-void w8a16_matmul_reference(const half *input, const int8_t *weight,
-                            const half *scales, half *output, int M, int N,
-                            int K, int group_size, cudaStream_t stream = 0);
+void w8a16_matmul_reference(const half *input, const int8_t *weight, const half *scales,
+                            half *output, int M, int N, int K, int group_size,
+                            cudaStream_t stream = 0);
 
 // FP16 baseline for accuracy comparison
-void fp16_matmul_reference(const half *input, const half *weight, half *output,
-                           int M, int N, int K, cudaStream_t stream = 0);
+void fp16_matmul_reference(const half *input, const half *weight, half *output, int M, int N, int K,
+                           cudaStream_t stream = 0);
 
 // Dequantize INT8 weights to FP16 (for testing)
-void dequantize_weights(const int8_t *weight_int8, const half *scales,
-                        half *weight_fp16, int K, int N, int group_size,
-                        cudaStream_t stream = 0);
+void dequantize_weights(const int8_t *weight_int8, const half *scales, half *weight_fp16, int K,
+                        int N, int group_size, cudaStream_t stream = 0);
 
 } // namespace kernels
 } // namespace tiny_llm
diff --git a/kernels/warp_utils.cuh b/kernels/warp_utils.cuh
index b268fe0..bc76211 100644
--- a/kernels/warp_utils.cuh
+++ b/kernels/warp_utils.cuh
@@ -13,114 +13,111 @@ constexpr unsigned int FULL_MASK = 0xffffffff;
 
 __device__ __forceinline__ float warp_reduce_sum(float val) {
 #pragma unroll
-  for (int offset = 16; offset > 0; offset /= 2) {
-    val += __shfl_down_sync(FULL_MASK, val, offset);
-  }
-  return val;
+    for (int offset = 16; offset > 0; offset /= 2) {
+        val += __shfl_down_sync(FULL_MASK, val, offset);
+    }
+    return val;
 }
 
 __device__ __forceinline__ float warp_reduce_max(float val) {
 #pragma unroll
-  for (int offset = 16; offset > 0; offset /= 2) {
-    val = fmaxf(val, __shfl_down_sync(FULL_MASK, val, offset));
-  }
-  return val;
+    for (int offset = 16; offset > 0; offset /= 2) {
+        val = fmaxf(val, __shfl_down_sync(FULL_MASK, val, offset));
+    }
+    return val;
 }
 
 __device__ __forceinline__ half warp_reduce_sum_half(half val) {
-  float fval = __half2float(val);
-  fval = warp_reduce_sum(fval);
-  return __float2half(fval);
+    float fval = __half2float(val);
+    fval = warp_reduce_sum(fval);
+    return __float2half(fval);
 }
 
 // Broadcast value from lane 0 to all lanes in warp
 __device__ __forceinline__ float warp_broadcast(float val, int src_lane = 0) {
-  return __shfl_sync(FULL_MASK, val, src_lane);
+    return __shfl_sync(FULL_MASK, val, src_lane);
 }
 
 // Warp-level dot product
 // Each thread holds one element, computes dot product across warp
 __device__ __forceinline__ float warp_dot_product(float a, float b) {
-  float product = a * b;
-  return warp_reduce_sum(product);
+    float product = a * b;
+    return warp_reduce_sum(product);
 }
 
 // Warp-level softmax (for attention)
 // Input: each thread holds one score
 // Output: each thread holds corresponding softmax probability
 __device__ __forceinline__ float warp_softmax(float score, int valid_lanes) {
-  // Find max for numerical stability
-  float max_score = score;
+    // Find max for numerical stability
+    float max_score = score;
 #pragma unroll
-  for (int offset = 16; offset > 0; offset /= 2) {
-    float other = __shfl_down_sync(FULL_MASK, max_score, offset);
-    if (threadIdx.x % 32 + offset < valid_lanes) {
-      max_score = fmaxf(max_score, other);
+    for (int offset = 16; offset > 0; offset /= 2) {
+        float other = __shfl_down_sync(FULL_MASK, max_score, offset);
+        if (threadIdx.x % 32 + offset < valid_lanes) {
+            max_score = fmaxf(max_score, other);
+        }
     }
-  }
-  max_score = __shfl_sync(FULL_MASK, max_score, 0);
+    max_score = __shfl_sync(FULL_MASK, max_score, 0);
 
-  // Compute exp(score - max)
-  float exp_score =
-      (threadIdx.x % 32 < valid_lanes) ? expf(score - max_score) : 0.0f;
+    // Compute exp(score - max)
+    float exp_score = (threadIdx.x % 32 < valid_lanes) ? expf(score - max_score) : 0.0f;
 
-  // Sum of exponentials
-  float sum_exp = warp_reduce_sum(exp_score);
-  sum_exp = __shfl_sync(FULL_MASK, sum_exp, 0);
+    // Sum of exponentials
+    float sum_exp = warp_reduce_sum(exp_score);
+    sum_exp = __shfl_sync(FULL_MASK, sum_exp, 0);
 
-  // Normalize
-  return exp_score / (sum_exp + 1e-6f);
+    // Normalize
+    return exp_score / (sum_exp + 1e-6f);
 }
 
 // Block-level reduction using shared memory and warp shuffles
 template <int BLOCK_SIZE>
-__device__ __forceinline__ float block_reduce_sum(float val,
-                                                  float *shared_mem) {
-  int lane = threadIdx.x % 32;
-  int warp_id = threadIdx.x / 32;
-
-  // Warp-level reduction
-  val = warp_reduce_sum(val);
-
-  // Write warp results to shared memory
-  if (lane == 0) {
-    shared_mem[warp_id] = val;
-  }
-  __syncthreads();
-
-  // Final reduction in first warp
-  constexpr int NUM_WARPS = BLOCK_SIZE / 32;
-  if (warp_id == 0) {
-    val = (lane < NUM_WARPS) ? shared_mem[lane] : 0.0f;
+__device__ __forceinline__ float block_reduce_sum(float val, float *shared_mem) {
+    int lane = threadIdx.x % 32;
+    int warp_id = threadIdx.x / 32;
+
+    // Warp-level reduction
     val = warp_reduce_sum(val);
-  }
 
-  return val;
+    // Write warp results to shared memory
+    if (lane == 0) {
+        shared_mem[warp_id] = val;
+    }
+    __syncthreads();
+
+    // Final reduction in first warp
+    constexpr int NUM_WARPS = BLOCK_SIZE / 32;
+    if (warp_id == 0) {
+        val = (lane < NUM_WARPS) ? shared_mem[lane] : 0.0f;
+        val = warp_reduce_sum(val);
+    }
+
+    return val;
 }
 
 template <int BLOCK_SIZE>
-__device__ __forceinline__ float block_reduce_max(float val,
-                                                  float *shared_mem) {
-  int lane = threadIdx.x % 32;
-  int warp_id = threadIdx.x / 32;
-
-  // Warp-level reduction
-  val = warp_reduce_max(val);
-
-  // Write warp results to shared memory
-  if (lane == 0) {
-    shared_mem[warp_id] = val;
-  }
-  __syncthreads();
-
-  // Final reduction in first warp
-  constexpr int NUM_WARPS = BLOCK_SIZE / 32;
-  if (warp_id == 0) {
-    val = (lane < NUM_WARPS) ? shared_mem[lane] : -INFINITY;
+__device__ __forceinline__ float block_reduce_max(float val, float *shared_mem) {
+    int lane = threadIdx.x % 32;
+    int warp_id = threadIdx.x / 32;
+
+    // Warp-level reduction
     val = warp_reduce_max(val);
-  }
 
-  return val;
+    // Write warp results to shared memory
+    if (lane == 0) {
+        shared_mem[warp_id] = val;
+    }
+    __syncthreads();
+
+    // Final reduction in first warp
+    constexpr int NUM_WARPS = BLOCK_SIZE / 32;
+    if (warp_id == 0) {
+        val = (lane < NUM_WARPS) ? shared_mem[lane] : -INFINITY;
+        val = warp_reduce_max(val);
+    }
+
+    return val;
 }
 
 } // namespace kernels
diff --git a/src/gguf_parser.cpp b/src/gguf_parser.cpp
index 548c78e..bbf489c 100644
--- a/src/gguf_parser.cpp
+++ b/src/gguf_parser.cpp
@@ -9,558 +9,526 @@ namespace tiny_llm {
 GGUFParser::GGUFParser(const std::string &path) : path_(path) {}
 
 Result<void> GGUFParser::parse() {
-  TLLM_INFO("Parsing GGUF file: {}", path_);
+    TLLM_INFO("Parsing GGUF file: {}", path_);
 
-  std::ifstream file(path_, std::ios::binary);
-  if (!file) {
-    return Result<void>::err("Failed to open file: " + path_);
-  }
+    std::ifstream file(path_, std::ios::binary);
+    if (!file) {
+        return Result<void>::err("Failed to open file: " + path_);
+    }
 
-  // Parse header
-  auto header_result = parseHeader(file);
-  if (header_result.isErr()) {
-    return header_result;
-  }
+    // Parse header
+    auto header_result = parseHeader(file);
+    if (header_result.isErr()) {
+        return header_result;
+    }
 
-  TLLM_INFO("GGUF header: version={}, tensors={}, metadata_entries={}",
-            header_.version, header_.tensor_count, header_.metadata_kv_count);
+    TLLM_INFO("GGUF header: version={}, tensors={}, metadata_entries={}", header_.version,
+              header_.tensor_count, header_.metadata_kv_count);
 
-  // Parse metadata
-  auto meta_result = parseMetadata(file);
-  if (meta_result.isErr()) {
-    return meta_result;
-  }
+    // Parse metadata
+    auto meta_result = parseMetadata(file);
+    if (meta_result.isErr()) {
+        return meta_result;
+    }
 
-  TLLM_DEBUG("Parsed {} metadata entries", metadata_.kv.size());
+    TLLM_DEBUG("Parsed {} metadata entries", metadata_.kv.size());
 
-  // Parse tensor info
-  auto tensor_result = parseTensorInfo(file);
-  if (tensor_result.isErr()) {
-    return tensor_result;
-  }
+    // Parse tensor info
+    auto tensor_result = parseTensorInfo(file);
+    if (tensor_result.isErr()) {
+        return tensor_result;
+    }
 
-  TLLM_DEBUG("Parsed {} tensor entries", tensors_.size());
+    TLLM_DEBUG("Parsed {} tensor entries", tensors_.size());
 
-  // Calculate data offset with alignment
-  data_offset_ = alignOffset(static_cast<uint64_t>(file.tellg()));
+    // Calculate data offset with alignment
+    data_offset_ = alignOffset(static_cast<uint64_t>(file.tellg()));
 
-  TLLM_INFO("GGUF parsing complete. Data offset: {}", data_offset_);
+    TLLM_INFO("GGUF parsing complete. Data offset: {}", data_offset_);
 
-  return Result<void>::ok();
+    return Result<void>::ok();
 }
 
 Result<void> GGUFParser::parseHeader(std::ifstream &file) {
-  file.read(reinterpret_cast<char *>(&header_.magic), 4);
-  file.read(reinterpret_cast<char *>(&header_.version), 4);
-  file.read(reinterpret_cast<char *>(&header_.tensor_count), 8);
-  file.read(reinterpret_cast<char *>(&header_.metadata_kv_count), 8);
-
-  if (!file) {
-    return Result<void>::err("Failed to read GGUF header");
-  }
-
-  if (header_.magic != GGUF_MAGIC) {
-    return Result<void>::err(
-        "Invalid GGUF magic number. Expected 0x" +
-        std::to_string(GGUF_MAGIC) + ", got 0x" + std::to_string(header_.magic));
-  }
-
-  // Support GGUF version 2 and 3
-  if (header_.version < 2 || header_.version > 3) {
-    TLLM_WARN("GGUF version {} may not be fully supported", header_.version);
-  }
-
-  return Result<void>::ok();
-}
+    file.read(reinterpret_cast<char *>(&header_.magic), 4);
+    file.read(reinterpret_cast<char *>(&header_.version), 4);
+    file.read(reinterpret_cast<char *>(&header_.tensor_count), 8);
+    file.read(reinterpret_cast<char *>(&header_.metadata_kv_count), 8);
 
-Result<void> GGUFParser::parseMetadata(std::ifstream &file) {
-  for (uint64_t i = 0; i < header_.metadata_kv_count; ++i) {
-    // Read key
-    auto key_result = readString(file);
-    if (key_result.isErr()) {
-      return Result<void>::err("Failed to read metadata key: " +
-                               key_result.error());
+    if (!file) {
+        return Result<void>::err("Failed to read GGUF header");
     }
-    std::string key = key_result.value();
 
-    // Read value type
-    uint32_t type_val;
-    file.read(reinterpret_cast<char *>(&type_val), 4);
-    if (!file) {
-      return Result<void>::err("Failed to read metadata type for key: " + key);
+    if (header_.magic != GGUF_MAGIC) {
+        return Result<void>::err("Invalid GGUF magic number. Expected 0x" +
+                                 std::to_string(GGUF_MAGIC) + ", got 0x" +
+                                 std::to_string(header_.magic));
     }
 
-    // Read value
-    auto value_result = readValue(file, static_cast<GGUFType>(type_val));
-    if (value_result.isErr()) {
-      return Result<void>::err("Failed to read metadata value for key: " +
-                               key + ": " + value_result.error());
+    // Support GGUF version 2 and 3
+    if (header_.version < 2 || header_.version > 3) {
+        TLLM_WARN("GGUF version {} may not be fully supported", header_.version);
     }
 
-    metadata_.kv[key] = value_result.value();
-    TLLM_TRACE("Metadata: {} = <value>", key);
-  }
+    return Result<void>::ok();
+}
+
+Result<void> GGUFParser::parseMetadata(std::ifstream &file) {
+    for (uint64_t i = 0; i < header_.metadata_kv_count; ++i) {
+        // Read key
+        auto key_result = readString(file);
+        if (key_result.isErr()) {
+            return Result<void>::err("Failed to read metadata key: " + key_result.error());
+        }
+        std::string key = key_result.value();
+
+        // Read value type
+        uint32_t type_val;
+        file.read(reinterpret_cast<char *>(&type_val), 4);
+        if (!file) {
+            return Result<void>::err("Failed to read metadata type for key: " + key);
+        }
+
+        // Read value
+        auto value_result = readValue(file, static_cast<GGUFType>(type_val));
+        if (value_result.isErr()) {
+            return Result<void>::err("Failed to read metadata value for key: " + key + ": " +
+                                     value_result.error());
+        }
+
+        metadata_.kv[key] = value_result.value();
+        TLLM_TRACE("Metadata: {} = <value>", key);
+    }
 
-  return Result<void>::ok();
+    return Result<void>::ok();
 }
 
 Result<void> GGUFParser::parseTensorInfo(std::ifstream &file) {
-  tensors_.reserve(header_.tensor_count);
+    tensors_.reserve(header_.tensor_count);
 
-  for (uint64_t i = 0; i < header_.tensor_count; ++i) {
-    auto tensor_result = readTensorInfoEntry(file);
-    if (tensor_result.isErr()) {
-      return Result<void>::err("Failed to read tensor info " +
-                               std::to_string(i) + ": " + tensor_result.error());
-    }
+    for (uint64_t i = 0; i < header_.tensor_count; ++i) {
+        auto tensor_result = readTensorInfoEntry(file);
+        if (tensor_result.isErr()) {
+            return Result<void>::err("Failed to read tensor info " + std::to_string(i) + ": " +
+                                     tensor_result.error());
+        }
 
-    tensors_.push_back(tensor_result.value());
-    tensor_name_map_[tensors_.back().name] = tensors_.size() - 1;
+        tensors_.push_back(tensor_result.value());
+        tensor_name_map_[tensors_.back().name] = tensors_.size() - 1;
 
-    TLLM_TRACE("Tensor: {} dims={} type={} offset={}",
-               tensors_.back().name, tensors_.back().dimensions.size(),
-               static_cast<uint32_t>(tensors_.back().type),
-               tensors_.back().offset);
-  }
+        TLLM_TRACE("Tensor: {} dims={} type={} offset={}", tensors_.back().name,
+                   tensors_.back().dimensions.size(), static_cast<uint32_t>(tensors_.back().type),
+                   tensors_.back().offset);
+    }
 
-  return Result<void>::ok();
+    return Result<void>::ok();
 }
 
 Result<GGUFTensorInfo> GGUFParser::readTensorInfoEntry(std::ifstream &file) {
-  GGUFTensorInfo info;
-
-  // Read name
-  auto name_result = readString(file);
-  if (name_result.isErr()) {
-    return Result<GGUFTensorInfo>::err(name_result.error());
-  }
-  info.name = name_result.value();
-
-  // Read number of dimensions
-  uint32_t n_dims;
-  file.read(reinterpret_cast<char *>(&n_dims), 4);
-  if (!file) {
-    return Result<GGUFTensorInfo>::err("Failed to read tensor n_dims");
-  }
-
-  // Read dimensions
-  info.dimensions.resize(n_dims);
-  for (uint32_t d = 0; d < n_dims; ++d) {
-    file.read(reinterpret_cast<char *>(&info.dimensions[d]), 8);
+    GGUFTensorInfo info;
+
+    // Read name
+    auto name_result = readString(file);
+    if (name_result.isErr()) {
+        return Result<GGUFTensorInfo>::err(name_result.error());
+    }
+    info.name = name_result.value();
+
+    // Read number of dimensions
+    uint32_t n_dims;
+    file.read(reinterpret_cast<char *>(&n_dims), 4);
     if (!file) {
-      return Result<GGUFTensorInfo>::err("Failed to read tensor dimension " +
-                                          std::to_string(d));
-    }
-  }
-
-  // Read type
-  uint32_t type_val;
-  file.read(reinterpret_cast<char *>(&type_val), 4);
-  if (!file) {
-    return Result<GGUFTensorInfo>::err("Failed to read tensor type");
-  }
-  info.type = static_cast<GGMLType>(type_val);
-
-  // Read offset
-  file.read(reinterpret_cast<char *>(&info.offset), 8);
-  if (!file) {
-    return Result<GGUFTensorInfo>::err("Failed to read tensor offset");
-  }
-
-  return Result<GGUFTensorInfo>::ok(info);
+        return Result<GGUFTensorInfo>::err("Failed to read tensor n_dims");
+    }
+
+    // Read dimensions
+    info.dimensions.resize(n_dims);
+    for (uint32_t d = 0; d < n_dims; ++d) {
+        file.read(reinterpret_cast<char *>(&info.dimensions[d]), 8);
+        if (!file) {
+            return Result<GGUFTensorInfo>::err("Failed to read tensor dimension " +
+                                               std::to_string(d));
+        }
+    }
+
+    // Read type
+    uint32_t type_val;
+    file.read(reinterpret_cast<char *>(&type_val), 4);
+    if (!file) {
+        return Result<GGUFTensorInfo>::err("Failed to read tensor type");
+    }
+    info.type = static_cast<GGMLType>(type_val);
+
+    // Read offset
+    file.read(reinterpret_cast<char *>(&info.offset), 8);
+    if (!file) {
+        return Result<GGUFTensorInfo>::err("Failed to read tensor offset");
+    }
+
+    return Result<GGUFTensorInfo>::ok(info);
 }
 
 Result<GGUFValue> GGUFParser::readValue(std::ifstream &file, GGUFType type) {
-  switch (type) {
-  case GGUFType::UINT8: {
-    uint8_t v;
-    file.read(reinterpret_cast<char *>(&v), 1);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read uint8_t");
-    return Result<GGUFValue>::ok(GGUFValue{v});
-  }
-  case GGUFType::INT8: {
-    int8_t v;
-    file.read(reinterpret_cast<char *>(&v), 1);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read int8_t");
-    return Result<GGUFValue>::ok(GGUFValue{v});
-  }
-  case GGUFType::UINT16: {
-    uint16_t v;
-    file.read(reinterpret_cast<char *>(&v), 2);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read uint16_t");
-    return Result<GGUFValue>::ok(GGUFValue{v});
-  }
-  case GGUFType::INT16: {
-    int16_t v;
-    file.read(reinterpret_cast<char *>(&v), 2);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read int16_t");
-    return Result<GGUFValue>::ok(GGUFValue{v});
-  }
-  case GGUFType::UINT32: {
-    uint32_t v;
-    file.read(reinterpret_cast<char *>(&v), 4);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read uint32_t");
-    return Result<GGUFValue>::ok(GGUFValue{v});
-  }
-  case GGUFType::INT32: {
-    int32_t v;
-    file.read(reinterpret_cast<char *>(&v), 4);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read int32_t");
-    return Result<GGUFValue>::ok(GGUFValue{v});
-  }
-  case GGUFType::UINT64: {
-    uint64_t v;
-    file.read(reinterpret_cast<char *>(&v), 8);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read uint64_t");
-    return Result<GGUFValue>::ok(GGUFValue{v});
-  }
-  case GGUFType::INT64: {
-    int64_t v;
-    file.read(reinterpret_cast<char *>(&v), 8);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read int64_t");
-    return Result<GGUFValue>::ok(GGUFValue{v});
-  }
-  case GGUFType::FLOAT32: {
-    float v;
-    file.read(reinterpret_cast<char *>(&v), 4);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read float");
-    return Result<GGUFValue>::ok(GGUFValue{v});
-  }
-  case GGUFType::FLOAT64: {
-    double v;
-    file.read(reinterpret_cast<char *>(&v), 8);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read double");
-    return Result<GGUFValue>::ok(GGUFValue{v});
-  }
-  case GGUFType::BOOL: {
-    uint8_t v;
-    file.read(reinterpret_cast<char *>(&v), 1);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read bool");
-    return Result<GGUFValue>::ok(GGUFValue{static_cast<bool>(v)});
-  }
-  case GGUFType::STRING: {
-    auto str_result = readString(file);
-    if (str_result.isErr()) {
-      return Result<GGUFValue>::err(str_result.error());
-    }
-    return Result<GGUFValue>::ok(GGUFValue{str_result.value()});
-  }
-  case GGUFType::ARRAY: {
-    auto arr_result = readArray(file);
-    if (arr_result.isErr()) {
-      return Result<GGUFValue>::err(arr_result.error());
-    }
-    return Result<GGUFValue>::ok(GGUFValue{arr_result.value()});
-  }
-  default:
-    return Result<GGUFValue>::err("Unsupported GGUF type: " +
-                                   std::to_string(static_cast<uint32_t>(type)));
-  }
+    switch (type) {
+    case GGUFType::UINT8: {
+        uint8_t v;
+        file.read(reinterpret_cast<char *>(&v), 1);
+        if (!file) return Result<GGUFValue>::err("Failed to read uint8_t");
+        return Result<GGUFValue>::ok(GGUFValue{v});
+    }
+    case GGUFType::INT8: {
+        int8_t v;
+        file.read(reinterpret_cast<char *>(&v), 1);
+        if (!file) return Result<GGUFValue>::err("Failed to read int8_t");
+        return Result<GGUFValue>::ok(GGUFValue{v});
+    }
+    case GGUFType::UINT16: {
+        uint16_t v;
+        file.read(reinterpret_cast<char *>(&v), 2);
+        if (!file) return Result<GGUFValue>::err("Failed to read uint16_t");
+        return Result<GGUFValue>::ok(GGUFValue{v});
+    }
+    case GGUFType::INT16: {
+        int16_t v;
+        file.read(reinterpret_cast<char *>(&v), 2);
+        if (!file) return Result<GGUFValue>::err("Failed to read int16_t");
+        return Result<GGUFValue>::ok(GGUFValue{v});
+    }
+    case GGUFType::UINT32: {
+        uint32_t v;
+        file.read(reinterpret_cast<char *>(&v), 4);
+        if (!file) return Result<GGUFValue>::err("Failed to read uint32_t");
+        return Result<GGUFValue>::ok(GGUFValue{v});
+    }
+    case GGUFType::INT32: {
+        int32_t v;
+        file.read(reinterpret_cast<char *>(&v), 4);
+        if (!file) return Result<GGUFValue>::err("Failed to read int32_t");
+        return Result<GGUFValue>::ok(GGUFValue{v});
+    }
+    case GGUFType::UINT64: {
+        uint64_t v;
+        file.read(reinterpret_cast<char *>(&v), 8);
+        if (!file) return Result<GGUFValue>::err("Failed to read uint64_t");
+        return Result<GGUFValue>::ok(GGUFValue{v});
+    }
+    case GGUFType::INT64: {
+        int64_t v;
+        file.read(reinterpret_cast<char *>(&v), 8);
+        if (!file) return Result<GGUFValue>::err("Failed to read int64_t");
+        return Result<GGUFValue>::ok(GGUFValue{v});
+    }
+    case GGUFType::FLOAT32: {
+        float v;
+        file.read(reinterpret_cast<char *>(&v), 4);
+        if (!file) return Result<GGUFValue>::err("Failed to read float");
+        return Result<GGUFValue>::ok(GGUFValue{v});
+    }
+    case GGUFType::FLOAT64: {
+        double v;
+        file.read(reinterpret_cast<char *>(&v), 8);
+        if (!file) return Result<GGUFValue>::err("Failed to read double");
+        return Result<GGUFValue>::ok(GGUFValue{v});
+    }
+    case GGUFType::BOOL: {
+        uint8_t v;
+        file.read(reinterpret_cast<char *>(&v), 1);
+        if (!file) return Result<GGUFValue>::err("Failed to read bool");
+        return Result<GGUFValue>::ok(GGUFValue{static_cast<bool>(v)});
+    }
+    case GGUFType::STRING: {
+        auto str_result = readString(file);
+        if (str_result.isErr()) {
+            return Result<GGUFValue>::err(str_result.error());
+        }
+        return Result<GGUFValue>::ok(GGUFValue{str_result.value()});
+    }
+    case GGUFType::ARRAY: {
+        auto arr_result = readArray(file);
+        if (arr_result.isErr()) {
+            return Result<GGUFValue>::err(arr_result.error());
+        }
+        return Result<GGUFValue>::ok(GGUFValue{arr_result.value()});
+    }
+    default:
+        return Result<GGUFValue>::err("Unsupported GGUF type: " +
+                                      std::to_string(static_cast<uint32_t>(type)));
+    }
 }
 
 Result<GGUFValue> GGUFParser::readArray(std::ifstream &file) {
-  // Read element type
-  uint32_t type_val;
-  file.read(reinterpret_cast<char *>(&type_val), 4);
-  if (!file) {
-    return Result<GGUFValue>::err("Failed to read array element type");
-  }
-  GGUFType elem_type = static_cast<GGUFType>(type_val);
-
-  // Read count
-  uint64_t count;
-  file.read(reinterpret_cast<char *>(&count), 8);
-  if (!file) {
-    return Result<GGUFValue>::err("Failed to read array count");
-  }
-
-  TLLM_TRACE("Reading array of {} elements, type {}", count,
-             static_cast<uint32_t>(elem_type));
-
-  // Handle different array types
-  switch (elem_type) {
-  case GGUFType::UINT32: {
-    std::vector<uint32_t> arr(count);
-    file.read(reinterpret_cast<char *>(arr.data()), count * 4);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read uint32 array");
-    return Result<GGUFValue>::ok(GGUFValue{arr});
-  }
-  case GGUFType::INT32: {
-    std::vector<int32_t> arr(count);
-    file.read(reinterpret_cast<char *>(arr.data()), count * 4);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read int32 array");
-    return Result<GGUFValue>::ok(GGUFValue{arr});
-  }
-  case GGUFType::FLOAT32: {
-    std::vector<float> arr(count);
-    file.read(reinterpret_cast<char *>(arr.data()), count * 4);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read float array");
-    return Result<GGUFValue>::ok(GGUFValue{arr});
-  }
-  case GGUFType::FLOAT64: {
-    std::vector<double> arr(count);
-    file.read(reinterpret_cast<char *>(arr.data()), count * 8);
-    if (!file)
-      return Result<GGUFValue>::err("Failed to read double array");
-    return Result<GGUFValue>::ok(GGUFValue{arr});
-  }
-  case GGUFType::STRING: {
-    std::vector<std::string> arr;
-    arr.reserve(count);
-    for (uint64_t i = 0; i < count; ++i) {
-      auto r = readString(file);
-      if (r.isErr()) {
-        return Result<GGUFValue>::err(r.error());
-      }
-      arr.push_back(r.value());
-    }
-    return Result<GGUFValue>::ok(GGUFValue{arr});
-  }
-  default:
-    // Skip unsupported array types
-    TLLM_WARN("Unsupported array element type: {}, skipping {} elements",
-              static_cast<uint32_t>(elem_type), count);
-    // Skip the data
-    for (uint64_t i = 0; i < count; ++i) {
-      auto r = readValue(file, elem_type);
-      if (r.isErr()) {
-        return Result<GGUFValue>::err(r.error());
-      }
-    }
-    return Result<GGUFValue>::ok(GGUFValue{std::vector<uint8_t>()});
-  }
+    // Read element type
+    uint32_t type_val;
+    file.read(reinterpret_cast<char *>(&type_val), 4);
+    if (!file) {
+        return Result<GGUFValue>::err("Failed to read array element type");
+    }
+    GGUFType elem_type = static_cast<GGUFType>(type_val);
+
+    // Read count
+    uint64_t count;
+    file.read(reinterpret_cast<char *>(&count), 8);
+    if (!file) {
+        return Result<GGUFValue>::err("Failed to read array count");
+    }
+
+    TLLM_TRACE("Reading array of {} elements, type {}", count, static_cast<uint32_t>(elem_type));
+
+    // Handle different array types
+    switch (elem_type) {
+    case GGUFType::UINT32: {
+        std::vector<uint32_t> arr(count);
+        file.read(reinterpret_cast<char *>(arr.data()), count * 4);
+        if (!file) return Result<GGUFValue>::err("Failed to read uint32 array");
+        return Result<GGUFValue>::ok(GGUFValue{arr});
+    }
+    case GGUFType::INT32: {
+        std::vector<int32_t> arr(count);
+        file.read(reinterpret_cast<char *>(arr.data()), count * 4);
+        if (!file) return Result<GGUFValue>::err("Failed to read int32 array");
+        return Result<GGUFValue>::ok(GGUFValue{arr});
+    }
+    case GGUFType::FLOAT32: {
+        std::vector<float> arr(count);
+        file.read(reinterpret_cast<char *>(arr.data()), count * 4);
+        if (!file) return Result<GGUFValue>::err("Failed to read float array");
+        return Result<GGUFValue>::ok(GGUFValue{arr});
+    }
+    case GGUFType::FLOAT64: {
+        std::vector<double> arr(count);
+        file.read(reinterpret_cast<char *>(arr.data()), count * 8);
+        if (!file) return Result<GGUFValue>::err("Failed to read double array");
+        return Result<GGUFValue>::ok(GGUFValue{arr});
+    }
+    case GGUFType::STRING: {
+        std::vector<std::string> arr;
+        arr.reserve(count);
+        for (uint64_t i = 0; i < count; ++i) {
+            auto r = readString(file);
+            if (r.isErr()) {
+                return Result<GGUFValue>::err(r.error());
+            }
+            arr.push_back(r.value());
+        }
+        return Result<GGUFValue>::ok(GGUFValue{arr});
+    }
+    default:
+        // Skip unsupported array types
+        TLLM_WARN("Unsupported array element type: {}, skipping {} elements",
+                  static_cast<uint32_t>(elem_type), count);
+        // Skip the data
+        for (uint64_t i = 0; i < count; ++i) {
+            auto r = readValue(file, elem_type);
+            if (r.isErr()) {
+                return Result<GGUFValue>::err(r.error());
+            }
+        }
+        return Result<GGUFValue>::ok(GGUFValue{std::vector<uint8_t>()});
+    }
 }
 
 Result<std::string> GGUFParser::readString(std::ifstream &file) {
-  uint64_t length;
-  file.read(reinterpret_cast<char *>(&length), 8);
+    uint64_t length;
+    file.read(reinterpret_cast<char *>(&length), 8);
 
-  if (!file) {
-    return Result<std::string>::err("Failed to read string length");
-  }
+    if (!file) {
+        return Result<std::string>::err("Failed to read string length");
+    }
 
-  // Sanity check
-  if (length > 1024 * 1024) {
-    return Result<std::string>::err("String too long: " +
-                                     std::to_string(length));
-  }
+    // Sanity check
+    if (length > 1024 * 1024) {
+        return Result<std::string>::err("String too long: " + std::to_string(length));
+    }
 
-  std::string str(length, '\0');
-  file.read(&str[0], length);
+    std::string str(length, '\0');
+    file.read(&str[0], length);
 
-  if (!file) {
-    return Result<std::string>::err("Failed to read string data");
-  }
+    if (!file) {
+        return Result<std::string>::err("Failed to read string data");
+    }
 
-  return Result<std::string>::ok(str);
+    return Result<std::string>::ok(str);
 }
 
 uint64_t GGUFParser::alignOffset(uint64_t offset) const {
-  return (offset + ALIGNMENT - 1) & ~(ALIGNMENT - 1);
+    return (offset + ALIGNMENT - 1) & ~(ALIGNMENT - 1);
 }
 
 Result<ModelConfig> GGUFParser::extractModelConfig() const {
-  ModelConfig config;
-
-  // Helper lambdas for getting metadata values
-  auto get_int = [this](const std::string &key, int &out) {
-    auto it = metadata_.kv.find(key);
-    if (it != metadata_.kv.end()) {
-      if (auto *val = std::get_if<int32_t>(&it->second)) {
-        out = *val;
-        return true;
-      }
-      if (auto *val = std::get_if<uint32_t>(&it->second)) {
-        out = static_cast<int>(*val);
-        return true;
-      }
-      if (auto *val = std::get_if<int64_t>(&it->second)) {
-        out = static_cast<int>(*val);
-        return true;
-      }
-      if (auto *val = std::get_if<uint64_t>(&it->second)) {
-        out = static_cast<int>(*val);
-        return true;
-      }
-    }
-    return false;
-  };
-
-  auto get_float = [this](const std::string &key, float &out) {
-    auto it = metadata_.kv.find(key);
-    if (it != metadata_.kv.end()) {
-      if (auto *val = std::get_if<float>(&it->second)) {
-        out = *val;
-        return true;
-      }
-      if (auto *val = std::get_if<double>(&it->second)) {
-        out = static_cast<float>(*val);
-        return true;
-      }
-    }
-    return false;
-  };
-
-  // Extract LLaMA-style metadata
-  // Standard GGUF metadata keys
-  get_int("llama.embedding_length", config.hidden_dim);
-  get_int("llama.block_count", config.num_layers);
-  get_int("llama.attention.head_count", config.num_heads);
-  get_int("llama.attention.head_count_kv", config.num_kv_heads);
-  get_int("llama.context_length", config.max_seq_len);
-  get_int("general.architecture", config.hidden_dim); // fallback
-
-  // Try alternative keys (some models use different naming)
-  get_int("llama.embedding_length", config.hidden_dim);
-  if (config.hidden_dim == 4096) { // default
+    ModelConfig config;
+
+    // Helper lambdas for getting metadata values
+    auto get_int = [this](const std::string &key, int &out) {
+        auto it = metadata_.kv.find(key);
+        if (it != metadata_.kv.end()) {
+            if (auto *val = std::get_if<int32_t>(&it->second)) {
+                out = *val;
+                return true;
+            }
+            if (auto *val = std::get_if<uint32_t>(&it->second)) {
+                out = static_cast<int>(*val);
+                return true;
+            }
+            if (auto *val = std::get_if<int64_t>(&it->second)) {
+                out = static_cast<int>(*val);
+                return true;
+            }
+            if (auto *val = std::get_if<uint64_t>(&it->second)) {
+                out = static_cast<int>(*val);
+                return true;
+            }
+        }
+        return false;
+    };
+
+    auto get_float = [this](const std::string &key, float &out) {
+        auto it = metadata_.kv.find(key);
+        if (it != metadata_.kv.end()) {
+            if (auto *val = std::get_if<float>(&it->second)) {
+                out = *val;
+                return true;
+            }
+            if (auto *val = std::get_if<double>(&it->second)) {
+                out = static_cast<float>(*val);
+                return true;
+            }
+        }
+        return false;
+    };
+
+    // Extract LLaMA-style metadata
+    // Standard GGUF metadata keys
     get_int("llama.embedding_length", config.hidden_dim);
-  }
-
-  // Tokenizer metadata
-  get_int("tokenizer.ggml.model.vocab_size", config.vocab_size);
-  get_int("tokenizer.ggml.eos_token_id", config.eos_token_id);
-  get_int("tokenizer.ggml.bos_token_id", config.bos_token_id);
-
-  // RoPE and normalization
-  get_float("llama.attention.layer_norm_rms_epsilon", config.rms_norm_eps);
-  get_float("llama.rope.freq_base", config.rope_theta);
-
-  // FFN dimension
-  get_int("llama.feed_forward_length", config.intermediate_dim);
-
-  // Calculate derived values
-  if (config.num_heads > 0) {
-    config.head_dim = config.hidden_dim / config.num_heads;
-  }
-
-  // Validate essential fields
-  if (config.hidden_dim <= 0 || config.num_layers <= 0 ||
-      config.num_heads <= 0 || config.vocab_size <= 0) {
-    TLLM_WARN("GGUF metadata may be incomplete. Using defaults for missing fields.");
-    // Set reasonable defaults if missing
-    if (config.hidden_dim <= 0)
-      config.hidden_dim = 4096;
-    if (config.num_layers <= 0)
-      config.num_layers = 32;
-    if (config.num_heads <= 0)
-      config.num_heads = 32;
-    if (config.num_kv_heads <= 0)
-      config.num_kv_heads = config.num_heads;
-    if (config.vocab_size <= 0)
-      config.vocab_size = 32000;
-    if (config.head_dim <= 0)
-      config.head_dim = config.hidden_dim / config.num_heads;
-    if (config.intermediate_dim <= 0)
-      config.intermediate_dim = config.hidden_dim * 8 / 3;
-  }
-
-  TLLM_INFO("Extracted model config: hidden_dim={}, num_layers={}, num_heads={}, "
-            "num_kv_heads={}, vocab_size={}",
-            config.hidden_dim, config.num_layers, config.num_heads,
-            config.num_kv_heads, config.vocab_size);
-
-  return Result<ModelConfig>::ok(config);
+    get_int("llama.block_count", config.num_layers);
+    get_int("llama.attention.head_count", config.num_heads);
+    get_int("llama.attention.head_count_kv", config.num_kv_heads);
+    get_int("llama.context_length", config.max_seq_len);
+    get_int("general.architecture", config.hidden_dim); // fallback
+
+    // Try alternative keys (some models use different naming)
+    get_int("llama.embedding_length", config.hidden_dim);
+    if (config.hidden_dim == 4096) { // default
+        get_int("llama.embedding_length", config.hidden_dim);
+    }
+
+    // Tokenizer metadata
+    get_int("tokenizer.ggml.model.vocab_size", config.vocab_size);
+    get_int("tokenizer.ggml.eos_token_id", config.eos_token_id);
+    get_int("tokenizer.ggml.bos_token_id", config.bos_token_id);
+
+    // RoPE and normalization
+    get_float("llama.attention.layer_norm_rms_epsilon", config.rms_norm_eps);
+    get_float("llama.rope.freq_base", config.rope_theta);
+
+    // FFN dimension
+    get_int("llama.feed_forward_length", config.intermediate_dim);
+
+    // Calculate derived values
+    if (config.num_heads > 0) {
+        config.head_dim = config.hidden_dim / config.num_heads;
+    }
+
+    // Validate essential fields
+    if (config.hidden_dim <= 0 || config.num_layers <= 0 || config.num_heads <= 0 ||
+        config.vocab_size <= 0) {
+        TLLM_WARN("GGUF metadata may be incomplete. Using defaults for missing fields.");
+        // Set reasonable defaults if missing
+        if (config.hidden_dim <= 0) config.hidden_dim = 4096;
+        if (config.num_layers <= 0) config.num_layers = 32;
+        if (config.num_heads <= 0) config.num_heads = 32;
+        if (config.num_kv_heads <= 0) config.num_kv_heads = config.num_heads;
+        if (config.vocab_size <= 0) config.vocab_size = 32000;
+        if (config.head_dim <= 0) config.head_dim = config.hidden_dim / config.num_heads;
+        if (config.intermediate_dim <= 0) config.intermediate_dim = config.hidden_dim * 8 / 3;
+    }
+
+    TLLM_INFO("Extracted model config: hidden_dim={}, num_layers={}, num_heads={}, "
+              "num_kv_heads={}, vocab_size={}",
+              config.hidden_dim, config.num_layers, config.num_heads, config.num_kv_heads,
+              config.vocab_size);
+
+    return Result<ModelConfig>::ok(config);
 }
 
-const GGUFTensorInfo *
-GGUFParser::getTensorByName(const std::string &name) const {
-  auto it = tensor_name_map_.find(name);
-  if (it != tensor_name_map_.end()) {
-    return &tensors_[it->second];
-  }
-  return nullptr;
+const GGUFTensorInfo *GGUFParser::getTensorByName(const std::string &name) const {
+    auto it = tensor_name_map_.find(name);
+    if (it != tensor_name_map_.end()) {
+        return &tensors_[it->second];
+    }
+    return nullptr;
 }
 
-Result<std::vector<uint8_t>>
-GGUFParser::readTensorData(const GGUFTensorInfo &tensor) {
-  std::ifstream file(path_, std::ios::binary);
-  if (!file) {
-    return Result<std::vector<uint8_t>>::err("Failed to open file: " + path_);
-  }
+Result<std::vector<uint8_t>> GGUFParser::readTensorData(const GGUFTensorInfo &tensor) {
+    std::ifstream file(path_, std::ios::binary);
+    if (!file) {
+        return Result<std::vector<uint8_t>>::err("Failed to open file: " + path_);
+    }
 
-  uint64_t read_offset = data_offset_ + tensor.offset;
-  file.seekg(read_offset);
+    uint64_t read_offset = data_offset_ + tensor.offset;
+    file.seekg(read_offset);
 
-  if (!file) {
-    return Result<std::vector<uint8_t>>::err(
-        "Failed to seek to tensor data at offset " + std::to_string(read_offset));
-  }
+    if (!file) {
+        return Result<std::vector<uint8_t>>::err("Failed to seek to tensor data at offset " +
+                                                 std::to_string(read_offset));
+    }
 
-  size_t size = tensor.calculateSize();
-  std::vector<uint8_t> data(size);
-  file.read(reinterpret_cast<char *>(data.data()), size);
+    size_t               size = tensor.calculateSize();
+    std::vector<uint8_t> data(size);
+    file.read(reinterpret_cast<char *>(data.data()), size);
 
-  if (!file) {
-    return Result<std::vector<uint8_t>>::err("Failed to read tensor data");
-  }
+    if (!file) {
+        return Result<std::vector<uint8_t>>::err("Failed to read tensor data");
+    }
 
-  return Result<std::vector<uint8_t>>::ok(data);
+    return Result<std::vector<uint8_t>>::ok(data);
 }
 
 // GGUFMetadata methods
-bool GGUFMetadata::has(const std::string &key) const {
-  return kv.find(key) != kv.end();
-}
+bool GGUFMetadata::has(const std::string &key) const { return kv.find(key) != kv.end(); }
 
 // GGUFTensorInfo methods
 size_t GGUFTensorInfo::numElements() const {
-  if (dimensions.empty())
-    return 0;
-  size_t n = 1;
-  for (auto d : dimensions) {
-    n *= d;
-  }
-  return n;
+    if (dimensions.empty()) return 0;
+    size_t n = 1;
+    for (auto d : dimensions) {
+        n *= d;
+    }
+    return n;
 }
 
 size_t GGUFTensorInfo::calculateSize() const {
-  size_t num_elem = numElements();
-
-  // Bytes per element for each type
-  switch (type) {
-  case GGMLType::F32:
-    return num_elem * 4;
-  case GGMLType::F16:
-    return num_elem * 2;
-  case GGMLType::I8:
-    return num_elem;
-  case GGMLType::I16:
-    return num_elem * 2;
-  case GGMLType::I32:
-    return num_elem * 4;
-  case GGMLType::I64:
-    return num_elem * 8;
-  case GGMLType::F64:
-    return num_elem * 8;
-  case GGMLType::Q8_0:
-    // Q8_0: 32 values per block, each block has 32 int8 + 1 half scale
-    return (num_elem / 32) * (32 + 2);
-  case GGMLType::Q4_0:
-    // Q4_0: 32 values per block, each block has 16 int8 + 1 half scale
-    return (num_elem / 32) * (16 + 2);
-  case GGMLType::Q4_1:
-    // Q4_1: 32 values per block, each block has 16 int8 + 2 half (scale + min)
-    return (num_elem / 32) * (16 + 4);
-  default:
-    // Default to 2 bytes per element (FP16)
-    TLLM_WARN("Unknown tensor type {}, assuming FP16 size",
-              static_cast<uint32_t>(type));
-    return num_elem * 2;
-  }
+    size_t num_elem = numElements();
+
+    // Bytes per element for each type
+    switch (type) {
+    case GGMLType::F32:
+        return num_elem * 4;
+    case GGMLType::F16:
+        return num_elem * 2;
+    case GGMLType::I8:
+        return num_elem;
+    case GGMLType::I16:
+        return num_elem * 2;
+    case GGMLType::I32:
+        return num_elem * 4;
+    case GGMLType::I64:
+        return num_elem * 8;
+    case GGMLType::F64:
+        return num_elem * 8;
+    case GGMLType::Q8_0:
+        // Q8_0: 32 values per block, each block has 32 int8 + 1 half scale
+        return (num_elem / 32) * (32 + 2);
+    case GGMLType::Q4_0:
+        // Q4_0: 32 values per block, each block has 16 int8 + 1 half scale
+        return (num_elem / 32) * (16 + 2);
+    case GGMLType::Q4_1:
+        // Q4_1: 32 values per block, each block has 16 int8 + 2 half (scale + min)
+        return (num_elem / 32) * (16 + 4);
+    default:
+        // Default to 2 bytes per element (FP16)
+        TLLM_WARN("Unknown tensor type {}, assuming FP16 size", static_cast<uint32_t>(type));
+        return num_elem * 2;
+    }
 }
 
 } // namespace tiny_llm
diff --git a/src/inference_engine.cpp b/src/inference_engine.cpp
index 40e7b64..b6f732d 100644
--- a/src/inference_engine.cpp
+++ b/src/inference_engine.cpp
@@ -14,504 +14,477 @@
 
 namespace tiny_llm {
 
-Result<std::unique_ptr<InferenceEngine>>
-InferenceEngine::load(const std::string &model_path,
-                      const ModelConfig &config) {
-  TLLM_INFO("Loading model from: {}", model_path);
-
-  // Validate model config
-  auto config_result = Validator::validateModelConfig(config);
-  if (config_result.isErr()) {
-    TLLM_ERROR("Invalid model config: {}", config_result.error());
-    return Result<std::unique_ptr<InferenceEngine>>::err(
-        "Invalid model config: " + config_result.error());
-  }
-
-  if (model_path.size() >= 5 &&
-      model_path.substr(model_path.size() - 5) == ".gguf") {
-    return Result<std::unique_ptr<InferenceEngine>>::err(
-        "GGUF runtime loading is not supported yet; use the test binary format loaded via loadBin().");
-  }
-
-  // Load model weights
-  auto result = ModelLoader::loadBin(model_path, config);
-  if (result.isErr()) {
-    TLLM_ERROR("Failed to load model: {}", result.error());
-    return Result<std::unique_ptr<InferenceEngine>>::err(result.error());
-  }
-
-  auto engine =
-      std::make_unique<InferenceEngine>(config, std::move(result.value()));
-
-  TLLM_INFO("Model loaded successfully: hidden_dim={}, num_layers={}, vocab_size={}",
-            config.hidden_dim, config.num_layers, config.vocab_size);
-
-  return Result<std::unique_ptr<InferenceEngine>>::ok(std::move(engine));
+Result<std::unique_ptr<InferenceEngine>> InferenceEngine::load(const std::string &model_path,
+                                                               const ModelConfig &config) {
+    TLLM_INFO("Loading model from: {}", model_path);
+
+    // Validate model config
+    auto config_result = Validator::validateModelConfig(config);
+    if (config_result.isErr()) {
+        TLLM_ERROR("Invalid model config: {}", config_result.error());
+        return Result<std::unique_ptr<InferenceEngine>>::err("Invalid model config: " +
+                                                             config_result.error());
+    }
+
+    if (model_path.size() >= 5 && model_path.substr(model_path.size() - 5) == ".gguf") {
+        return Result<std::unique_ptr<InferenceEngine>>::err(
+            "GGUF runtime loading is not supported yet; use the test binary format loaded via "
+            "loadBin().");
+    }
+
+    // Load model weights
+    auto result = ModelLoader::loadBin(model_path, config);
+    if (result.isErr()) {
+        TLLM_ERROR("Failed to load model: {}", result.error());
+        return Result<std::unique_ptr<InferenceEngine>>::err(result.error());
+    }
+
+    auto engine = std::make_unique<InferenceEngine>(config, std::move(result.value()));
+
+    TLLM_INFO("Model loaded successfully: hidden_dim={}, num_layers={}, vocab_size={}",
+              config.hidden_dim, config.num_layers, config.vocab_size);
+
+    return Result<std::unique_ptr<InferenceEngine>>::ok(std::move(engine));
 }
 
-InferenceEngine::InferenceEngine(const ModelConfig &config,
-                                 ModelWeights &&weights)
+InferenceEngine::InferenceEngine(const ModelConfig &config, ModelWeights &&weights)
     : config_(config), weights_(std::move(weights)) {
 
-  // Create CUDA stream
-  CUDA_CHECK(cudaStreamCreate(&stream_));
-
-  // Initialize KV cache
-  KVCacheConfig kv_config;
-  kv_config.num_layers = config_.num_layers;
-  kv_config.num_heads = config_.num_kv_heads;
-  kv_config.head_dim = config_.head_dim;
-  kv_config.max_seq_len = config_.max_seq_len;
-  kv_config.max_batch_size = 1;
-  kv_cache_ = std::make_unique<KVCacheManager>(kv_config);
-
-  // Create transformer layers
-  layers_.reserve(config_.num_layers);
-  for (int i = 0; i < config_.num_layers; ++i) {
-    layers_.push_back(
-        std::make_unique<TransformerLayer>(i, weights_.layers[i], config_));
-  }
-
-  // Allocate buffers
-  size_t hidden_size = config_.max_seq_len * config_.hidden_dim * sizeof(half);
-  size_t logits_size = config_.vocab_size * sizeof(half);
-
-  CUDA_CHECK(cudaMalloc(&hidden_states_, hidden_size));
-  CUDA_CHECK(cudaMalloc(&logits_, logits_size));
+    // Create CUDA stream
+    CUDA_CHECK(cudaStreamCreate(&stream_));
+
+    // Initialize KV cache
+    KVCacheConfig kv_config;
+    kv_config.num_layers = config_.num_layers;
+    kv_config.num_heads = config_.num_kv_heads;
+    kv_config.head_dim = config_.head_dim;
+    kv_config.max_seq_len = config_.max_seq_len;
+    kv_config.max_batch_size = 1;
+    kv_cache_ = std::make_unique<KVCacheManager>(kv_config);
+
+    // Create transformer layers
+    layers_.reserve(config_.num_layers);
+    for (int i = 0; i < config_.num_layers; ++i) {
+        layers_.push_back(std::make_unique<TransformerLayer>(i, weights_.layers[i], config_));
+    }
+
+    // Allocate buffers
+    size_t hidden_size = config_.max_seq_len * config_.hidden_dim * sizeof(half);
+    size_t logits_size = config_.vocab_size * sizeof(half);
+
+    CUDA_CHECK(cudaMalloc(&hidden_states_, hidden_size));
+    CUDA_CHECK(cudaMalloc(&logits_, logits_size));
 }
 
 InferenceEngine::~InferenceEngine() {
-  layers_.clear();
-  kv_cache_.reset();
-
-  if (hidden_states_) {
-    cudaError_t err = cudaFree(hidden_states_);
-    if (err != cudaSuccess) {
-      TLLM_ERROR("CUDA error freeing hidden_states: {}", cudaGetErrorString(err));
-    }
-    hidden_states_ = nullptr;
-  }
-  if (logits_) {
-    cudaError_t err = cudaFree(logits_);
-    if (err != cudaSuccess) {
-      TLLM_ERROR("CUDA error freeing logits: {}", cudaGetErrorString(err));
-    }
-    logits_ = nullptr;
-  }
-  if (stream_) {
-    cudaError_t err = cudaStreamDestroy(stream_);
-    if (err != cudaSuccess) {
-      TLLM_ERROR("CUDA error destroying stream: {}", cudaGetErrorString(err));
-    }
-    stream_ = nullptr;
-  }
-
-  ModelLoader::freeWeights(weights_);
+    layers_.clear();
+    kv_cache_.reset();
+
+    if (hidden_states_) {
+        cudaError_t err = cudaFree(hidden_states_);
+        if (err != cudaSuccess) {
+            TLLM_ERROR("CUDA error freeing hidden_states: {}", cudaGetErrorString(err));
+        }
+        hidden_states_ = nullptr;
+    }
+    if (logits_) {
+        cudaError_t err = cudaFree(logits_);
+        if (err != cudaSuccess) {
+            TLLM_ERROR("CUDA error freeing logits: {}", cudaGetErrorString(err));
+        }
+        logits_ = nullptr;
+    }
+    if (stream_) {
+        cudaError_t err = cudaStreamDestroy(stream_);
+        if (err != cudaSuccess) {
+            TLLM_ERROR("CUDA error destroying stream: {}", cudaGetErrorString(err));
+        }
+        stream_ = nullptr;
+    }
+
+    ModelLoader::freeWeights(weights_);
 }
 
-Result<std::vector<int>>
-InferenceEngine::generate(const std::vector<int> &prompt_tokens,
-                          const GenerationConfig &config) {
-  stats_ = GenerationStats{};
-
-  // 1. Validate generation config
-  auto config_result = config.validate();
-  if (config_result.isErr()) {
-    TLLM_ERROR("Invalid generation config: {}", config_result.error());
-    return Result<std::vector<int>>::err(
-        "Invalid generation config: " + config_result.error());
-  }
-
-  // 2. Validate prompt tokens
-  if (prompt_tokens.empty()) {
-    TLLM_ERROR("generate: prompt_tokens is empty");
-    return Result<std::vector<int>>::err("prompt_tokens cannot be empty");
-  }
-
-  auto token_result = Validator::validateTokenSequence(
-      prompt_tokens, config_.vocab_size, "generate");
-  if (token_result.isErr()) {
-    TLLM_ERROR("{}", token_result.error());
-    return Result<std::vector<int>>::err(token_result.error());
-  }
-
-  // 3. Validate prompt length
-  auto length_result = Validator::validatePromptLength(
-      static_cast<int>(prompt_tokens.size()), config.max_new_tokens,
-      config_.max_seq_len);
-  if (length_result.isErr()) {
-    TLLM_ERROR("{}", length_result.error());
-    return Result<std::vector<int>>::err(length_result.error());
-  }
-
-  stats_.prompt_tokens = static_cast<int>(prompt_tokens.size());
-  TLLM_INFO("Starting generation: prompt_tokens={}, max_new_tokens={}",
-            prompt_tokens.size(), config.max_new_tokens);
-
-  // Allocate sequence in KV cache
-  int total_len =
-      static_cast<int>(prompt_tokens.size()) + config.max_new_tokens;
-  auto alloc_result =
-      kv_cache_->allocateSequence(std::min(total_len, config_.max_seq_len));
-  if (alloc_result.isErr()) {
-    TLLM_ERROR("Failed to allocate KV cache: {}", alloc_result.error());
-    return Result<std::vector<int>>::err(
-        "Failed to allocate KV cache: " + alloc_result.error());
-  }
-  int seq_id = alloc_result.value();
-  TLLM_DEBUG("Allocated KV cache sequence: seq_id={}", seq_id);
-
-  std::vector<int> output_tokens;
-  output_tokens.reserve(config.max_new_tokens);
-
-  // Prefill phase
-  auto prefill_start = std::chrono::high_resolution_clock::now();
-  prefill(prompt_tokens, seq_id);
-  CUDA_CHECK(cudaStreamSynchronize(stream_));
-  auto prefill_end = std::chrono::high_resolution_clock::now();
-  stats_.prefill_time_ms =
-      std::chrono::duration<float, std::milli>(prefill_end - prefill_start)
-          .count();
-
-  TLLM_DEBUG("Prefill completed: time={:.2f}ms", stats_.prefill_time_ms);
-
-  // Decode phase
-  auto decode_start = std::chrono::high_resolution_clock::now();
-  int position = static_cast<int>(prompt_tokens.size());
-  int prev_token =
-      prompt_tokens.empty() ? config_.bos_token_id : prompt_tokens.back();
-  int generated = 0;
-
-  if (!prompt_tokens.empty() && position > 0 &&
-      generated < config.max_new_tokens) {
-    half *last_hidden = hidden_states_ + (position - 1) * config_.hidden_dim;
-    int next_token = sampleFromHidden(last_hidden, config);
-    output_tokens.push_back(next_token);
-    ++generated;
-
-    if (next_token == config_.eos_token_id) {
-      CUDA_CHECK(cudaStreamSynchronize(stream_));
-      auto decode_end = std::chrono::high_resolution_clock::now();
-      stats_.decode_time_ms =
-          std::chrono::duration<float, std::milli>(decode_end - decode_start)
-              .count();
-      stats_.tokens_generated = static_cast<int>(output_tokens.size());
-      if (stats_.decode_time_ms > 0) {
-        stats_.tokens_per_second =
-            stats_.tokens_generated / (stats_.decode_time_ms / 1000.0f);
-      }
-      TLLM_INFO("Generation stopped at EOS token: generated={}, time={:.2f}ms",
-                stats_.tokens_generated, stats_.decode_time_ms);
-      auto release_result = kv_cache_->releaseSequence(seq_id);
-      if (release_result.isErr()) {
+Result<std::vector<int>> InferenceEngine::generate(const std::vector<int> &prompt_tokens,
+                                                   const GenerationConfig &config) {
+    stats_ = GenerationStats{};
+
+    // 1. Validate generation config
+    auto config_result = config.validate();
+    if (config_result.isErr()) {
+        TLLM_ERROR("Invalid generation config: {}", config_result.error());
+        return Result<std::vector<int>>::err("Invalid generation config: " + config_result.error());
+    }
+
+    // 2. Validate prompt tokens
+    if (prompt_tokens.empty()) {
+        TLLM_ERROR("generate: prompt_tokens is empty");
+        return Result<std::vector<int>>::err("prompt_tokens cannot be empty");
+    }
+
+    auto token_result =
+        Validator::validateTokenSequence(prompt_tokens, config_.vocab_size, "generate");
+    if (token_result.isErr()) {
+        TLLM_ERROR("{}", token_result.error());
+        return Result<std::vector<int>>::err(token_result.error());
+    }
+
+    // 3. Validate prompt length
+    auto length_result = Validator::validatePromptLength(
+        static_cast<int>(prompt_tokens.size()), config.max_new_tokens, config_.max_seq_len);
+    if (length_result.isErr()) {
+        TLLM_ERROR("{}", length_result.error());
+        return Result<std::vector<int>>::err(length_result.error());
+    }
+
+    stats_.prompt_tokens = static_cast<int>(prompt_tokens.size());
+    TLLM_INFO("Starting generation: prompt_tokens={}, max_new_tokens={}", prompt_tokens.size(),
+              config.max_new_tokens);
+
+    // Allocate sequence in KV cache
+    int  total_len = static_cast<int>(prompt_tokens.size()) + config.max_new_tokens;
+    auto alloc_result = kv_cache_->allocateSequence(std::min(total_len, config_.max_seq_len));
+    if (alloc_result.isErr()) {
+        TLLM_ERROR("Failed to allocate KV cache: {}", alloc_result.error());
+        return Result<std::vector<int>>::err("Failed to allocate KV cache: " +
+                                             alloc_result.error());
+    }
+    int seq_id = alloc_result.value();
+    TLLM_DEBUG("Allocated KV cache sequence: seq_id={}", seq_id);
+
+    std::vector<int> output_tokens;
+    output_tokens.reserve(config.max_new_tokens);
+
+    // Prefill phase
+    auto prefill_start = std::chrono::high_resolution_clock::now();
+    prefill(prompt_tokens, seq_id);
+    CUDA_CHECK(cudaStreamSynchronize(stream_));
+    auto prefill_end = std::chrono::high_resolution_clock::now();
+    stats_.prefill_time_ms =
+        std::chrono::duration<float, std::milli>(prefill_end - prefill_start).count();
+
+    TLLM_DEBUG("Prefill completed: time={:.2f}ms", stats_.prefill_time_ms);
+
+    // Decode phase
+    auto decode_start = std::chrono::high_resolution_clock::now();
+    int  position = static_cast<int>(prompt_tokens.size());
+    int  prev_token = prompt_tokens.empty() ? config_.bos_token_id : prompt_tokens.back();
+    int  generated = 0;
+
+    if (!prompt_tokens.empty() && position > 0 && generated < config.max_new_tokens) {
+        half *last_hidden = hidden_states_ + (position - 1) * config_.hidden_dim;
+        int   next_token = sampleFromHidden(last_hidden, config);
+        output_tokens.push_back(next_token);
+        ++generated;
+
+        if (next_token == config_.eos_token_id) {
+            CUDA_CHECK(cudaStreamSynchronize(stream_));
+            auto decode_end = std::chrono::high_resolution_clock::now();
+            stats_.decode_time_ms =
+                std::chrono::duration<float, std::milli>(decode_end - decode_start).count();
+            stats_.tokens_generated = static_cast<int>(output_tokens.size());
+            if (stats_.decode_time_ms > 0) {
+                stats_.tokens_per_second =
+                    stats_.tokens_generated / (stats_.decode_time_ms / 1000.0f);
+            }
+            TLLM_INFO("Generation stopped at EOS token: generated={}, time={:.2f}ms",
+                      stats_.tokens_generated, stats_.decode_time_ms);
+            auto release_result = kv_cache_->releaseSequence(seq_id);
+            if (release_result.isErr()) {
+                TLLM_WARN("Failed to release sequence: {}", release_result.error());
+            }
+            return Result<std::vector<int>>::ok(output_tokens);
+        }
+        prev_token = next_token;
+    }
+
+    while (generated < config.max_new_tokens && position < config_.max_seq_len) {
+        int next_token = decodeStep(seq_id, position, prev_token, config);
+        output_tokens.push_back(next_token);
+        ++generated;
+
+        // Check for EOS
+        if (next_token == config_.eos_token_id) break;
+
+        prev_token = next_token;
+        ++position;
+    }
+
+    CUDA_CHECK(cudaStreamSynchronize(stream_));
+    auto decode_end = std::chrono::high_resolution_clock::now();
+    stats_.decode_time_ms =
+        std::chrono::duration<float, std::milli>(decode_end - decode_start).count();
+    stats_.tokens_generated = static_cast<int>(output_tokens.size());
+
+    if (stats_.decode_time_ms > 0) {
+        stats_.tokens_per_second = stats_.tokens_generated / (stats_.decode_time_ms / 1000.0f);
+    }
+
+    TLLM_INFO("Generation completed: tokens={}, prefill={:.2f}ms, decode={:.2f}ms, tps={:.2f}",
+              stats_.tokens_generated, stats_.prefill_time_ms, stats_.decode_time_ms,
+              stats_.tokens_per_second);
+
+    // Release sequence
+    auto release_result = kv_cache_->releaseSequence(seq_id);
+    if (release_result.isErr()) {
         TLLM_WARN("Failed to release sequence: {}", release_result.error());
-      }
-      return Result<std::vector<int>>::ok(output_tokens);
-    }
-    prev_token = next_token;
-  }
-
-  while (generated < config.max_new_tokens && position < config_.max_seq_len) {
-    int next_token = decodeStep(seq_id, position, prev_token, config);
-    output_tokens.push_back(next_token);
-    ++generated;
-
-    // Check for EOS
-    if (next_token == config_.eos_token_id)
-      break;
-
-    prev_token = next_token;
-    ++position;
-  }
-
-  CUDA_CHECK(cudaStreamSynchronize(stream_));
-  auto decode_end = std::chrono::high_resolution_clock::now();
-  stats_.decode_time_ms =
-      std::chrono::duration<float, std::milli>(decode_end - decode_start)
-          .count();
-  stats_.tokens_generated = static_cast<int>(output_tokens.size());
-
-  if (stats_.decode_time_ms > 0) {
-    stats_.tokens_per_second =
-        stats_.tokens_generated / (stats_.decode_time_ms / 1000.0f);
-  }
-
-  TLLM_INFO("Generation completed: tokens={}, prefill={:.2f}ms, decode={:.2f}ms, tps={:.2f}",
-            stats_.tokens_generated, stats_.prefill_time_ms,
-            stats_.decode_time_ms, stats_.tokens_per_second);
-
-  // Release sequence
-  auto release_result = kv_cache_->releaseSequence(seq_id);
-  if (release_result.isErr()) {
-    TLLM_WARN("Failed to release sequence: {}", release_result.error());
-  }
-
-  return Result<std::vector<int>>::ok(output_tokens);
+    }
+
+    return Result<std::vector<int>>::ok(output_tokens);
 }
 
 void InferenceEngine::prefill(const std::vector<int> &tokens, int seq_id) {
-  int num_tokens = static_cast<int>(tokens.size());
-  if (num_tokens <= 0) {
-    TLLM_WARN("prefill: empty token sequence");
-    return;
-  }
-
-  TLLM_TRACE("prefill: seq_id={}, num_tokens={}", seq_id, num_tokens);
-
-  // Validate token IDs (debug mode only for performance)
-  TLLM_DEBUG_IF(true, "prefill: validating {} token IDs", num_tokens);
-  for (int i = 0; i < num_tokens; ++i) {
-    if (tokens[i] < 0 || tokens[i] >= config_.vocab_size) {
-      TLLM_ERROR("prefill: invalid token_id {} at position {}, vocab_size={}",
-                 tokens[i], i, config_.vocab_size);
-      return;
-    }
-  }
-
-  // Embed tokens
-  std::vector<int> h_tokens(tokens);
-  DeviceBuffer<int> d_tokens(num_tokens);
-  d_tokens.copyFromHost(h_tokens.data(), num_tokens, stream_);
-
-  embedTokens(d_tokens.data(), num_tokens, hidden_states_);
-
-  // Forward through all layers
-  for (auto &layer : layers_) {
-    layer->forwardPrefill(hidden_states_, *kv_cache_, seq_id, num_tokens,
-                          stream_);
-  }
-
-  auto advance_result = kv_cache_->advanceSeqLen(seq_id, num_tokens);
-  if (advance_result.isErr()) {
-    TLLM_ERROR("prefill: {}", advance_result.error());
-  }
+    int num_tokens = static_cast<int>(tokens.size());
+    if (num_tokens <= 0) {
+        TLLM_WARN("prefill: empty token sequence");
+        return;
+    }
+
+    TLLM_TRACE("prefill: seq_id={}, num_tokens={}", seq_id, num_tokens);
+
+    // Validate token IDs (debug mode only for performance)
+    TLLM_DEBUG_IF(true, "prefill: validating {} token IDs", num_tokens);
+    for (int i = 0; i < num_tokens; ++i) {
+        if (tokens[i] < 0 || tokens[i] >= config_.vocab_size) {
+            TLLM_ERROR("prefill: invalid token_id {} at position {}, vocab_size={}", tokens[i], i,
+                       config_.vocab_size);
+            return;
+        }
+    }
+
+    // Embed tokens
+    std::vector<int>  h_tokens(tokens);
+    DeviceBuffer<int> d_tokens(num_tokens);
+    d_tokens.copyFromHost(h_tokens.data(), num_tokens, stream_);
+
+    embedTokens(d_tokens.data(), num_tokens, hidden_states_);
+
+    // Forward through all layers
+    for (auto &layer : layers_) {
+        layer->forwardPrefill(hidden_states_, *kv_cache_, seq_id, num_tokens, stream_);
+    }
+
+    auto advance_result = kv_cache_->advanceSeqLen(seq_id, num_tokens);
+    if (advance_result.isErr()) {
+        TLLM_ERROR("prefill: {}", advance_result.error());
+    }
 }
 
 int InferenceEngine::decodeStep(int seq_id, int position, int token_id,
                                 const GenerationConfig &config) {
-  DeviceBuffer<int> d_token(1);
-  d_token.copyFromHost(&token_id, 1, stream_);
+    DeviceBuffer<int> d_token(1);
+    d_token.copyFromHost(&token_id, 1, stream_);
 
-  half *token_state = hidden_states_ + position * config_.hidden_dim;
-  embedTokens(d_token.data(), 1, token_state);
+    half *token_state = hidden_states_ + position * config_.hidden_dim;
+    embedTokens(d_token.data(), 1, token_state);
 
-  // Forward through all layers for single token
-  for (auto &layer : layers_) {
-    layer->forward(token_state, *kv_cache_, seq_id, position, stream_);
-  }
+    // Forward through all layers for single token
+    for (auto &layer : layers_) {
+        layer->forward(token_state, *kv_cache_, seq_id, position, stream_);
+    }
 
-  kv_cache_->advanceSeqLen(seq_id, 1);
+    kv_cache_->advanceSeqLen(seq_id, 1);
 
-  return sampleFromHidden(token_state, config);
+    return sampleFromHidden(token_state, config);
 }
 
-int InferenceEngine::sampleFromHidden(half *hidden_state,
-                                      const GenerationConfig &config) {
-  finalNorm(hidden_state, hidden_state, 1);
-  computeLogits(hidden_state, 1, logits_);
+int InferenceEngine::sampleFromHidden(half *hidden_state, const GenerationConfig &config) {
+    finalNorm(hidden_state, hidden_state, 1);
+    computeLogits(hidden_state, 1, logits_);
 
-  CUDA_CHECK(cudaStreamSynchronize(stream_));
+    CUDA_CHECK(cudaStreamSynchronize(stream_));
 
-  std::vector<half> h_logits(config_.vocab_size);
-  CUDA_CHECK(cudaMemcpy(h_logits.data(), logits_,
-                        config_.vocab_size * sizeof(half),
-                        cudaMemcpyDeviceToHost));
+    std::vector<half> h_logits(config_.vocab_size);
+    CUDA_CHECK(cudaMemcpy(h_logits.data(), logits_, config_.vocab_size * sizeof(half),
+                          cudaMemcpyDeviceToHost));
 
-  return sample(h_logits.data(), config);
+    return sample(h_logits.data(), config);
 }
 
-void InferenceEngine::embedTokens(const int *tokens, int num_tokens,
-                                  half *output) {
-  kernels::gather_embeddings(tokens, weights_.token_embedding, output, num_tokens,
-                             config_.hidden_dim, config_.vocab_size, stream_);
+void InferenceEngine::embedTokens(const int *tokens, int num_tokens, half *output) {
+    kernels::gather_embeddings(tokens, weights_.token_embedding, output, num_tokens,
+                               config_.hidden_dim, config_.vocab_size, stream_);
 }
 
-void InferenceEngine::computeLogits(const half *hidden_states, int num_tokens,
-                                    half *logits) {
-  // LM head projection: hidden_states @ lm_head.T
-  if (weights_.lm_head.isValid()) {
-    kernels::w8a16_matmul(hidden_states, weights_.lm_head.data,
-                          weights_.lm_head.scales, logits, num_tokens,
-                          config_.vocab_size, config_.hidden_dim,
-                          weights_.lm_head.group_size, stream_);
-  }
+void InferenceEngine::computeLogits(const half *hidden_states, int num_tokens, half *logits) {
+    // LM head projection: hidden_states @ lm_head.T
+    if (weights_.lm_head.isValid()) {
+        kernels::w8a16_matmul(hidden_states, weights_.lm_head.data, weights_.lm_head.scales, logits,
+                              num_tokens, config_.vocab_size, config_.hidden_dim,
+                              weights_.lm_head.group_size, stream_);
+    }
 }
 
-void InferenceEngine::finalNorm(const half *input, half *output,
-                                int num_tokens) {
-  if (weights_.final_norm_weight) {
-    kernels::rmsnorm(input, weights_.final_norm_weight, output, num_tokens,
-                     config_.hidden_dim, config_.rms_norm_eps, stream_);
-  }
+void InferenceEngine::finalNorm(const half *input, half *output, int num_tokens) {
+    if (weights_.final_norm_weight) {
+        kernels::rmsnorm(input, weights_.final_norm_weight, output, num_tokens, config_.hidden_dim,
+                         config_.rms_norm_eps, stream_);
+    }
 }
 
-int InferenceEngine::sample(const half *logits,
-                            const GenerationConfig &config) {
-  if (!config.do_sample) {
-    return sampleGreedy(logits, config_.vocab_size);
-  }
+int InferenceEngine::sample(const half *logits, const GenerationConfig &config) {
+    if (!config.do_sample) {
+        return sampleGreedy(logits, config_.vocab_size);
+    }
 
-  if (config.top_p < 1.0f) {
-    return sampleTopP(logits, config_.vocab_size, config.top_p,
-                      config.temperature);
-  }
+    if (config.top_p < 1.0f) {
+        return sampleTopP(logits, config_.vocab_size, config.top_p, config.temperature);
+    }
 
-  if (config.top_k > 0) {
-    return sampleTopK(logits, config_.vocab_size, config.top_k,
-                      config.temperature);
-  }
+    if (config.top_k > 0) {
+        return sampleTopK(logits, config_.vocab_size, config.top_k, config.temperature);
+    }
 
-  return sampleTemperature(logits, config_.vocab_size, config.temperature);
+    return sampleTemperature(logits, config_.vocab_size, config.temperature);
 }
 
 // Greedy sampling: return argmax
 int InferenceEngine::sampleGreedy(const half *logits, int vocab_size) {
-  if (!logits || vocab_size <= 0) {
-    return 0;
-  }
+    if (!logits || vocab_size <= 0) {
+        return 0;
+    }
 
-  int max_idx = 0;
-  float max_val = __half2float(logits[0]);
+    int   max_idx = 0;
+    float max_val = __half2float(logits[0]);
 
-  for (int i = 1; i < vocab_size; ++i) {
-    float val = __half2float(logits[i]);
-    if (val > max_val) {
-      max_val = val;
-      max_idx = i;
+    for (int i = 1; i < vocab_size; ++i) {
+        float val = __half2float(logits[i]);
+        if (val > max_val) {
+            max_val = val;
+            max_idx = i;
+        }
     }
-  }
 
-  return max_idx;
+    return max_idx;
 }
 
 // Temperature sampling
-int InferenceEngine::sampleTemperature(const half *logits, int vocab_size,
-                                       float temperature, unsigned seed) {
-  if (!logits || vocab_size <= 0) {
-    return 0;
-  }
-  temperature = std::max(temperature, 1e-5f);
-
-  std::vector<float> probs(vocab_size);
-  float max_logit = __half2float(logits[0]);
-
-  // Find max for numerical stability
-  for (int i = 1; i < vocab_size; ++i) {
-    max_logit = std::max(max_logit, __half2float(logits[i]));
-  }
-
-  // Apply temperature and softmax
-  float sum = 0.0f;
-  for (int i = 0; i < vocab_size; ++i) {
-    probs[i] = std::exp((__half2float(logits[i]) - max_logit) / temperature);
-    sum += probs[i];
-  }
-
-  for (int i = 0; i < vocab_size; ++i) {
-    probs[i] /= sum;
-  }
-
-  // Sample from distribution
-  std::mt19937 gen(seed ? seed : std::random_device{}());
-  std::discrete_distribution<int> dist(probs.begin(), probs.end());
-
-  return dist(gen);
+int InferenceEngine::sampleTemperature(const half *logits, int vocab_size, float temperature,
+                                       unsigned seed) {
+    if (!logits || vocab_size <= 0) {
+        return 0;
+    }
+    temperature = std::max(temperature, 1e-5f);
+
+    std::vector<float> probs(vocab_size);
+    float              max_logit = __half2float(logits[0]);
+
+    // Find max for numerical stability
+    for (int i = 1; i < vocab_size; ++i) {
+        max_logit = std::max(max_logit, __half2float(logits[i]));
+    }
+
+    // Apply temperature and softmax
+    float sum = 0.0f;
+    for (int i = 0; i < vocab_size; ++i) {
+        probs[i] = std::exp((__half2float(logits[i]) - max_logit) / temperature);
+        sum += probs[i];
+    }
+
+    for (int i = 0; i < vocab_size; ++i) {
+        probs[i] /= sum;
+    }
+
+    // Sample from distribution
+    std::mt19937                    gen(seed ? seed : std::random_device{}());
+    std::discrete_distribution<int> dist(probs.begin(), probs.end());
+
+    return dist(gen);
 }
 
 // Top-k sampling
-int InferenceEngine::sampleTopK(const half *logits, int vocab_size, int k,
-                                float temperature, unsigned seed) {
-  if (!logits || vocab_size <= 0) {
-    return 0;
-  }
-  temperature = std::max(temperature, 1e-5f);
-  k = std::max(1, std::min(k, vocab_size));
-
-  // Get top-k indices
-  std::vector<std::pair<float, int>> logit_pairs(vocab_size);
-  for (int i = 0; i < vocab_size; ++i) {
-    logit_pairs[i] = {__half2float(logits[i]), i};
-  }
-
-  std::partial_sort(
-      logit_pairs.begin(), logit_pairs.begin() + k, logit_pairs.end(),
-      [](const auto &a, const auto &b) { return a.first > b.first; });
-
-  // Apply temperature and softmax to top-k
-  std::vector<float> probs(k);
-  float max_logit = logit_pairs[0].first;
-  float sum = 0.0f;
-
-  for (int i = 0; i < k; ++i) {
-    probs[i] = std::exp((logit_pairs[i].first - max_logit) / temperature);
-    sum += probs[i];
-  }
-
-  for (int i = 0; i < k; ++i) {
-    probs[i] /= sum;
-  }
-
-  // Sample
-  std::mt19937 gen(seed ? seed : std::random_device{}());
-  std::discrete_distribution<int> dist(probs.begin(), probs.end());
-
-  return logit_pairs[dist(gen)].second;
+int InferenceEngine::sampleTopK(const half *logits, int vocab_size, int k, float temperature,
+                                unsigned seed) {
+    if (!logits || vocab_size <= 0) {
+        return 0;
+    }
+    temperature = std::max(temperature, 1e-5f);
+    k = std::max(1, std::min(k, vocab_size));
+
+    // Get top-k indices
+    std::vector<std::pair<float, int>> logit_pairs(vocab_size);
+    for (int i = 0; i < vocab_size; ++i) {
+        logit_pairs[i] = {__half2float(logits[i]), i};
+    }
+
+    std::partial_sort(logit_pairs.begin(), logit_pairs.begin() + k, logit_pairs.end(),
+                      [](const auto &a, const auto &b) { return a.first > b.first; });
+
+    // Apply temperature and softmax to top-k
+    std::vector<float> probs(k);
+    float              max_logit = logit_pairs[0].first;
+    float              sum = 0.0f;
+
+    for (int i = 0; i < k; ++i) {
+        probs[i] = std::exp((logit_pairs[i].first - max_logit) / temperature);
+        sum += probs[i];
+    }
+
+    for (int i = 0; i < k; ++i) {
+        probs[i] /= sum;
+    }
+
+    // Sample
+    std::mt19937                    gen(seed ? seed : std::random_device{}());
+    std::discrete_distribution<int> dist(probs.begin(), probs.end());
+
+    return logit_pairs[dist(gen)].second;
 }
 
 // Top-p (nucleus) sampling
-int InferenceEngine::sampleTopP(const half *logits, int vocab_size, float p,
-                                float temperature, unsigned seed) {
-  if (!logits || vocab_size <= 0) {
-    return 0;
-  }
-  temperature = std::max(temperature, 1e-5f);
-  p = std::min(std::max(p, 1e-5f), 1.0f);
-
-  // Sort by logit value
-  std::vector<std::pair<float, int>> logit_pairs(vocab_size);
-  for (int i = 0; i < vocab_size; ++i) {
-    logit_pairs[i] = {__half2float(logits[i]), i};
-  }
-
-  std::sort(logit_pairs.begin(), logit_pairs.end(),
-            [](const auto &a, const auto &b) { return a.first > b.first; });
-
-  // Apply temperature and compute cumulative probability
-  float max_logit = logit_pairs[0].first;
-  std::vector<float> probs(vocab_size);
-  float sum = 0.0f;
-
-  for (int i = 0; i < vocab_size; ++i) {
-    probs[i] = std::exp((logit_pairs[i].first - max_logit) / temperature);
-    sum += probs[i];
-  }
-
-  // Normalize and find cutoff
-  float cumsum = 0.0f;
-  int cutoff = vocab_size;
-  for (int i = 0; i < vocab_size; ++i) {
-    probs[i] /= sum;
-    cumsum += probs[i];
-    if (cumsum >= p) {
-      cutoff = i + 1;
-      break;
-    }
-  }
-
-  // Renormalize top-p tokens
-  float top_p_sum = 0.0f;
-  for (int i = 0; i < cutoff; ++i) {
-    top_p_sum += probs[i];
-  }
-  for (int i = 0; i < cutoff; ++i) {
-    probs[i] /= top_p_sum;
-  }
-
-  // Sample
-  std::mt19937 gen(seed ? seed : std::random_device{}());
-  std::discrete_distribution<int> dist(probs.begin(), probs.begin() + cutoff);
-
-  return logit_pairs[dist(gen)].second;
+int InferenceEngine::sampleTopP(const half *logits, int vocab_size, float p, float temperature,
+                                unsigned seed) {
+    if (!logits || vocab_size <= 0) {
+        return 0;
+    }
+    temperature = std::max(temperature, 1e-5f);
+    p = std::min(std::max(p, 1e-5f), 1.0f);
+
+    // Sort by logit value
+    std::vector<std::pair<float, int>> logit_pairs(vocab_size);
+    for (int i = 0; i < vocab_size; ++i) {
+        logit_pairs[i] = {__half2float(logits[i]), i};
+    }
+
+    std::sort(logit_pairs.begin(), logit_pairs.end(),
+              [](const auto &a, const auto &b) { return a.first > b.first; });
+
+    // Apply temperature and compute cumulative probability
+    float              max_logit = logit_pairs[0].first;
+    std::vector<float> probs(vocab_size);
+    float              sum = 0.0f;
+
+    for (int i = 0; i < vocab_size; ++i) {
+        probs[i] = std::exp((logit_pairs[i].first - max_logit) / temperature);
+        sum += probs[i];
+    }
+
+    // Normalize and find cutoff
+    float cumsum = 0.0f;
+    int   cutoff = vocab_size;
+    for (int i = 0; i < vocab_size; ++i) {
+        probs[i] /= sum;
+        cumsum += probs[i];
+        if (cumsum >= p) {
+            cutoff = i + 1;
+            break;
+        }
+    }
+
+    // Renormalize top-p tokens
+    float top_p_sum = 0.0f;
+    for (int i = 0; i < cutoff; ++i) {
+        top_p_sum += probs[i];
+    }
+    for (int i = 0; i < cutoff; ++i) {
+        probs[i] /= top_p_sum;
+    }
+
+    // Sample
+    std::mt19937                    gen(seed ? seed : std::random_device{}());
+    std::discrete_distribution<int> dist(probs.begin(), probs.begin() + cutoff);
+
+    return logit_pairs[dist(gen)].second;
 }
 
 } // namespace tiny_llm
diff --git a/src/kv_cache.cpp b/src/kv_cache.cpp
index 5e5ec84..152ae72 100644
--- a/src/kv_cache.cpp
+++ b/src/kv_cache.cpp
@@ -7,288 +7,276 @@ namespace tiny_llm {
 
 KVCacheManager::KVCacheManager(const KVCacheConfig &config) : config_(config) {
 
-  // Validate configuration to prevent overflow
-  if (config_.num_layers <= 0 || config_.num_heads <= 0 || 
-      config_.head_dim <= 0 || config_.max_seq_len <= 0 || config_.max_batch_size <= 0) {
-    throw std::invalid_argument("KVCacheManager: invalid configuration parameters");
-  }
-
-  // Calculate per-slot memory size with overflow check
-  size_t kv_per_layer = static_cast<size_t>(config_.num_heads) *
-                        config_.max_seq_len * config_.head_dim;
-  
-  size_t kv_total = kv_per_layer * static_cast<size_t>(config_.num_layers) * 2;
-  
-  if (kv_total > SIZE_MAX / sizeof(half)) {
-    throw std::runtime_error("KVCacheManager: memory size overflow");
-  }
-  slot_size_ = kv_total * sizeof(half);
-
-  // Total pool size for all batch slots
-  if (slot_size_ > SIZE_MAX / static_cast<size_t>(config_.max_batch_size)) {
-    throw std::runtime_error("KVCacheManager: pool size overflow");
-  }
-  pool_size_ = slot_size_ * static_cast<size_t>(config_.max_batch_size);
-
-  // Allocate GPU memory pool
-  CUDA_CHECK(cudaMalloc(&memory_pool_, pool_size_));
-  CUDA_CHECK(cudaMemset(memory_pool_, 0, pool_size_));
-
-  // Initialize slots
-  slots_.resize(config_.max_batch_size);
-  for (auto &slot : slots_) {
-    slot.active = false;
-    slot.seq_id = -1;
-    slot.current_len = 0;
-    slot.max_len = config_.max_seq_len;
-  }
+    // Validate configuration to prevent overflow
+    if (config_.num_layers <= 0 || config_.num_heads <= 0 || config_.head_dim <= 0 ||
+        config_.max_seq_len <= 0 || config_.max_batch_size <= 0) {
+        throw std::invalid_argument("KVCacheManager: invalid configuration parameters");
+    }
+
+    // Calculate per-slot memory size with overflow check
+    size_t kv_per_layer =
+        static_cast<size_t>(config_.num_heads) * config_.max_seq_len * config_.head_dim;
+
+    size_t kv_total = kv_per_layer * static_cast<size_t>(config_.num_layers) * 2;
+
+    if (kv_total > SIZE_MAX / sizeof(half)) {
+        throw std::runtime_error("KVCacheManager: memory size overflow");
+    }
+    slot_size_ = kv_total * sizeof(half);
+
+    // Total pool size for all batch slots
+    if (slot_size_ > SIZE_MAX / static_cast<size_t>(config_.max_batch_size)) {
+        throw std::runtime_error("KVCacheManager: pool size overflow");
+    }
+    pool_size_ = slot_size_ * static_cast<size_t>(config_.max_batch_size);
+
+    // Allocate GPU memory pool
+    CUDA_CHECK(cudaMalloc(&memory_pool_, pool_size_));
+    CUDA_CHECK(cudaMemset(memory_pool_, 0, pool_size_));
+
+    // Initialize slots
+    slots_.resize(config_.max_batch_size);
+    for (auto &slot : slots_) {
+        slot.active = false;
+        slot.seq_id = -1;
+        slot.current_len = 0;
+        slot.max_len = config_.max_seq_len;
+    }
 }
 
 KVCacheManager::~KVCacheManager() {
-  if (memory_pool_) {
-    cudaFree(memory_pool_);
-    memory_pool_ = nullptr;
-  }
+    if (memory_pool_) {
+        cudaFree(memory_pool_);
+        memory_pool_ = nullptr;
+    }
 }
 
-size_t KVCacheManager::calculateOffset(int slot_idx, int layer_idx,
-                                       bool is_value) const {
-  // Memory layout per slot:
-  // [Layer 0 K][Layer 0 V][Layer 1 K][Layer 1 V]...
-  size_t kv_per_layer = static_cast<size_t>(config_.num_heads) *
-                        config_.max_seq_len * config_.head_dim;
+size_t KVCacheManager::calculateOffset(int slot_idx, int layer_idx, bool is_value) const {
+    // Memory layout per slot:
+    // [Layer 0 K][Layer 0 V][Layer 1 K][Layer 1 V]...
+    size_t kv_per_layer =
+        static_cast<size_t>(config_.num_heads) * config_.max_seq_len * config_.head_dim;
 
-  size_t slot_offset = slot_idx * slot_size_ / sizeof(half);
-  size_t layer_offset = layer_idx * kv_per_layer * 2;
-  size_t kv_offset = is_value ? kv_per_layer : 0;
+    size_t slot_offset = slot_idx * slot_size_ / sizeof(half);
+    size_t layer_offset = layer_idx * kv_per_layer * 2;
+    size_t kv_offset = is_value ? kv_per_layer : 0;
 
-  return slot_offset + layer_offset + kv_offset;
+    return slot_offset + layer_offset + kv_offset;
 }
 
 int KVCacheManager::findFreeSlot() const {
-  for (int i = 0; i < static_cast<int>(slots_.size()); ++i) {
-    if (!slots_[i].active) {
-      return i;
+    for (int i = 0; i < static_cast<int>(slots_.size()); ++i) {
+        if (!slots_[i].active) {
+            return i;
+        }
     }
-  }
-  return -1;
+    return -1;
 }
 
 Result<int> KVCacheManager::allocateSequence(int max_len) {
-  // Validate max_len
-  if (max_len <= 0 || max_len > config_.max_seq_len) {
-    return Result<int>::err("Invalid max_len: " + std::to_string(max_len) +
-                            " (must be 1-" +
-                            std::to_string(config_.max_seq_len) + ")");
-  }
-
-  // Find free slot
-  int slot_idx = findFreeSlot();
-  if (slot_idx < 0) {
-    return Result<int>::err("KV cache exhausted: no free slots available. "
-                            "Used: " +
-                            std::to_string(getUsedMemory()) +
-                            " bytes, "
-                            "Total: " +
-                            std::to_string(getTotalMemory()) + " bytes");
-  }
-
-  // Allocate slot
-  int seq_id = next_seq_id_++;
-  slots_[slot_idx].seq_id = seq_id;
-  slots_[slot_idx].current_len = 0;
-  slots_[slot_idx].max_len = max_len;
-  slots_[slot_idx].active = true;
-
-  seq_to_slot_[seq_id] = slot_idx;
-
-  return Result<int>::ok(seq_id);
+    // Validate max_len
+    if (max_len <= 0 || max_len > config_.max_seq_len) {
+        return Result<int>::err("Invalid max_len: " + std::to_string(max_len) + " (must be 1-" +
+                                std::to_string(config_.max_seq_len) + ")");
+    }
+
+    // Find free slot
+    int slot_idx = findFreeSlot();
+    if (slot_idx < 0) {
+        return Result<int>::err("KV cache exhausted: no free slots available. "
+                                "Used: " +
+                                std::to_string(getUsedMemory()) +
+                                " bytes, "
+                                "Total: " +
+                                std::to_string(getTotalMemory()) + " bytes");
+    }
+
+    // Allocate slot
+    int seq_id = next_seq_id_++;
+    slots_[slot_idx].seq_id = seq_id;
+    slots_[slot_idx].current_len = 0;
+    slots_[slot_idx].max_len = max_len;
+    slots_[slot_idx].active = true;
+
+    seq_to_slot_[seq_id] = slot_idx;
+
+    return Result<int>::ok(seq_id);
 }
 
 Result<void> KVCacheManager::releaseSequence(int seq_id) {
-  auto it = seq_to_slot_.find(seq_id);
-  if (it == seq_to_slot_.end()) {
-    TLLM_WARN("releaseSequence: sequence not found: {}", seq_id);
-    return Result<void>::err("Sequence not found: " + std::to_string(seq_id));
-  }
+    auto it = seq_to_slot_.find(seq_id);
+    if (it == seq_to_slot_.end()) {
+        TLLM_WARN("releaseSequence: sequence not found: {}", seq_id);
+        return Result<void>::err("Sequence not found: " + std::to_string(seq_id));
+    }
 
-  int slot_idx = it->second;
-  slots_[slot_idx].active = false;
-  slots_[slot_idx].seq_id = -1;
-  slots_[slot_idx].current_len = 0;
+    int slot_idx = it->second;
+    slots_[slot_idx].active = false;
+    slots_[slot_idx].seq_id = -1;
+    slots_[slot_idx].current_len = 0;
 
-  seq_to_slot_.erase(it);
+    seq_to_slot_.erase(it);
 
-  TLLM_DEBUG("KVCache: released sequence {} (slot {})", seq_id, slot_idx);
-  return Result<void>::ok();
+    TLLM_DEBUG("KVCache: released sequence {} (slot {})", seq_id, slot_idx);
+    return Result<void>::ok();
 }
 
-Result<std::pair<half *, half *>>
-KVCacheManager::getCacheChecked(int seq_id, int layer_idx) {
-  auto it = seq_to_slot_.find(seq_id);
-  if (it == seq_to_slot_.end()) {
-    return Result<std::pair<half *, half *>>::err("Sequence not found: " +
-                                                   std::to_string(seq_id));
-  }
-
-  auto layer_result =
-      Validator::validateLayerIndex(layer_idx, config_.num_layers, "getCache");
-  if (layer_result.isErr()) {
-    return Result<std::pair<half *, half *>>::err(layer_result.error());
-  }
-
-  int slot_idx = it->second;
-  size_t k_offset = calculateOffset(slot_idx, layer_idx, false);
-  size_t v_offset = calculateOffset(slot_idx, layer_idx, true);
-
-  return Result<std::pair<half *, half *>>::ok(
-      {memory_pool_ + k_offset, memory_pool_ + v_offset});
+Result<std::pair<half *, half *>> KVCacheManager::getCacheChecked(int seq_id, int layer_idx) {
+    auto it = seq_to_slot_.find(seq_id);
+    if (it == seq_to_slot_.end()) {
+        return Result<std::pair<half *, half *>>::err("Sequence not found: " +
+                                                      std::to_string(seq_id));
+    }
+
+    auto layer_result = Validator::validateLayerIndex(layer_idx, config_.num_layers, "getCache");
+    if (layer_result.isErr()) {
+        return Result<std::pair<half *, half *>>::err(layer_result.error());
+    }
+
+    int    slot_idx = it->second;
+    size_t k_offset = calculateOffset(slot_idx, layer_idx, false);
+    size_t v_offset = calculateOffset(slot_idx, layer_idx, true);
+
+    return Result<std::pair<half *, half *>>::ok(
+        {memory_pool_ + k_offset, memory_pool_ + v_offset});
 }
 
 std::pair<half *, half *> KVCacheManager::getCache(int seq_id, int layer_idx) {
-  auto result = getCacheChecked(seq_id, layer_idx);
-  if (result.isErr()) {
-    TLLM_WARN("getCache: {}", result.error());
-    return {nullptr, nullptr};
-  }
-  return result.value();
+    auto result = getCacheChecked(seq_id, layer_idx);
+    if (result.isErr()) {
+        TLLM_WARN("getCache: {}", result.error());
+        return {nullptr, nullptr};
+    }
+    return result.value();
 }
 
 Result<void> KVCacheManager::appendKV(int seq_id, int layer_idx, const half *new_k,
-                                       const half *new_v, int num_tokens,
-                                       cudaStream_t stream) {
-  // Validate pointers
-  auto ptr_result = Validator::validateNotNull(new_k, "new_k");
-  if (ptr_result.isErr()) {
-    TLLM_ERROR("appendKV: {}", ptr_result.error());
-    return ptr_result;
-  }
-  ptr_result = Validator::validateNotNull(new_v, "new_v");
-  if (ptr_result.isErr()) {
-    TLLM_ERROR("appendKV: {}", ptr_result.error());
-    return ptr_result;
-  }
-
-  // Validate num_tokens
-  if (num_tokens <= 0) {
-    TLLM_ERROR("appendKV: invalid num_tokens: {}", num_tokens);
-    return Result<void>::err("appendKV: num_tokens must be positive: " +
-                              std::to_string(num_tokens));
-  }
-
-  // Validate layer index
-  auto layer_result =
-      Validator::validateLayerIndex(layer_idx, config_.num_layers, "appendKV");
-  if (layer_result.isErr()) {
-    TLLM_ERROR("{}", layer_result.error());
-    return layer_result;
-  }
-
-  // Find sequence
-  auto it = seq_to_slot_.find(seq_id);
-  if (it == seq_to_slot_.end()) {
-    TLLM_ERROR("appendKV: sequence not found: {}", seq_id);
-    return Result<void>::err("appendKV: sequence not found: " +
-                              std::to_string(seq_id));
-  }
-
-  int slot_idx = it->second;
-  auto &slot = slots_[slot_idx];
-
-  // Write position is always current_len — all layers see the same value
-  // because advanceSeqLen() is called ONCE after all layers have appended.
-  int write_pos = slot.current_len;
-
-  // Check if we have space
-  if (write_pos + num_tokens > slot.max_len) {
-    TLLM_ERROR("appendKV: cache overflow. seq_id={}, write_pos={}, num_tokens={}, max_len={}",
-               seq_id, write_pos, num_tokens, slot.max_len);
-    return Result<void>::err(
-        "appendKV: cache overflow. Current: " + std::to_string(write_pos) +
-        ", appending: " + std::to_string(num_tokens) +
-        ", max: " + std::to_string(slot.max_len));
-  }
-
-  // Calculate destination offsets
-  auto [k_cache, v_cache] = getCache(seq_id, layer_idx);
-  if (!k_cache || !v_cache) {
-    TLLM_ERROR("appendKV: failed to get cache pointers");
-    return Result<void>::err("appendKV: failed to get cache pointers");
-  }
-
-  size_t pos_offset =
-      static_cast<size_t>(write_pos) * config_.num_heads * config_.head_dim;
-  size_t copy_size = static_cast<size_t>(num_tokens) * config_.num_heads *
-                     config_.head_dim * sizeof(half);
-
-  CUDA_CHECK(cudaMemcpyAsync(k_cache + pos_offset, new_k, copy_size,
-                             cudaMemcpyDeviceToDevice, stream));
-  CUDA_CHECK(cudaMemcpyAsync(v_cache + pos_offset, new_v, copy_size,
-                             cudaMemcpyDeviceToDevice, stream));
-
-  TLLM_TRACE("appendKV: seq_id={}, layer={}, num_tokens={}, write_pos={}",
-             seq_id, layer_idx, num_tokens, write_pos);
-  return Result<void>::ok();
+                                      const half *new_v, int num_tokens, cudaStream_t stream) {
+    // Validate pointers
+    auto ptr_result = Validator::validateNotNull(new_k, "new_k");
+    if (ptr_result.isErr()) {
+        TLLM_ERROR("appendKV: {}", ptr_result.error());
+        return ptr_result;
+    }
+    ptr_result = Validator::validateNotNull(new_v, "new_v");
+    if (ptr_result.isErr()) {
+        TLLM_ERROR("appendKV: {}", ptr_result.error());
+        return ptr_result;
+    }
+
+    // Validate num_tokens
+    if (num_tokens <= 0) {
+        TLLM_ERROR("appendKV: invalid num_tokens: {}", num_tokens);
+        return Result<void>::err("appendKV: num_tokens must be positive: " +
+                                 std::to_string(num_tokens));
+    }
+
+    // Validate layer index
+    auto layer_result = Validator::validateLayerIndex(layer_idx, config_.num_layers, "appendKV");
+    if (layer_result.isErr()) {
+        TLLM_ERROR("{}", layer_result.error());
+        return layer_result;
+    }
+
+    // Find sequence
+    auto it = seq_to_slot_.find(seq_id);
+    if (it == seq_to_slot_.end()) {
+        TLLM_ERROR("appendKV: sequence not found: {}", seq_id);
+        return Result<void>::err("appendKV: sequence not found: " + std::to_string(seq_id));
+    }
+
+    int   slot_idx = it->second;
+    auto &slot = slots_[slot_idx];
+
+    // Write position is always current_len — all layers see the same value
+    // because advanceSeqLen() is called ONCE after all layers have appended.
+    int write_pos = slot.current_len;
+
+    // Check if we have space
+    if (write_pos + num_tokens > slot.max_len) {
+        TLLM_ERROR("appendKV: cache overflow. seq_id={}, write_pos={}, num_tokens={}, max_len={}",
+                   seq_id, write_pos, num_tokens, slot.max_len);
+        return Result<void>::err("appendKV: cache overflow. Current: " + std::to_string(write_pos) +
+                                 ", appending: " + std::to_string(num_tokens) +
+                                 ", max: " + std::to_string(slot.max_len));
+    }
+
+    // Calculate destination offsets
+    auto [k_cache, v_cache] = getCache(seq_id, layer_idx);
+    if (!k_cache || !v_cache) {
+        TLLM_ERROR("appendKV: failed to get cache pointers");
+        return Result<void>::err("appendKV: failed to get cache pointers");
+    }
+
+    size_t pos_offset = static_cast<size_t>(write_pos) * config_.num_heads * config_.head_dim;
+    size_t copy_size =
+        static_cast<size_t>(num_tokens) * config_.num_heads * config_.head_dim * sizeof(half);
+
+    CUDA_CHECK(
+        cudaMemcpyAsync(k_cache + pos_offset, new_k, copy_size, cudaMemcpyDeviceToDevice, stream));
+    CUDA_CHECK(
+        cudaMemcpyAsync(v_cache + pos_offset, new_v, copy_size, cudaMemcpyDeviceToDevice, stream));
+
+    TLLM_TRACE("appendKV: seq_id={}, layer={}, num_tokens={}, write_pos={}", seq_id, layer_idx,
+               num_tokens, write_pos);
+    return Result<void>::ok();
 }
 
 Result<void> KVCacheManager::advanceSeqLen(int seq_id, int num_tokens) {
-  if (num_tokens <= 0) {
-    TLLM_ERROR("advanceSeqLen: invalid num_tokens: {}", num_tokens);
-    return Result<void>::err("advanceSeqLen: num_tokens must be positive: " +
-                              std::to_string(num_tokens));
-  }
-
-  auto it = seq_to_slot_.find(seq_id);
-  if (it == seq_to_slot_.end()) {
-    TLLM_ERROR("advanceSeqLen: sequence not found: {}", seq_id);
-    return Result<void>::err("advanceSeqLen: sequence not found: " +
-                              std::to_string(seq_id));
-  }
-
-  auto &slot = slots_[it->second];
-  int old_len = slot.current_len;
-  slot.current_len = std::min(slot.current_len + num_tokens, slot.max_len);
-
-  TLLM_TRACE("advanceSeqLen: seq_id={}, {} -> {}", seq_id, old_len, slot.current_len);
-  return Result<void>::ok();
+    if (num_tokens <= 0) {
+        TLLM_ERROR("advanceSeqLen: invalid num_tokens: {}", num_tokens);
+        return Result<void>::err("advanceSeqLen: num_tokens must be positive: " +
+                                 std::to_string(num_tokens));
+    }
+
+    auto it = seq_to_slot_.find(seq_id);
+    if (it == seq_to_slot_.end()) {
+        TLLM_ERROR("advanceSeqLen: sequence not found: {}", seq_id);
+        return Result<void>::err("advanceSeqLen: sequence not found: " + std::to_string(seq_id));
+    }
+
+    auto &slot = slots_[it->second];
+    int   old_len = slot.current_len;
+    slot.current_len = std::min(slot.current_len + num_tokens, slot.max_len);
+
+    TLLM_TRACE("advanceSeqLen: seq_id={}, {} -> {}", seq_id, old_len, slot.current_len);
+    return Result<void>::ok();
 }
 
 int KVCacheManager::getSeqLen(int seq_id) const {
-  auto it = seq_to_slot_.find(seq_id);
-  if (it == seq_to_slot_.end()) {
-    return 0;
-  }
-  return slots_[it->second].current_len;
+    auto it = seq_to_slot_.find(seq_id);
+    if (it == seq_to_slot_.end()) {
+        return 0;
+    }
+    return slots_[it->second].current_len;
 }
 
 bool KVCacheManager::hasSequence(int seq_id) const {
-  return seq_to_slot_.find(seq_id) != seq_to_slot_.end();
+    return seq_to_slot_.find(seq_id) != seq_to_slot_.end();
 }
 
 size_t KVCacheManager::getUsedMemory() const {
-  int active_count = 0;
-  for (const auto &slot : slots_) {
-    if (slot.active) {
-      active_count++;
+    int active_count = 0;
+    for (const auto &slot : slots_) {
+        if (slot.active) {
+            active_count++;
+        }
     }
-  }
-  return active_count * slot_size_;
+    return active_count * slot_size_;
 }
 
 size_t KVCacheManager::getTotalMemory() const { return pool_size_; }
 
-size_t KVCacheManager::getFreeMemory() const {
-  return getTotalMemory() - getUsedMemory();
-}
+size_t KVCacheManager::getFreeMemory() const { return getTotalMemory() - getUsedMemory(); }
 
 int KVCacheManager::getActiveSequenceCount() const {
-  int count = 0;
-  for (const auto &slot : slots_) {
-    if (slot.active) {
-      count++;
+    int count = 0;
+    for (const auto &slot : slots_) {
+        if (slot.active) {
+            count++;
+        }
     }
-  }
-  return count;
+    return count;
 }
 
 } // namespace tiny_llm
diff --git a/src/logger.cpp b/src/logger.cpp
index d350949..f00cc02 100644
--- a/src/logger.cpp
+++ b/src/logger.cpp
@@ -10,86 +10,84 @@
 namespace tiny_llm {
 
 std::shared_ptr<spdlog::logger> Logger::logger_ = nullptr;
-bool Logger::initialized_ = false;
+bool                            Logger::initialized_ = false;
 
 void Logger::init(LogLevel level, const std::string &log_file, bool async) {
-  if (initialized_) {
-    return;
-  }
-
-  std::vector<spdlog::sink_ptr> sinks;
-
-  // Console sink (colorized)
-  auto console_sink = std::make_shared<spdlog::sinks::stdout_color_sink_mt>();
-  console_sink->set_pattern("[%Y-%m-%d %H:%M:%S.%e] [%^%l%$] [%t] %v");
-  sinks.push_back(console_sink);
-
-  // File sink (optional, rotating)
-  if (!log_file.empty()) {
-    // 10MB per file, keep 3 rotated files
-    auto file_sink = std::make_shared<spdlog::sinks::rotating_file_sink_mt>(
-        log_file, 1024 * 1024 * 10, 3);
-    file_sink->set_pattern("[%Y-%m-%d %H:%M:%S.%e] [%l] [%t] [%s:%#] %v");
-    sinks.push_back(file_sink);
-  }
-
-  // Create logger (async or sync)
-  if (async) {
-    // Initialize thread pool with 8192 queue size and 1 worker thread
-    spdlog::init_thread_pool(8192, 1);
-    logger_ = std::make_shared<spdlog::async_logger>(
-        "tiny_llm", sinks.begin(), sinks.end(), spdlog::thread_pool(),
-        spdlog::async_overflow_policy::block);
-  } else {
-    logger_ = std::make_shared<spdlog::logger>("tiny_llm", sinks.begin(),
-                                                sinks.end());
-  }
-
-  // Set log level
-  logger_->set_level(static_cast<spdlog::level::level_enum>(level));
-
-  // Auto-flush on warnings and above
-  logger_->flush_on(spdlog::level::warn);
-
-  // Register as default logger
-  spdlog::register_logger(logger_);
-  spdlog::set_default_logger(logger_);
-
-  initialized_ = true;
-
-  TLLM_DEBUG("Logger initialized: level={}, async={}, file={}",
-             static_cast<int>(level), async,
-             log_file.empty() ? "(console only)" : log_file);
+    if (initialized_) {
+        return;
+    }
+
+    std::vector<spdlog::sink_ptr> sinks;
+
+    // Console sink (colorized)
+    auto console_sink = std::make_shared<spdlog::sinks::stdout_color_sink_mt>();
+    console_sink->set_pattern("[%Y-%m-%d %H:%M:%S.%e] [%^%l%$] [%t] %v");
+    sinks.push_back(console_sink);
+
+    // File sink (optional, rotating)
+    if (!log_file.empty()) {
+        // 10MB per file, keep 3 rotated files
+        auto file_sink =
+            std::make_shared<spdlog::sinks::rotating_file_sink_mt>(log_file, 1024 * 1024 * 10, 3);
+        file_sink->set_pattern("[%Y-%m-%d %H:%M:%S.%e] [%l] [%t] [%s:%#] %v");
+        sinks.push_back(file_sink);
+    }
+
+    // Create logger (async or sync)
+    if (async) {
+        // Initialize thread pool with 8192 queue size and 1 worker thread
+        spdlog::init_thread_pool(8192, 1);
+        logger_ = std::make_shared<spdlog::async_logger>("tiny_llm", sinks.begin(), sinks.end(),
+                                                         spdlog::thread_pool(),
+                                                         spdlog::async_overflow_policy::block);
+    } else {
+        logger_ = std::make_shared<spdlog::logger>("tiny_llm", sinks.begin(), sinks.end());
+    }
+
+    // Set log level
+    logger_->set_level(static_cast<spdlog::level::level_enum>(level));
+
+    // Auto-flush on warnings and above
+    logger_->flush_on(spdlog::level::warn);
+
+    // Register as default logger
+    spdlog::register_logger(logger_);
+    spdlog::set_default_logger(logger_);
+
+    initialized_ = true;
+
+    TLLM_DEBUG("Logger initialized: level={}, async={}, file={}", static_cast<int>(level), async,
+               log_file.empty() ? "(console only)" : log_file);
 }
 
 void Logger::shutdown() {
-  if (initialized_) {
-    TLLM_DEBUG("Logger shutting down");
-    spdlog::shutdown();
-    logger_ = nullptr;
-    initialized_ = false;
-  }
+    if (initialized_) {
+        TLLM_DEBUG("Logger shutting down");
+        spdlog::shutdown();
+        logger_ = nullptr;
+        initialized_ = false;
+    }
 }
 
 std::shared_ptr<spdlog::logger> Logger::get() {
-  if (!initialized_) {
-    // Auto-initialize with defaults if not already done
-    init();
-  }
-  return logger_;
+    if (!initialized_) {
+        // Auto-initialize with defaults if not already done
+        init();
+    }
+    return logger_;
 }
 
 void Logger::setLevel(LogLevel level) {
-  if (logger_) {
-    logger_->set_level(static_cast<spdlog::level::level_enum>(level));
-    TLLM_DEBUG("Log level changed to {}", static_cast<int>(level));
-  }
+    if (logger_) {
+        logger_->set_level(static_cast<spdlog::level::level_enum>(level));
+        TLLM_DEBUG("Log level changed to {}", static_cast<int>(level));
+    }
 }
 
 void Logger::flush() {
-  if (logger_) {
-    logger_->flush();
-  }
+    if (logger_) {
+        logger_->flush();
+    }
 }
 
 } // namespace tiny_llm
diff --git a/src/main.cpp b/src/main.cpp
index 52f4db0..27d8b11 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -4,56 +4,59 @@
 #include <string>
 
 int main(int argc, char **argv) {
-  std::cout << "Tiny-LLM Inference Engine" << std::endl;
-  std::cout << "=========================" << std::endl;
-
-  // Check CUDA availability
-  int device_count = 0;
-  cudaError_t err = cudaGetDeviceCount(&device_count);
-
-  if (err != cudaSuccess || device_count == 0) {
-    std::cerr << "No CUDA devices found!" << std::endl;
-    return 1;
-  }
-
-  // Print device info
-  cudaDeviceProp prop;
-  err = cudaGetDeviceProperties(&prop, 0);
-  if (err != cudaSuccess) {
-    std::cerr << "Failed to get device properties: " << cudaGetErrorString(err) << std::endl;
-    return 1;
-  }
-
-  std::cout << "GPU: " << prop.name << std::endl;
-  std::cout << "Compute Capability: " << prop.major << "." << prop.minor
-            << std::endl;
-  std::cout << "Total Memory: " << prop.totalGlobalMem / (1024 * 1024) << " MB"
-            << std::endl;
-  std::cout << "SM Count: " << prop.multiProcessorCount << std::endl;
-
-  try {
-    auto mem_info = tiny_llm::getGPUMemoryInfo();
-    std::cout << "Free Memory: " << mem_info.free / (1024 * 1024) << " MB"
-              << std::endl;
-  } catch (const tiny_llm::CudaException &e) {
-    std::cerr << "CUDA Error: " << e.what() << std::endl;
-    return 1;
-  }
-
-  if (argc > 1) {
-    std::string model_path = argv[1];
-    if (model_path.size() >= 5 &&
-        model_path.substr(model_path.size() - 5) == ".gguf") {
-      std::cout << "\nRuntime note: GGUF parsing is partial and runtime GGUF loading is not supported yet." << std::endl;
-      std::cout << "Use the test binary format consumed by ModelLoader::loadBin() for end-to-end loading." << std::endl;
+    std::cout << "Tiny-LLM Inference Engine" << std::endl;
+    std::cout << "=========================" << std::endl;
+
+    // Check CUDA availability
+    int         device_count = 0;
+    cudaError_t err = cudaGetDeviceCount(&device_count);
+
+    if (err != cudaSuccess || device_count == 0) {
+        std::cerr << "No CUDA devices found!" << std::endl;
+        return 1;
+    }
+
+    // Print device info
+    cudaDeviceProp prop;
+    err = cudaGetDeviceProperties(&prop, 0);
+    if (err != cudaSuccess) {
+        std::cerr << "Failed to get device properties: " << cudaGetErrorString(err) << std::endl;
+        return 1;
+    }
+
+    std::cout << "GPU: " << prop.name << std::endl;
+    std::cout << "Compute Capability: " << prop.major << "." << prop.minor << std::endl;
+    std::cout << "Total Memory: " << prop.totalGlobalMem / (1024 * 1024) << " MB" << std::endl;
+    std::cout << "SM Count: " << prop.multiProcessorCount << std::endl;
+
+    try {
+        auto mem_info = tiny_llm::getGPUMemoryInfo();
+        std::cout << "Free Memory: " << mem_info.free / (1024 * 1024) << " MB" << std::endl;
+    } catch (const tiny_llm::CudaException &e) {
+        std::cerr << "CUDA Error: " << e.what() << std::endl;
+        return 1;
+    }
+
+    if (argc > 1) {
+        std::string model_path = argv[1];
+        if (model_path.size() >= 5 && model_path.substr(model_path.size() - 5) == ".gguf") {
+            std::cout << "\nRuntime note: GGUF parsing is partial and runtime GGUF loading is not "
+                         "supported yet."
+                      << std::endl;
+            std::cout << "Use the test binary format consumed by ModelLoader::loadBin() for "
+                         "end-to-end loading."
+                      << std::endl;
+        } else {
+            std::cout << "\nRuntime note: the demo binary currently reports CUDA readiness only."
+                      << std::endl;
+            std::cout << "Model execution still requires integrating a supported load/generate "
+                         "path in the demo."
+                      << std::endl;
+        }
     } else {
-      std::cout << "\nRuntime note: the demo binary currently reports CUDA readiness only." << std::endl;
-      std::cout << "Model execution still requires integrating a supported load/generate path in the demo." << std::endl;
+        std::cout << "\nThis demo currently reports CUDA readiness only." << std::endl;
+        std::cout << "Pass a model path to see supported format notes." << std::endl;
     }
-  } else {
-    std::cout << "\nThis demo currently reports CUDA readiness only." << std::endl;
-    std::cout << "Pass a model path to see supported format notes." << std::endl;
-  }
 
-  return 0;
+    return 0;
 }
diff --git a/src/model_loader.cpp b/src/model_loader.cpp
index b0c4731..5b02707 100644
--- a/src/model_loader.cpp
+++ b/src/model_loader.cpp
@@ -7,615 +7,608 @@
 
 namespace tiny_llm {
 
-Result<ModelWeights> ModelLoader::loadGGUF(const std::string &path,
-                                           ModelConfig &config) {
-  TLLM_INFO("Loading GGUF model from: {}", path);
-
-  // Use the new GGUFParser
-  GGUFParser parser(path);
-  auto parse_result = parser.parse();
-  if (parse_result.isErr()) {
-    TLLM_ERROR("Failed to parse GGUF: {}", parse_result.error());
-    return Result<ModelWeights>::err("Failed to parse GGUF: " +
-                                      parse_result.error());
-  }
-
-  // Extract model config
-  auto config_result = parser.extractModelConfig();
-  if (config_result.isErr()) {
-    TLLM_ERROR("Failed to extract model config: {}", config_result.error());
-    return Result<ModelWeights>::err("Failed to extract model config: " +
-                                      config_result.error());
-  }
-  config = config_result.value();
-
-  TLLM_INFO("Model config: hidden_dim={}, num_layers={}, vocab_size={}",
-            config.hidden_dim, config.num_layers, config.vocab_size);
-
-  const auto &tensors = parser.getTensors();
-  TLLM_DEBUG("Found {} tensors", tensors.size());
-
-  // Build tensor name map for quick lookup
-  std::unordered_map<std::string, const GGUFTensorInfo *> tensor_map;
-  for (const auto &t : tensors) {
-    tensor_map[t.name] = &t;
-  }
-
-  ModelWeights weights;
-  bool success = false;
-  auto cleanup_on_error = [&]() {
-    if (!success) {
-      freeWeights(weights);
+Result<ModelWeights> ModelLoader::loadGGUF(const std::string &path, ModelConfig &config) {
+    TLLM_INFO("Loading GGUF model from: {}", path);
+
+    // Use the new GGUFParser
+    GGUFParser parser(path);
+    auto       parse_result = parser.parse();
+    if (parse_result.isErr()) {
+        TLLM_ERROR("Failed to parse GGUF: {}", parse_result.error());
+        return Result<ModelWeights>::err("Failed to parse GGUF: " + parse_result.error());
     }
-  };
 
-  // Helper function to find tensor
-  auto find_tensor = [&](const std::string &name) -> const GGUFTensorInfo * {
-    auto it = tensor_map.find(name);
-    if (it != tensor_map.end()) {
-      return it->second;
-    }
-    return nullptr;
-  };
-
-  // Load token embedding
-  // GGUF naming: token_embd.weight
-  const GGUFTensorInfo *embed_tensor = find_tensor("token_embd.weight");
-  if (!embed_tensor) {
-    // Try alternative names
-    embed_tensor = find_tensor("tok_embeddings.weight");
-  }
-
-  if (embed_tensor) {
-    TLLM_DEBUG("Loading token embedding from tensor: {}", embed_tensor->name);
-    auto data_result = parser.readTensorData(*embed_tensor);
-    if (data_result.isErr()) {
-      cleanup_on_error();
-      return Result<ModelWeights>::err("Failed to read token embedding: " +
-                                        data_result.error());
+    // Extract model config
+    auto config_result = parser.extractModelConfig();
+    if (config_result.isErr()) {
+        TLLM_ERROR("Failed to extract model config: {}", config_result.error());
+        return Result<ModelWeights>::err("Failed to extract model config: " +
+                                         config_result.error());
     }
+    config = config_result.value();
 
-    size_t embed_size = static_cast<size_t>(config.vocab_size) * config.hidden_dim;
-    CUDA_CHECK(cudaMalloc(&weights.token_embedding, embed_size * sizeof(half)));
+    TLLM_INFO("Model config: hidden_dim={}, num_layers={}, vocab_size={}", config.hidden_dim,
+              config.num_layers, config.vocab_size);
 
-    // Convert to FP16 if needed
-    const auto &data = data_result.value();
-    if (embed_tensor->type == GGMLType::F16) {
-      CUDA_CHECK(cudaMemcpy(weights.token_embedding, data.data(),
-                            data.size(), cudaMemcpyHostToDevice));
-    } else if (embed_tensor->type == GGMLType::F32) {
-      // Convert F32 to F16
-      std::vector<half> f16_data(embed_size);
-      const float *f32_data = reinterpret_cast<const float *>(data.data());
-      for (size_t i = 0; i < embed_size; ++i) {
-        f16_data[i] = __float2half(f32_data[i]);
-      }
-      CUDA_CHECK(cudaMemcpy(weights.token_embedding, f16_data.data(),
-                            embed_size * sizeof(half), cudaMemcpyHostToDevice));
-    } else {
-      TLLM_WARN("Unsupported embedding type: {}, skipping", static_cast<int>(embed_tensor->type));
+    const auto &tensors = parser.getTensors();
+    TLLM_DEBUG("Found {} tensors", tensors.size());
+
+    // Build tensor name map for quick lookup
+    std::unordered_map<std::string, const GGUFTensorInfo *> tensor_map;
+    for (const auto &t : tensors) {
+        tensor_map[t.name] = &t;
     }
-  } else {
-    TLLM_WARN("Token embedding tensor not found, using zeros");
-    size_t embed_size = static_cast<size_t>(config.vocab_size) * config.hidden_dim;
-    CUDA_CHECK(cudaMalloc(&weights.token_embedding, embed_size * sizeof(half)));
-    CUDA_CHECK(cudaMemset(weights.token_embedding, 0, embed_size * sizeof(half)));
-  }
-
-  // Load layer weights
-  weights.layers.resize(config.num_layers);
-
-  for (int layer = 0; layer < config.num_layers; ++layer) {
-    auto &lw = weights.layers[layer];
-
-    // GGUF tensor naming convention:
-    // - blk.{N}.attn_q.weight
-    // - blk.{N}.attn_k.weight
-    // - blk.{N}.attn_v.weight
-    // - blk.{N}.attn_output.weight (or attn_out)
-    // - blk.{N}.ffn_gate.weight (w1)
-    // - blk.{N}.ffn_up.weight (w3)
-    // - blk.{N}.ffn_down.weight (w2)
-    // - blk.{N}.attn_norm.weight
-    // - blk.{N}.ffn_norm.weight
-
-    std::string layer_prefix = "blk." + std::to_string(layer) + ".";
-
-    // Alternative LLaMA naming
-    std::string llama_prefix = "layers." + std::to_string(layer) + ".";
-
-    auto find_layer_tensor = [&](const std::string &suffix) -> const GGUFTensorInfo * {
-      const GGUFTensorInfo *t = find_tensor(layer_prefix + suffix);
-      if (!t) {
-        t = find_tensor(llama_prefix + suffix);
-      }
-      return t;
+
+    ModelWeights weights;
+    bool         success = false;
+    auto         cleanup_on_error = [&]() {
+        if (!success) {
+            freeWeights(weights);
+        }
     };
 
-    // Load attention weights (Q, K, V, O)
-    // For now, load as FP16 placeholders (full quantization support would need conversion)
-    int hidden = config.hidden_dim;
-    int kv_dim = config.num_kv_heads * config.head_dim;
-
-    // Helper to allocate zero-initialized weight
-    auto alloc_zero_weight = [](int rows, int cols) -> QuantizedWeight {
-      QuantizedWeight qw;
-      qw.rows = rows;
-      qw.cols = cols;
-      qw.group_size = 128;
-      CUDA_CHECK(cudaMalloc(&qw.data, qw.weightElements() * sizeof(int8_t)));
-      CUDA_CHECK(cudaMalloc(&qw.scales, qw.scaleElements() * sizeof(half)));
-      CUDA_CHECK(cudaMemset(qw.data, 0, qw.weightElements() * sizeof(int8_t)));
-      CUDA_CHECK(cudaMemset(qw.scales, 0, qw.scaleElements() * sizeof(half)));
-      return qw;
+    // Helper function to find tensor
+    auto find_tensor = [&](const std::string &name) -> const GGUFTensorInfo * {
+        auto it = tensor_map.find(name);
+        if (it != tensor_map.end()) {
+            return it->second;
+        }
+        return nullptr;
     };
 
-    // Load Q weight
-    const GGUFTensorInfo *q_tensor = find_layer_tensor("attn_q.weight");
-    if (q_tensor) {
-      TLLM_TRACE("Loading Q weight from: {}", q_tensor->name);
-      // For now, allocate placeholder (full GGUF quantization support requires conversion)
-      lw.wq = alloc_zero_weight(hidden, hidden);
-    } else {
-      TLLM_WARN("Layer {} Q weight not found", layer);
-      lw.wq = alloc_zero_weight(hidden, hidden);
+    // Load token embedding
+    // GGUF naming: token_embd.weight
+    const GGUFTensorInfo *embed_tensor = find_tensor("token_embd.weight");
+    if (!embed_tensor) {
+        // Try alternative names
+        embed_tensor = find_tensor("tok_embeddings.weight");
     }
 
-    // Load K weight
-    const GGUFTensorInfo *k_tensor = find_layer_tensor("attn_k.weight");
-    if (k_tensor) {
-      TLLM_TRACE("Loading K weight from: {}", k_tensor->name);
-      lw.wk = alloc_zero_weight(hidden, kv_dim);
-    } else {
-      lw.wk = alloc_zero_weight(hidden, kv_dim);
-    }
+    if (embed_tensor) {
+        TLLM_DEBUG("Loading token embedding from tensor: {}", embed_tensor->name);
+        auto data_result = parser.readTensorData(*embed_tensor);
+        if (data_result.isErr()) {
+            cleanup_on_error();
+            return Result<ModelWeights>::err("Failed to read token embedding: " +
+                                             data_result.error());
+        }
 
-    // Load V weight
-    const GGUFTensorInfo *v_tensor = find_layer_tensor("attn_v.weight");
-    if (v_tensor) {
-      TLLM_TRACE("Loading V weight from: {}", v_tensor->name);
-      lw.wv = alloc_zero_weight(hidden, kv_dim);
+        size_t embed_size = static_cast<size_t>(config.vocab_size) * config.hidden_dim;
+        CUDA_CHECK(cudaMalloc(&weights.token_embedding, embed_size * sizeof(half)));
+
+        // Convert to FP16 if needed
+        const auto &data = data_result.value();
+        if (embed_tensor->type == GGMLType::F16) {
+            CUDA_CHECK(cudaMemcpy(weights.token_embedding, data.data(), data.size(),
+                                  cudaMemcpyHostToDevice));
+        } else if (embed_tensor->type == GGMLType::F32) {
+            // Convert F32 to F16
+            std::vector<half> f16_data(embed_size);
+            const float      *f32_data = reinterpret_cast<const float *>(data.data());
+            for (size_t i = 0; i < embed_size; ++i) {
+                f16_data[i] = __float2half(f32_data[i]);
+            }
+            CUDA_CHECK(cudaMemcpy(weights.token_embedding, f16_data.data(),
+                                  embed_size * sizeof(half), cudaMemcpyHostToDevice));
+        } else {
+            TLLM_WARN("Unsupported embedding type: {}, skipping",
+                      static_cast<int>(embed_tensor->type));
+        }
     } else {
-      lw.wv = alloc_zero_weight(hidden, kv_dim);
+        TLLM_WARN("Token embedding tensor not found, using zeros");
+        size_t embed_size = static_cast<size_t>(config.vocab_size) * config.hidden_dim;
+        CUDA_CHECK(cudaMalloc(&weights.token_embedding, embed_size * sizeof(half)));
+        CUDA_CHECK(cudaMemset(weights.token_embedding, 0, embed_size * sizeof(half)));
     }
 
-    // Load O weight
-    const GGUFTensorInfo *o_tensor = find_layer_tensor("attn_output.weight");
-    if (!o_tensor) {
-      o_tensor = find_layer_tensor("attn_out.weight");
-    }
-    if (o_tensor) {
-      TLLM_TRACE("Loading O weight from: {}", o_tensor->name);
-      lw.wo = alloc_zero_weight(hidden, hidden);
-    } else {
-      lw.wo = alloc_zero_weight(hidden, hidden);
-    }
+    // Load layer weights
+    weights.layers.resize(config.num_layers);
+
+    for (int layer = 0; layer < config.num_layers; ++layer) {
+        auto &lw = weights.layers[layer];
+
+        // GGUF tensor naming convention:
+        // - blk.{N}.attn_q.weight
+        // - blk.{N}.attn_k.weight
+        // - blk.{N}.attn_v.weight
+        // - blk.{N}.attn_output.weight (or attn_out)
+        // - blk.{N}.ffn_gate.weight (w1)
+        // - blk.{N}.ffn_up.weight (w3)
+        // - blk.{N}.ffn_down.weight (w2)
+        // - blk.{N}.attn_norm.weight
+        // - blk.{N}.ffn_norm.weight
+
+        std::string layer_prefix = "blk." + std::to_string(layer) + ".";
+
+        // Alternative LLaMA naming
+        std::string llama_prefix = "layers." + std::to_string(layer) + ".";
+
+        auto find_layer_tensor = [&](const std::string &suffix) -> const GGUFTensorInfo * {
+            const GGUFTensorInfo *t = find_tensor(layer_prefix + suffix);
+            if (!t) {
+                t = find_tensor(llama_prefix + suffix);
+            }
+            return t;
+        };
+
+        // Load attention weights (Q, K, V, O)
+        // For now, load as FP16 placeholders (full quantization support would need conversion)
+        int hidden = config.hidden_dim;
+        int kv_dim = config.num_kv_heads * config.head_dim;
+
+        // Helper to allocate zero-initialized weight
+        auto alloc_zero_weight = [](int rows, int cols) -> QuantizedWeight {
+            QuantizedWeight qw;
+            qw.rows = rows;
+            qw.cols = cols;
+            qw.group_size = 128;
+            CUDA_CHECK(cudaMalloc(&qw.data, qw.weightElements() * sizeof(int8_t)));
+            CUDA_CHECK(cudaMalloc(&qw.scales, qw.scaleElements() * sizeof(half)));
+            CUDA_CHECK(cudaMemset(qw.data, 0, qw.weightElements() * sizeof(int8_t)));
+            CUDA_CHECK(cudaMemset(qw.scales, 0, qw.scaleElements() * sizeof(half)));
+            return qw;
+        };
+
+        // Load Q weight
+        const GGUFTensorInfo *q_tensor = find_layer_tensor("attn_q.weight");
+        if (q_tensor) {
+            TLLM_TRACE("Loading Q weight from: {}", q_tensor->name);
+            // For now, allocate placeholder (full GGUF quantization support requires conversion)
+            lw.wq = alloc_zero_weight(hidden, hidden);
+        } else {
+            TLLM_WARN("Layer {} Q weight not found", layer);
+            lw.wq = alloc_zero_weight(hidden, hidden);
+        }
 
-    // Load FFN weights
-    const GGUFTensorInfo *w1_tensor = find_layer_tensor("ffn_gate.weight");
-    const GGUFTensorInfo *w2_tensor = find_layer_tensor("ffn_down.weight");
-    const GGUFTensorInfo *w3_tensor = find_layer_tensor("ffn_up.weight");
-    int inter = config.intermediate_dim;
+        // Load K weight
+        const GGUFTensorInfo *k_tensor = find_layer_tensor("attn_k.weight");
+        if (k_tensor) {
+            TLLM_TRACE("Loading K weight from: {}", k_tensor->name);
+            lw.wk = alloc_zero_weight(hidden, kv_dim);
+        } else {
+            lw.wk = alloc_zero_weight(hidden, kv_dim);
+        }
 
-    if (w1_tensor) {
-      TLLM_TRACE("Loading w1 (gate) weight from: {}", w1_tensor->name);
-    }
-    if (w2_tensor) {
-      TLLM_TRACE("Loading w2 (down) weight from: {}", w2_tensor->name);
-    }
-    if (w3_tensor) {
-      TLLM_TRACE("Loading w3 (up) weight from: {}", w3_tensor->name);
-    }
+        // Load V weight
+        const GGUFTensorInfo *v_tensor = find_layer_tensor("attn_v.weight");
+        if (v_tensor) {
+            TLLM_TRACE("Loading V weight from: {}", v_tensor->name);
+            lw.wv = alloc_zero_weight(hidden, kv_dim);
+        } else {
+            lw.wv = alloc_zero_weight(hidden, kv_dim);
+        }
+
+        // Load O weight
+        const GGUFTensorInfo *o_tensor = find_layer_tensor("attn_output.weight");
+        if (!o_tensor) {
+            o_tensor = find_layer_tensor("attn_out.weight");
+        }
+        if (o_tensor) {
+            TLLM_TRACE("Loading O weight from: {}", o_tensor->name);
+            lw.wo = alloc_zero_weight(hidden, hidden);
+        } else {
+            lw.wo = alloc_zero_weight(hidden, hidden);
+        }
 
-    lw.w1 = alloc_zero_weight(hidden, inter);
-    lw.w2 = alloc_zero_weight(inter, hidden);
-    lw.w3 = alloc_zero_weight(hidden, inter);
+        // Load FFN weights
+        const GGUFTensorInfo *w1_tensor = find_layer_tensor("ffn_gate.weight");
+        const GGUFTensorInfo *w2_tensor = find_layer_tensor("ffn_down.weight");
+        const GGUFTensorInfo *w3_tensor = find_layer_tensor("ffn_up.weight");
+        int                   inter = config.intermediate_dim;
 
-    // Load normalization weights
-    const GGUFTensorInfo *attn_norm = find_layer_tensor("attn_norm.weight");
-    if (attn_norm) {
-      auto data_result = parser.readTensorData(*attn_norm);
-      if (data_result.isOk()) {
-        CUDA_CHECK(cudaMalloc(&lw.rms_att_weight, hidden * sizeof(half)));
-        // Convert if needed
-        if (attn_norm->type == GGMLType::F32) {
-          std::vector<half> f16(hidden);
-          const float *f32 = reinterpret_cast<const float *>(data_result.value().data());
-          for (int i = 0; i < hidden; ++i) {
-            f16[i] = __float2half(f32[i]);
-          }
-          CUDA_CHECK(cudaMemcpy(lw.rms_att_weight, f16.data(),
-                                hidden * sizeof(half), cudaMemcpyHostToDevice));
+        if (w1_tensor) {
+            TLLM_TRACE("Loading w1 (gate) weight from: {}", w1_tensor->name);
+        }
+        if (w2_tensor) {
+            TLLM_TRACE("Loading w2 (down) weight from: {}", w2_tensor->name);
+        }
+        if (w3_tensor) {
+            TLLM_TRACE("Loading w3 (up) weight from: {}", w3_tensor->name);
+        }
+
+        lw.w1 = alloc_zero_weight(hidden, inter);
+        lw.w2 = alloc_zero_weight(inter, hidden);
+        lw.w3 = alloc_zero_weight(hidden, inter);
+
+        // Load normalization weights
+        const GGUFTensorInfo *attn_norm = find_layer_tensor("attn_norm.weight");
+        if (attn_norm) {
+            auto data_result = parser.readTensorData(*attn_norm);
+            if (data_result.isOk()) {
+                CUDA_CHECK(cudaMalloc(&lw.rms_att_weight, hidden * sizeof(half)));
+                // Convert if needed
+                if (attn_norm->type == GGMLType::F32) {
+                    std::vector<half> f16(hidden);
+                    const float *f32 = reinterpret_cast<const float *>(data_result.value().data());
+                    for (int i = 0; i < hidden; ++i) {
+                        f16[i] = __float2half(f32[i]);
+                    }
+                    CUDA_CHECK(cudaMemcpy(lw.rms_att_weight, f16.data(), hidden * sizeof(half),
+                                          cudaMemcpyHostToDevice));
+                } else {
+                    CUDA_CHECK(cudaMemcpy(lw.rms_att_weight, data_result.value().data(),
+                                          hidden * sizeof(half), cudaMemcpyHostToDevice));
+                }
+            }
         } else {
-          CUDA_CHECK(cudaMemcpy(lw.rms_att_weight, data_result.value().data(),
-                                hidden * sizeof(half), cudaMemcpyHostToDevice));
+            TLLM_WARN("Layer {} attention norm not found", layer);
+            CUDA_CHECK(cudaMalloc(&lw.rms_att_weight, hidden * sizeof(half)));
+            CUDA_CHECK(cudaMemset(lw.rms_att_weight, 0, hidden * sizeof(half)));
         }
-      }
-    } else {
-      TLLM_WARN("Layer {} attention norm not found", layer);
-      CUDA_CHECK(cudaMalloc(&lw.rms_att_weight, hidden * sizeof(half)));
-      CUDA_CHECK(cudaMemset(lw.rms_att_weight, 0, hidden * sizeof(half)));
-    }
 
-    const GGUFTensorInfo *ffn_norm = find_layer_tensor("ffn_norm.weight");
-    if (ffn_norm) {
-      auto data_result = parser.readTensorData(*ffn_norm);
-      if (data_result.isOk()) {
-        CUDA_CHECK(cudaMalloc(&lw.rms_ffn_weight, hidden * sizeof(half)));
-        if (ffn_norm->type == GGMLType::F32) {
-          std::vector<half> f16(hidden);
-          const float *f32 = reinterpret_cast<const float *>(data_result.value().data());
-          for (int i = 0; i < hidden; ++i) {
-            f16[i] = __float2half(f32[i]);
-          }
-          CUDA_CHECK(cudaMemcpy(lw.rms_ffn_weight, f16.data(),
-                                hidden * sizeof(half), cudaMemcpyHostToDevice));
+        const GGUFTensorInfo *ffn_norm = find_layer_tensor("ffn_norm.weight");
+        if (ffn_norm) {
+            auto data_result = parser.readTensorData(*ffn_norm);
+            if (data_result.isOk()) {
+                CUDA_CHECK(cudaMalloc(&lw.rms_ffn_weight, hidden * sizeof(half)));
+                if (ffn_norm->type == GGMLType::F32) {
+                    std::vector<half> f16(hidden);
+                    const float *f32 = reinterpret_cast<const float *>(data_result.value().data());
+                    for (int i = 0; i < hidden; ++i) {
+                        f16[i] = __float2half(f32[i]);
+                    }
+                    CUDA_CHECK(cudaMemcpy(lw.rms_ffn_weight, f16.data(), hidden * sizeof(half),
+                                          cudaMemcpyHostToDevice));
+                } else {
+                    CUDA_CHECK(cudaMemcpy(lw.rms_ffn_weight, data_result.value().data(),
+                                          hidden * sizeof(half), cudaMemcpyHostToDevice));
+                }
+            }
         } else {
-          CUDA_CHECK(cudaMemcpy(lw.rms_ffn_weight, data_result.value().data(),
-                                hidden * sizeof(half), cudaMemcpyHostToDevice));
+            TLLM_WARN("Layer {} FFN norm not found", layer);
+            CUDA_CHECK(cudaMalloc(&lw.rms_ffn_weight, hidden * sizeof(half)));
+            CUDA_CHECK(cudaMemset(lw.rms_ffn_weight, 0, hidden * sizeof(half)));
         }
-      }
-    } else {
-      TLLM_WARN("Layer {} FFN norm not found", layer);
-      CUDA_CHECK(cudaMalloc(&lw.rms_ffn_weight, hidden * sizeof(half)));
-      CUDA_CHECK(cudaMemset(lw.rms_ffn_weight, 0, hidden * sizeof(half)));
+
+        TLLM_TRACE("Loaded layer {}/{}", layer + 1, config.num_layers);
     }
 
-    TLLM_TRACE("Loaded layer {}/{}", layer + 1, config.num_layers);
-  }
-
-  // Load final norm
-  const GGUFTensorInfo *output_norm = find_tensor("output_norm.weight");
-  if (!output_norm) {
-    output_norm = find_tensor("norm.weight");
-  }
-  if (output_norm) {
-    TLLM_DEBUG("Loading final norm from: {}", output_norm->name);
-    auto data_result = parser.readTensorData(*output_norm);
-    if (data_result.isOk()) {
-      CUDA_CHECK(cudaMalloc(&weights.final_norm_weight, config.hidden_dim * sizeof(half)));
-      if (output_norm->type == GGMLType::F32) {
-        std::vector<half> f16(config.hidden_dim);
-        const float *f32 = reinterpret_cast<const float *>(data_result.value().data());
-        for (int i = 0; i < config.hidden_dim; ++i) {
-          f16[i] = __float2half(f32[i]);
+    // Load final norm
+    const GGUFTensorInfo *output_norm = find_tensor("output_norm.weight");
+    if (!output_norm) {
+        output_norm = find_tensor("norm.weight");
+    }
+    if (output_norm) {
+        TLLM_DEBUG("Loading final norm from: {}", output_norm->name);
+        auto data_result = parser.readTensorData(*output_norm);
+        if (data_result.isOk()) {
+            CUDA_CHECK(cudaMalloc(&weights.final_norm_weight, config.hidden_dim * sizeof(half)));
+            if (output_norm->type == GGMLType::F32) {
+                std::vector<half> f16(config.hidden_dim);
+                const float      *f32 = reinterpret_cast<const float *>(data_result.value().data());
+                for (int i = 0; i < config.hidden_dim; ++i) {
+                    f16[i] = __float2half(f32[i]);
+                }
+                CUDA_CHECK(cudaMemcpy(weights.final_norm_weight, f16.data(),
+                                      config.hidden_dim * sizeof(half), cudaMemcpyHostToDevice));
+            } else {
+                CUDA_CHECK(cudaMemcpy(weights.final_norm_weight, data_result.value().data(),
+                                      config.hidden_dim * sizeof(half), cudaMemcpyHostToDevice));
+            }
         }
-        CUDA_CHECK(cudaMemcpy(weights.final_norm_weight, f16.data(),
-                              config.hidden_dim * sizeof(half), cudaMemcpyHostToDevice));
-      } else {
-        CUDA_CHECK(cudaMemcpy(weights.final_norm_weight, data_result.value().data(),
-                              config.hidden_dim * sizeof(half), cudaMemcpyHostToDevice));
-      }
+    } else {
+        TLLM_WARN("Output norm not found");
+        CUDA_CHECK(cudaMalloc(&weights.final_norm_weight, config.hidden_dim * sizeof(half)));
+        CUDA_CHECK(cudaMemset(weights.final_norm_weight, 0, config.hidden_dim * sizeof(half)));
     }
-  } else {
-    TLLM_WARN("Output norm not found");
-    CUDA_CHECK(cudaMalloc(&weights.final_norm_weight, config.hidden_dim * sizeof(half)));
-    CUDA_CHECK(cudaMemset(weights.final_norm_weight, 0, config.hidden_dim * sizeof(half)));
-  }
-
-  // Load LM head
-  const GGUFTensorInfo *lm_head = find_tensor("output.weight");
-  if (!lm_head) {
-    lm_head = find_tensor("lm_head.weight");
-  }
-  if (lm_head) {
-    TLLM_DEBUG("Loading LM head from: {}", lm_head->name);
-    // For now, allocate placeholder (full support needs quantization conversion)
-    weights.lm_head.rows = config.hidden_dim;
-    weights.lm_head.cols = config.vocab_size;
-    weights.lm_head.group_size = 128;
-    CUDA_CHECK(cudaMalloc(&weights.lm_head.data, weights.lm_head.weightElements() * sizeof(int8_t)));
-    CUDA_CHECK(cudaMalloc(&weights.lm_head.scales, weights.lm_head.scaleElements() * sizeof(half)));
-    CUDA_CHECK(cudaMemset(weights.lm_head.data, 0, weights.lm_head.weightElements() * sizeof(int8_t)));
-    CUDA_CHECK(cudaMemset(weights.lm_head.scales, 0, weights.lm_head.scaleElements() * sizeof(half)));
-  } else {
-    TLLM_WARN("LM head tensor not found");
-    weights.lm_head.rows = config.hidden_dim;
-    weights.lm_head.cols = config.vocab_size;
-    weights.lm_head.group_size = 128;
-    CUDA_CHECK(cudaMalloc(&weights.lm_head.data, weights.lm_head.weightElements() * sizeof(int8_t)));
-    CUDA_CHECK(cudaMalloc(&weights.lm_head.scales, weights.lm_head.scaleElements() * sizeof(half)));
-    CUDA_CHECK(cudaMemset(weights.lm_head.data, 0, weights.lm_head.weightElements() * sizeof(int8_t)));
-    CUDA_CHECK(cudaMemset(weights.lm_head.scales, 0, weights.lm_head.scaleElements() * sizeof(half)));
-  }
-
-  success = true;
-  TLLM_INFO("GGUF model loaded successfully");
-
-  return Result<ModelWeights>::ok(std::move(weights));
-}
 
-Result<ModelWeights> ModelLoader::loadBin(const std::string &path,
-                                          const ModelConfig &config) {
-  std::ifstream file(path, std::ios::binary);
-  if (!file) {
-    return Result<ModelWeights>::err("Failed to open file: " + path);
-  }
-
-  // Read and validate header
-  BinHeader header;
-  file.read(reinterpret_cast<char *>(&header.magic), sizeof(header.magic));
-  if (!file) {
-    return Result<ModelWeights>::err("Failed to read binary header magic");
-  }
-
-  if (header.magic != BIN_MAGIC) {
-    return Result<ModelWeights>::err(
-        "Invalid binary magic number: expected 0x" + std::to_string(BIN_MAGIC) +
-        ", got 0x" + std::to_string(header.magic));
-  }
-
-  file.read(reinterpret_cast<char *>(&header.version), sizeof(header.version));
-  if (!file) {
-    return Result<ModelWeights>::err("Failed to read binary version");
-  }
-
-  if (header.version != BIN_VERSION) {
-    return Result<ModelWeights>::err("Unsupported binary version: " +
-                                     std::to_string(header.version));
-  }
-
-  // Read stored config
-  file.read(reinterpret_cast<char *>(&header.config), sizeof(header.config));
-  if (!file) {
-    return Result<ModelWeights>::err("Failed to read model config");
-  }
-
-  // Validate dimensions match
-  if (header.config.hidden_dim != config.hidden_dim ||
-      header.config.num_layers != config.num_layers ||
-      header.config.vocab_size != config.vocab_size) {
-    return Result<ModelWeights>::err(
-        "Model config mismatch: expected hidden_dim=" +
-        std::to_string(config.hidden_dim) +
-        ", num_layers=" + std::to_string(config.num_layers) +
-        ", vocab_size=" + std::to_string(config.vocab_size) +
-        ", got hidden_dim=" + std::to_string(header.config.hidden_dim) +
-        ", num_layers=" + std::to_string(header.config.num_layers) +
-        ", vocab_size=" + std::to_string(header.config.vocab_size));
-  }
-
-  ModelWeights weights;
-  bool success = false;
-  auto cleanup_on_error = [&]() {
-    if (!success) {
-      freeWeights(weights);
+    // Load LM head
+    const GGUFTensorInfo *lm_head = find_tensor("output.weight");
+    if (!lm_head) {
+        lm_head = find_tensor("lm_head.weight");
     }
-  };
-
-  // Read token embedding [vocab_size, hidden_dim] as FP16
-  size_t embed_size =
-      static_cast<size_t>(config.vocab_size) * config.hidden_dim;
-  std::vector<half> embed_host(embed_size);
-  file.read(reinterpret_cast<char *>(embed_host.data()),
-            embed_size * sizeof(half));
-  if (!file) {
-    cleanup_on_error();
-    return Result<ModelWeights>::err("Failed to read token embedding");
-  }
-
-  // Allocate and transfer embedding to GPU
-  CUDA_CHECK(cudaMalloc(&weights.token_embedding, embed_size * sizeof(half)));
-  CUDA_CHECK(cudaMemcpy(weights.token_embedding, embed_host.data(),
-                        embed_size * sizeof(half), cudaMemcpyHostToDevice));
-
-  // Read layer weights
-  weights.layers.resize(config.num_layers);
-  int group_size = 128; // Default group size
-
-  for (int layer = 0; layer < config.num_layers; ++layer) {
-    auto &lw = weights.layers[layer];
-
-    // Read attention weights
-    auto load_qweight = [&](QuantizedWeight &qw, int rows,
-                            int cols) -> Result<void> {
-      auto result = loadQuantizedTensor(file, rows, cols, group_size);
-      if (result.isErr()) {
-        return Result<void>::err(result.error());
-      }
-      qw = result.value();
-      return Result<void>::ok();
-    };
+    if (lm_head) {
+        TLLM_DEBUG("Loading LM head from: {}", lm_head->name);
+        // For now, allocate placeholder (full support needs quantization conversion)
+        weights.lm_head.rows = config.hidden_dim;
+        weights.lm_head.cols = config.vocab_size;
+        weights.lm_head.group_size = 128;
+        CUDA_CHECK(
+            cudaMalloc(&weights.lm_head.data, weights.lm_head.weightElements() * sizeof(int8_t)));
+        CUDA_CHECK(
+            cudaMalloc(&weights.lm_head.scales, weights.lm_head.scaleElements() * sizeof(half)));
+        CUDA_CHECK(
+            cudaMemset(weights.lm_head.data, 0, weights.lm_head.weightElements() * sizeof(int8_t)));
+        CUDA_CHECK(
+            cudaMemset(weights.lm_head.scales, 0, weights.lm_head.scaleElements() * sizeof(half)));
+    } else {
+        TLLM_WARN("LM head tensor not found");
+        weights.lm_head.rows = config.hidden_dim;
+        weights.lm_head.cols = config.vocab_size;
+        weights.lm_head.group_size = 128;
+        CUDA_CHECK(
+            cudaMalloc(&weights.lm_head.data, weights.lm_head.weightElements() * sizeof(int8_t)));
+        CUDA_CHECK(
+            cudaMalloc(&weights.lm_head.scales, weights.lm_head.scaleElements() * sizeof(half)));
+        CUDA_CHECK(
+            cudaMemset(weights.lm_head.data, 0, weights.lm_head.weightElements() * sizeof(int8_t)));
+        CUDA_CHECK(
+            cudaMemset(weights.lm_head.scales, 0, weights.lm_head.scaleElements() * sizeof(half)));
+    }
+
+    success = true;
+    TLLM_INFO("GGUF model loaded successfully");
 
-    int hidden = config.hidden_dim;
-    int kv_dim = config.num_kv_heads * config.head_dim;
-    int inter = config.intermediate_dim;
+    return Result<ModelWeights>::ok(std::move(weights));
+}
 
-    // Q, K, V, O projections
-    auto r = load_qweight(lw.wq, hidden, hidden);
-    if (r.isErr()) {
-      cleanup_on_error();
-      return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
-                                       " wq: " + r.error());
+Result<ModelWeights> ModelLoader::loadBin(const std::string &path, const ModelConfig &config) {
+    std::ifstream file(path, std::ios::binary);
+    if (!file) {
+        return Result<ModelWeights>::err("Failed to open file: " + path);
     }
 
-    r = load_qweight(lw.wk, hidden, kv_dim);
-    if (r.isErr()) {
-      cleanup_on_error();
-      return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
-                                       " wk: " + r.error());
+    // Read and validate header
+    BinHeader header;
+    file.read(reinterpret_cast<char *>(&header.magic), sizeof(header.magic));
+    if (!file) {
+        return Result<ModelWeights>::err("Failed to read binary header magic");
     }
 
-    r = load_qweight(lw.wv, hidden, kv_dim);
-    if (r.isErr()) {
-      cleanup_on_error();
-      return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
-                                       " wv: " + r.error());
+    if (header.magic != BIN_MAGIC) {
+        return Result<ModelWeights>::err("Invalid binary magic number: expected 0x" +
+                                         std::to_string(BIN_MAGIC) + ", got 0x" +
+                                         std::to_string(header.magic));
     }
 
-    r = load_qweight(lw.wo, hidden, hidden);
-    if (r.isErr()) {
-      cleanup_on_error();
-      return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
-                                       " wo: " + r.error());
+    file.read(reinterpret_cast<char *>(&header.version), sizeof(header.version));
+    if (!file) {
+        return Result<ModelWeights>::err("Failed to read binary version");
     }
 
-    // FFN weights
-    r = load_qweight(lw.w1, hidden, inter);
-    if (r.isErr()) {
-      cleanup_on_error();
-      return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
-                                       " w1: " + r.error());
+    if (header.version != BIN_VERSION) {
+        return Result<ModelWeights>::err("Unsupported binary version: " +
+                                         std::to_string(header.version));
     }
 
-    r = load_qweight(lw.w2, inter, hidden);
-    if (r.isErr()) {
-      cleanup_on_error();
-      return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
-                                       " w2: " + r.error());
+    // Read stored config
+    file.read(reinterpret_cast<char *>(&header.config), sizeof(header.config));
+    if (!file) {
+        return Result<ModelWeights>::err("Failed to read model config");
     }
 
-    r = load_qweight(lw.w3, hidden, inter);
-    if (r.isErr()) {
-      cleanup_on_error();
-      return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
-                                       " w3: " + r.error());
+    // Validate dimensions match
+    if (header.config.hidden_dim != config.hidden_dim ||
+        header.config.num_layers != config.num_layers ||
+        header.config.vocab_size != config.vocab_size) {
+        return Result<ModelWeights>::err(
+            "Model config mismatch: expected hidden_dim=" + std::to_string(config.hidden_dim) +
+            ", num_layers=" + std::to_string(config.num_layers) +
+            ", vocab_size=" + std::to_string(config.vocab_size) +
+            ", got hidden_dim=" + std::to_string(header.config.hidden_dim) +
+            ", num_layers=" + std::to_string(header.config.num_layers) +
+            ", vocab_size=" + std::to_string(header.config.vocab_size));
     }
 
-    // RMSNorm weights (FP16)
-    std::vector<half> norm_host(hidden);
+    ModelWeights weights;
+    bool         success = false;
+    auto         cleanup_on_error = [&]() {
+        if (!success) {
+            freeWeights(weights);
+        }
+    };
 
-    file.read(reinterpret_cast<char *>(norm_host.data()),
-              hidden * sizeof(half));
+    // Read token embedding [vocab_size, hidden_dim] as FP16
+    size_t            embed_size = static_cast<size_t>(config.vocab_size) * config.hidden_dim;
+    std::vector<half> embed_host(embed_size);
+    file.read(reinterpret_cast<char *>(embed_host.data()), embed_size * sizeof(half));
     if (!file) {
-      cleanup_on_error();
-      return Result<ModelWeights>::err(
-          "Failed to read rms_att_weight for layer " + std::to_string(layer));
+        cleanup_on_error();
+        return Result<ModelWeights>::err("Failed to read token embedding");
+    }
+
+    // Allocate and transfer embedding to GPU
+    CUDA_CHECK(cudaMalloc(&weights.token_embedding, embed_size * sizeof(half)));
+    CUDA_CHECK(cudaMemcpy(weights.token_embedding, embed_host.data(), embed_size * sizeof(half),
+                          cudaMemcpyHostToDevice));
+
+    // Read layer weights
+    weights.layers.resize(config.num_layers);
+    int group_size = 128; // Default group size
+
+    for (int layer = 0; layer < config.num_layers; ++layer) {
+        auto &lw = weights.layers[layer];
+
+        // Read attention weights
+        auto load_qweight = [&](QuantizedWeight &qw, int rows, int cols) -> Result<void> {
+            auto result = loadQuantizedTensor(file, rows, cols, group_size);
+            if (result.isErr()) {
+                return Result<void>::err(result.error());
+            }
+            qw = result.value();
+            return Result<void>::ok();
+        };
+
+        int hidden = config.hidden_dim;
+        int kv_dim = config.num_kv_heads * config.head_dim;
+        int inter = config.intermediate_dim;
+
+        // Q, K, V, O projections
+        auto r = load_qweight(lw.wq, hidden, hidden);
+        if (r.isErr()) {
+            cleanup_on_error();
+            return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
+                                             " wq: " + r.error());
+        }
+
+        r = load_qweight(lw.wk, hidden, kv_dim);
+        if (r.isErr()) {
+            cleanup_on_error();
+            return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
+                                             " wk: " + r.error());
+        }
+
+        r = load_qweight(lw.wv, hidden, kv_dim);
+        if (r.isErr()) {
+            cleanup_on_error();
+            return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
+                                             " wv: " + r.error());
+        }
+
+        r = load_qweight(lw.wo, hidden, hidden);
+        if (r.isErr()) {
+            cleanup_on_error();
+            return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
+                                             " wo: " + r.error());
+        }
+
+        // FFN weights
+        r = load_qweight(lw.w1, hidden, inter);
+        if (r.isErr()) {
+            cleanup_on_error();
+            return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
+                                             " w1: " + r.error());
+        }
+
+        r = load_qweight(lw.w2, inter, hidden);
+        if (r.isErr()) {
+            cleanup_on_error();
+            return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
+                                             " w2: " + r.error());
+        }
+
+        r = load_qweight(lw.w3, hidden, inter);
+        if (r.isErr()) {
+            cleanup_on_error();
+            return Result<ModelWeights>::err("Layer " + std::to_string(layer) +
+                                             " w3: " + r.error());
+        }
+
+        // RMSNorm weights (FP16)
+        std::vector<half> norm_host(hidden);
+
+        file.read(reinterpret_cast<char *>(norm_host.data()), hidden * sizeof(half));
+        if (!file) {
+            cleanup_on_error();
+            return Result<ModelWeights>::err("Failed to read rms_att_weight for layer " +
+                                             std::to_string(layer));
+        }
+        CUDA_CHECK(cudaMalloc(&lw.rms_att_weight, hidden * sizeof(half)));
+        CUDA_CHECK(cudaMemcpy(lw.rms_att_weight, norm_host.data(), hidden * sizeof(half),
+                              cudaMemcpyHostToDevice));
+
+        file.read(reinterpret_cast<char *>(norm_host.data()), hidden * sizeof(half));
+        if (!file) {
+            cleanup_on_error();
+            return Result<ModelWeights>::err("Failed to read rms_ffn_weight for layer " +
+                                             std::to_string(layer));
+        }
+        CUDA_CHECK(cudaMalloc(&lw.rms_ffn_weight, hidden * sizeof(half)));
+        CUDA_CHECK(cudaMemcpy(lw.rms_ffn_weight, norm_host.data(), hidden * sizeof(half),
+                              cudaMemcpyHostToDevice));
     }
-    CUDA_CHECK(cudaMalloc(&lw.rms_att_weight, hidden * sizeof(half)));
-    CUDA_CHECK(cudaMemcpy(lw.rms_att_weight, norm_host.data(),
-                          hidden * sizeof(half), cudaMemcpyHostToDevice));
 
-    file.read(reinterpret_cast<char *>(norm_host.data()),
-              hidden * sizeof(half));
+    // Read final norm weight
+    std::vector<half> final_norm_host(config.hidden_dim);
+    file.read(reinterpret_cast<char *>(final_norm_host.data()), config.hidden_dim * sizeof(half));
     if (!file) {
-      cleanup_on_error();
-      return Result<ModelWeights>::err(
-          "Failed to read rms_ffn_weight for layer " + std::to_string(layer));
+        cleanup_on_error();
+        return Result<ModelWeights>::err("Failed to read final norm weight");
+    }
+    CUDA_CHECK(cudaMalloc(&weights.final_norm_weight, config.hidden_dim * sizeof(half)));
+    CUDA_CHECK(cudaMemcpy(weights.final_norm_weight, final_norm_host.data(),
+                          config.hidden_dim * sizeof(half), cudaMemcpyHostToDevice));
+
+    // Read LM head
+    auto lm_result = loadQuantizedTensor(file, config.hidden_dim, config.vocab_size, group_size);
+    if (lm_result.isErr()) {
+        cleanup_on_error();
+        return Result<ModelWeights>::err("Failed to read LM head: " + lm_result.error());
     }
-    CUDA_CHECK(cudaMalloc(&lw.rms_ffn_weight, hidden * sizeof(half)));
-    CUDA_CHECK(cudaMemcpy(lw.rms_ffn_weight, norm_host.data(),
-                          hidden * sizeof(half), cudaMemcpyHostToDevice));
-  }
-
-  // Read final norm weight
-  std::vector<half> final_norm_host(config.hidden_dim);
-  file.read(reinterpret_cast<char *>(final_norm_host.data()),
-            config.hidden_dim * sizeof(half));
-  if (!file) {
-    cleanup_on_error();
-    return Result<ModelWeights>::err("Failed to read final norm weight");
-  }
-  CUDA_CHECK(
-      cudaMalloc(&weights.final_norm_weight, config.hidden_dim * sizeof(half)));
-  CUDA_CHECK(cudaMemcpy(weights.final_norm_weight, final_norm_host.data(),
-                        config.hidden_dim * sizeof(half),
-                        cudaMemcpyHostToDevice));
-
-  // Read LM head
-  auto lm_result = loadQuantizedTensor(file, config.hidden_dim,
-                                       config.vocab_size, group_size);
-  if (lm_result.isErr()) {
-    cleanup_on_error();
-    return Result<ModelWeights>::err("Failed to read LM head: " +
-                                     lm_result.error());
-  }
-  weights.lm_head = lm_result.value();
-
-  success = true;
-  return Result<ModelWeights>::ok(std::move(weights));
+    weights.lm_head = lm_result.value();
+
+    success = true;
+    return Result<ModelWeights>::ok(std::move(weights));
 }
 
-Result<QuantizedWeight> ModelLoader::loadQuantizedTensor(std::ifstream &file,
-                                                         int rows, int cols,
+Result<QuantizedWeight> ModelLoader::loadQuantizedTensor(std::ifstream &file, int rows, int cols,
                                                          int group_size) {
 
-  QuantizedWeight qw;
-  qw.rows = rows;
-  qw.cols = cols;
-  qw.group_size = group_size;
-
-  // Read INT8 weights
-  size_t weight_size = qw.weightElements();
-  std::vector<int8_t> weight_host(weight_size);
-  file.read(reinterpret_cast<char *>(weight_host.data()), weight_size);
-  if (!file) {
-    return Result<QuantizedWeight>::err("Failed to read quantized weights");
-  }
-
-  // Read scales
-  size_t scale_size = qw.scaleElements();
-  std::vector<half> scale_host(scale_size);
-  file.read(reinterpret_cast<char *>(scale_host.data()),
-            scale_size * sizeof(half));
-  if (!file) {
-    return Result<QuantizedWeight>::err("Failed to read scale factors");
-  }
-
-  // Allocate GPU memory
-  CUDA_CHECK(cudaMalloc(&qw.data, weight_size * sizeof(int8_t)));
-  CUDA_CHECK(cudaMalloc(&qw.scales, scale_size * sizeof(half)));
-
-  // Transfer to GPU
-  CUDA_CHECK(cudaMemcpy(qw.data, weight_host.data(),
-                        weight_size * sizeof(int8_t), cudaMemcpyHostToDevice));
-  CUDA_CHECK(cudaMemcpy(qw.scales, scale_host.data(), scale_size * sizeof(half),
-                        cudaMemcpyHostToDevice));
-
-  return Result<QuantizedWeight>::ok(qw);
+    QuantizedWeight qw;
+    qw.rows = rows;
+    qw.cols = cols;
+    qw.group_size = group_size;
+
+    // Read INT8 weights
+    size_t              weight_size = qw.weightElements();
+    std::vector<int8_t> weight_host(weight_size);
+    file.read(reinterpret_cast<char *>(weight_host.data()), weight_size);
+    if (!file) {
+        return Result<QuantizedWeight>::err("Failed to read quantized weights");
+    }
+
+    // Read scales
+    size_t            scale_size = qw.scaleElements();
+    std::vector<half> scale_host(scale_size);
+    file.read(reinterpret_cast<char *>(scale_host.data()), scale_size * sizeof(half));
+    if (!file) {
+        return Result<QuantizedWeight>::err("Failed to read scale factors");
+    }
+
+    // Allocate GPU memory
+    CUDA_CHECK(cudaMalloc(&qw.data, weight_size * sizeof(int8_t)));
+    CUDA_CHECK(cudaMalloc(&qw.scales, scale_size * sizeof(half)));
+
+    // Transfer to GPU
+    CUDA_CHECK(cudaMemcpy(qw.data, weight_host.data(), weight_size * sizeof(int8_t),
+                          cudaMemcpyHostToDevice));
+    CUDA_CHECK(cudaMemcpy(qw.scales, scale_host.data(), scale_size * sizeof(half),
+                          cudaMemcpyHostToDevice));
+
+    return Result<QuantizedWeight>::ok(qw);
 }
 
 void ModelLoader::freeWeights(ModelWeights &weights) {
-  if (weights.token_embedding) {
-    cudaFree(weights.token_embedding);
-    weights.token_embedding = nullptr;
-  }
-
-  for (auto &layer : weights.layers) {
-    // Free quantized weights
-    auto free_qw = [](QuantizedWeight &qw) {
-      if (qw.data) {
-        cudaFree(qw.data);
-        qw.data = nullptr;
-      }
-      if (qw.scales) {
-        cudaFree(qw.scales);
-        qw.scales = nullptr;
-      }
-    };
+    if (weights.token_embedding) {
+        cudaFree(weights.token_embedding);
+        weights.token_embedding = nullptr;
+    }
+
+    for (auto &layer : weights.layers) {
+        // Free quantized weights
+        auto free_qw = [](QuantizedWeight &qw) {
+            if (qw.data) {
+                cudaFree(qw.data);
+                qw.data = nullptr;
+            }
+            if (qw.scales) {
+                cudaFree(qw.scales);
+                qw.scales = nullptr;
+            }
+        };
+
+        free_qw(layer.wq);
+        free_qw(layer.wk);
+        free_qw(layer.wv);
+        free_qw(layer.wo);
+        free_qw(layer.w1);
+        free_qw(layer.w2);
+        free_qw(layer.w3);
+
+        if (layer.rms_att_weight) {
+            cudaFree(layer.rms_att_weight);
+            layer.rms_att_weight = nullptr;
+        }
+        if (layer.rms_ffn_weight) {
+            cudaFree(layer.rms_ffn_weight);
+            layer.rms_ffn_weight = nullptr;
+        }
+    }
+    weights.layers.clear();
+
+    if (weights.final_norm_weight) {
+        cudaFree(weights.final_norm_weight);
+        weights.final_norm_weight = nullptr;
+    }
 
-    free_qw(layer.wq);
-    free_qw(layer.wk);
-    free_qw(layer.wv);
-    free_qw(layer.wo);
-    free_qw(layer.w1);
-    free_qw(layer.w2);
-    free_qw(layer.w3);
-
-    if (layer.rms_att_weight) {
-      cudaFree(layer.rms_att_weight);
-      layer.rms_att_weight = nullptr;
+    if (weights.lm_head.data) {
+        cudaFree(weights.lm_head.data);
+        weights.lm_head.data = nullptr;
     }
-    if (layer.rms_ffn_weight) {
-      cudaFree(layer.rms_ffn_weight);
-      layer.rms_ffn_weight = nullptr;
+    if (weights.lm_head.scales) {
+        cudaFree(weights.lm_head.scales);
+        weights.lm_head.scales = nullptr;
     }
-  }
-  weights.layers.clear();
-
-  if (weights.final_norm_weight) {
-    cudaFree(weights.final_norm_weight);
-    weights.final_norm_weight = nullptr;
-  }
-
-  if (weights.lm_head.data) {
-    cudaFree(weights.lm_head.data);
-    weights.lm_head.data = nullptr;
-  }
-  if (weights.lm_head.scales) {
-    cudaFree(weights.lm_head.scales);
-    weights.lm_head.scales = nullptr;
-  }
 }
 
 } // namespace tiny_llm
diff --git a/src/transformer.cpp b/src/transformer.cpp
index f3fb00c..2939fa4 100644
--- a/src/transformer.cpp
+++ b/src/transformer.cpp
@@ -10,54 +10,23 @@
 
 namespace tiny_llm {
 
-TransformerLayer::TransformerLayer(int layer_idx,
-                                   const TransformerWeights &weights,
+TransformerLayer::TransformerLayer(int layer_idx, const TransformerWeights &weights,
                                    const ModelConfig &config)
     : layer_idx_(layer_idx), weights_(weights), config_(config) {
-  // Allocate buffers for max batch size
-  max_batch_tokens_ = config_.max_seq_len; // Support full sequence in prefill
-  allocateBuffers();
+    // Allocate buffers for max batch size
+    max_batch_tokens_ = config_.max_seq_len; // Support full sequence in prefill
+    allocateBuffers();
 }
 
 TransformerLayer::~TransformerLayer() { freeBuffers(); }
 
 TransformerLayer::TransformerLayer(TransformerLayer &&other) noexcept
-    : layer_idx_(other.layer_idx_), weights_(other.weights_),
-      config_(other.config_), norm_output_(other.norm_output_),
-      q_buf_(other.q_buf_), k_buf_(other.k_buf_), v_buf_(other.v_buf_),
-      attn_output_(other.attn_output_), ffn_gate_(other.ffn_gate_),
+    : layer_idx_(other.layer_idx_), weights_(other.weights_), config_(other.config_),
+      norm_output_(other.norm_output_), q_buf_(other.q_buf_), k_buf_(other.k_buf_),
+      v_buf_(other.v_buf_), attn_output_(other.attn_output_), ffn_gate_(other.ffn_gate_),
       ffn_up_(other.ffn_up_), ffn_output_(other.ffn_output_),
-      max_batch_tokens_(other.max_batch_tokens_),
-      buffers_allocated_(other.buffers_allocated_) {
-  // Null out other's pointers
-  other.norm_output_ = nullptr;
-  other.q_buf_ = nullptr;
-  other.k_buf_ = nullptr;
-  other.v_buf_ = nullptr;
-  other.attn_output_ = nullptr;
-  other.ffn_gate_ = nullptr;
-  other.ffn_up_ = nullptr;
-  other.ffn_output_ = nullptr;
-  other.buffers_allocated_ = false;
-}
-
-TransformerLayer &
-TransformerLayer::operator=(TransformerLayer &&other) noexcept {
-  if (this != &other) {
-    freeBuffers();
-
-    layer_idx_ = other.layer_idx_;
-    norm_output_ = other.norm_output_;
-    q_buf_ = other.q_buf_;
-    k_buf_ = other.k_buf_;
-    v_buf_ = other.v_buf_;
-    attn_output_ = other.attn_output_;
-    ffn_gate_ = other.ffn_gate_;
-    ffn_up_ = other.ffn_up_;
-    ffn_output_ = other.ffn_output_;
-    max_batch_tokens_ = other.max_batch_tokens_;
-    buffers_allocated_ = other.buffers_allocated_;
-
+      max_batch_tokens_(other.max_batch_tokens_), buffers_allocated_(other.buffers_allocated_) {
+    // Null out other's pointers
     other.norm_output_ = nullptr;
     other.q_buf_ = nullptr;
     other.k_buf_ = nullptr;
@@ -67,246 +36,249 @@ TransformerLayer::operator=(TransformerLayer &&other) noexcept {
     other.ffn_up_ = nullptr;
     other.ffn_output_ = nullptr;
     other.buffers_allocated_ = false;
-  }
-  return *this;
+}
+
+TransformerLayer &TransformerLayer::operator=(TransformerLayer &&other) noexcept {
+    if (this != &other) {
+        freeBuffers();
+
+        layer_idx_ = other.layer_idx_;
+        norm_output_ = other.norm_output_;
+        q_buf_ = other.q_buf_;
+        k_buf_ = other.k_buf_;
+        v_buf_ = other.v_buf_;
+        attn_output_ = other.attn_output_;
+        ffn_gate_ = other.ffn_gate_;
+        ffn_up_ = other.ffn_up_;
+        ffn_output_ = other.ffn_output_;
+        max_batch_tokens_ = other.max_batch_tokens_;
+        buffers_allocated_ = other.buffers_allocated_;
+
+        other.norm_output_ = nullptr;
+        other.q_buf_ = nullptr;
+        other.k_buf_ = nullptr;
+        other.v_buf_ = nullptr;
+        other.attn_output_ = nullptr;
+        other.ffn_gate_ = nullptr;
+        other.ffn_up_ = nullptr;
+        other.ffn_output_ = nullptr;
+        other.buffers_allocated_ = false;
+    }
+    return *this;
 }
 
 void TransformerLayer::allocateBuffers() {
-  if (buffers_allocated_)
-    return;
-
-  size_t hidden_size = max_batch_tokens_ * config_.hidden_dim;
-  size_t qkv_size = max_batch_tokens_ * config_.num_heads * config_.head_dim;
-  size_t kv_size = max_batch_tokens_ * config_.num_kv_heads * config_.head_dim;
-  size_t ffn_size = max_batch_tokens_ * config_.intermediate_dim;
-
-  CUDA_CHECK(cudaMalloc(&norm_output_, hidden_size * sizeof(half)));
-  CUDA_CHECK(cudaMalloc(&q_buf_, qkv_size * sizeof(half)));
-  CUDA_CHECK(cudaMalloc(&k_buf_, kv_size * sizeof(half)));
-  CUDA_CHECK(cudaMalloc(&v_buf_, kv_size * sizeof(half)));
-  CUDA_CHECK(cudaMalloc(&attn_output_, hidden_size * sizeof(half)));
-  CUDA_CHECK(cudaMalloc(&ffn_gate_, ffn_size * sizeof(half)));
-  CUDA_CHECK(cudaMalloc(&ffn_up_, ffn_size * sizeof(half)));
-  CUDA_CHECK(cudaMalloc(&ffn_output_, hidden_size * sizeof(half)));
-
-  buffers_allocated_ = true;
+    if (buffers_allocated_) return;
+
+    size_t hidden_size = max_batch_tokens_ * config_.hidden_dim;
+    size_t qkv_size = max_batch_tokens_ * config_.num_heads * config_.head_dim;
+    size_t kv_size = max_batch_tokens_ * config_.num_kv_heads * config_.head_dim;
+    size_t ffn_size = max_batch_tokens_ * config_.intermediate_dim;
+
+    CUDA_CHECK(cudaMalloc(&norm_output_, hidden_size * sizeof(half)));
+    CUDA_CHECK(cudaMalloc(&q_buf_, qkv_size * sizeof(half)));
+    CUDA_CHECK(cudaMalloc(&k_buf_, kv_size * sizeof(half)));
+    CUDA_CHECK(cudaMalloc(&v_buf_, kv_size * sizeof(half)));
+    CUDA_CHECK(cudaMalloc(&attn_output_, hidden_size * sizeof(half)));
+    CUDA_CHECK(cudaMalloc(&ffn_gate_, ffn_size * sizeof(half)));
+    CUDA_CHECK(cudaMalloc(&ffn_up_, ffn_size * sizeof(half)));
+    CUDA_CHECK(cudaMalloc(&ffn_output_, hidden_size * sizeof(half)));
+
+    buffers_allocated_ = true;
 }
 
 void TransformerLayer::freeBuffers() {
-  if (!buffers_allocated_)
-    return;
-
-  // Use safe checks in destructor (no exceptions)
-  auto safe_free = [](half *ptr) {
-    if (ptr) {
-      cudaError_t err = cudaFree(ptr);
-      if (err != cudaSuccess) {
-        fprintf(stderr, "CUDA error in freeBuffers: %s\n",
-                cudaGetErrorString(err));
-      }
-    }
-  };
-
-  safe_free(norm_output_);
-  safe_free(q_buf_);
-  safe_free(k_buf_);
-  safe_free(v_buf_);
-  safe_free(attn_output_);
-  safe_free(ffn_gate_);
-  safe_free(ffn_up_);
-  safe_free(ffn_output_);
-
-  norm_output_ = nullptr;
-  q_buf_ = nullptr;
-  k_buf_ = nullptr;
-  v_buf_ = nullptr;
-  attn_output_ = nullptr;
-  ffn_gate_ = nullptr;
-  ffn_up_ = nullptr;
-  ffn_output_ = nullptr;
-  buffers_allocated_ = false;
+    if (!buffers_allocated_) return;
+
+    // Use safe checks in destructor (no exceptions)
+    auto safe_free = [](half *ptr) {
+        if (ptr) {
+            cudaError_t err = cudaFree(ptr);
+            if (err != cudaSuccess) {
+                fprintf(stderr, "CUDA error in freeBuffers: %s\n", cudaGetErrorString(err));
+            }
+        }
+    };
+
+    safe_free(norm_output_);
+    safe_free(q_buf_);
+    safe_free(k_buf_);
+    safe_free(v_buf_);
+    safe_free(attn_output_);
+    safe_free(ffn_gate_);
+    safe_free(ffn_up_);
+    safe_free(ffn_output_);
+
+    norm_output_ = nullptr;
+    q_buf_ = nullptr;
+    k_buf_ = nullptr;
+    v_buf_ = nullptr;
+    attn_output_ = nullptr;
+    ffn_gate_ = nullptr;
+    ffn_up_ = nullptr;
+    ffn_output_ = nullptr;
+    buffers_allocated_ = false;
 }
 
-void TransformerLayer::forward(half *hidden_states, KVCacheManager &kv_cache,
-                               int seq_id, int position, cudaStream_t stream) {
-  // Input validation
-  auto ptr_result = Validator::validateNotNull(hidden_states, "hidden_states");
-  if (ptr_result.isErr()) {
-    TLLM_ERROR("forward: {}", ptr_result.error());
-    return;
-  }
-
-  if (position < 0 || position >= config_.max_seq_len) {
-    TLLM_ERROR("forward: invalid position {} for layer {}, max_seq_len={}",
-               position, layer_idx_, config_.max_seq_len);
-    return;
-  }
-
-  if (!kv_cache.hasSequence(seq_id)) {
-    TLLM_ERROR("forward: invalid seq_id {} for layer {}", seq_id, layer_idx_);
-    return;
-  }
-
-  // Single token decode
-  const int num_tokens = 1;
-  const int hidden_dim = config_.hidden_dim;
-
-  // Attention sublayer with residual
-  // x = x + attention(rms_norm(x))
-  rmsNorm(hidden_states, weights_.rms_att_weight, norm_output_, num_tokens,
-          stream);
-  attention(norm_output_, attn_output_, kv_cache, seq_id, position, num_tokens,
-            stream);
-  kernels::add_inplace(hidden_states, attn_output_, num_tokens * hidden_dim,
-                       stream);
-
-  // FFN sublayer with residual
-  // x = x + ffn(rms_norm(x))
-  rmsNorm(hidden_states, weights_.rms_ffn_weight, norm_output_, num_tokens,
-          stream);
-  feedForward(norm_output_, ffn_output_, num_tokens, stream);
-  kernels::add_inplace(hidden_states, ffn_output_, num_tokens * hidden_dim,
-                       stream);
+void TransformerLayer::forward(half *hidden_states, KVCacheManager &kv_cache, int seq_id,
+                               int position, cudaStream_t stream) {
+    // Input validation
+    auto ptr_result = Validator::validateNotNull(hidden_states, "hidden_states");
+    if (ptr_result.isErr()) {
+        TLLM_ERROR("forward: {}", ptr_result.error());
+        return;
+    }
+
+    if (position < 0 || position >= config_.max_seq_len) {
+        TLLM_ERROR("forward: invalid position {} for layer {}, max_seq_len={}", position,
+                   layer_idx_, config_.max_seq_len);
+        return;
+    }
+
+    if (!kv_cache.hasSequence(seq_id)) {
+        TLLM_ERROR("forward: invalid seq_id {} for layer {}", seq_id, layer_idx_);
+        return;
+    }
+
+    // Single token decode
+    const int num_tokens = 1;
+    const int hidden_dim = config_.hidden_dim;
+
+    // Attention sublayer with residual
+    // x = x + attention(rms_norm(x))
+    rmsNorm(hidden_states, weights_.rms_att_weight, norm_output_, num_tokens, stream);
+    attention(norm_output_, attn_output_, kv_cache, seq_id, position, num_tokens, stream);
+    kernels::add_inplace(hidden_states, attn_output_, num_tokens * hidden_dim, stream);
+
+    // FFN sublayer with residual
+    // x = x + ffn(rms_norm(x))
+    rmsNorm(hidden_states, weights_.rms_ffn_weight, norm_output_, num_tokens, stream);
+    feedForward(norm_output_, ffn_output_, num_tokens, stream);
+    kernels::add_inplace(hidden_states, ffn_output_, num_tokens * hidden_dim, stream);
 }
 
-void TransformerLayer::forwardPrefill(half *hidden_states,
-                                      KVCacheManager &kv_cache, int seq_id,
+void TransformerLayer::forwardPrefill(half *hidden_states, KVCacheManager &kv_cache, int seq_id,
                                       int seq_len, cudaStream_t stream) {
-  // Input validation
-  auto ptr_result = Validator::validateNotNull(hidden_states, "hidden_states");
-  if (ptr_result.isErr()) {
-    TLLM_ERROR("forwardPrefill: {}", ptr_result.error());
-    return;
-  }
-
-  if (seq_len <= 0) {
-    TLLM_ERROR("forwardPrefill: invalid seq_len {}", seq_len);
-    return;
-  }
-
-  if (seq_len > config_.max_seq_len) {
-    TLLM_ERROR("forwardPrefill: seq_len {} exceeds max_seq_len {}",
-               seq_len, config_.max_seq_len);
-    return;
-  }
-
-  if (!kv_cache.hasSequence(seq_id)) {
-    TLLM_ERROR("forwardPrefill: invalid seq_id {}", seq_id);
-    return;
-  }
-
-  // Multiple tokens prefill
-  const int num_tokens = seq_len;
-  const int hidden_dim = config_.hidden_dim;
-
-  // Attention sublayer
-  rmsNorm(hidden_states, weights_.rms_att_weight, norm_output_, num_tokens,
-          stream);
-  attention(norm_output_, attn_output_, kv_cache, seq_id, 0, num_tokens,
-            stream);
-  kernels::add_inplace(hidden_states, attn_output_, num_tokens * hidden_dim,
-                       stream);
-
-  // FFN sublayer
-  rmsNorm(hidden_states, weights_.rms_ffn_weight, norm_output_, num_tokens,
-          stream);
-  feedForward(norm_output_, ffn_output_, num_tokens, stream);
-  kernels::add_inplace(hidden_states, ffn_output_, num_tokens * hidden_dim,
-                       stream);
+    // Input validation
+    auto ptr_result = Validator::validateNotNull(hidden_states, "hidden_states");
+    if (ptr_result.isErr()) {
+        TLLM_ERROR("forwardPrefill: {}", ptr_result.error());
+        return;
+    }
+
+    if (seq_len <= 0) {
+        TLLM_ERROR("forwardPrefill: invalid seq_len {}", seq_len);
+        return;
+    }
+
+    if (seq_len > config_.max_seq_len) {
+        TLLM_ERROR("forwardPrefill: seq_len {} exceeds max_seq_len {}", seq_len,
+                   config_.max_seq_len);
+        return;
+    }
+
+    if (!kv_cache.hasSequence(seq_id)) {
+        TLLM_ERROR("forwardPrefill: invalid seq_id {}", seq_id);
+        return;
+    }
+
+    // Multiple tokens prefill
+    const int num_tokens = seq_len;
+    const int hidden_dim = config_.hidden_dim;
+
+    // Attention sublayer
+    rmsNorm(hidden_states, weights_.rms_att_weight, norm_output_, num_tokens, stream);
+    attention(norm_output_, attn_output_, kv_cache, seq_id, 0, num_tokens, stream);
+    kernels::add_inplace(hidden_states, attn_output_, num_tokens * hidden_dim, stream);
+
+    // FFN sublayer
+    rmsNorm(hidden_states, weights_.rms_ffn_weight, norm_output_, num_tokens, stream);
+    feedForward(norm_output_, ffn_output_, num_tokens, stream);
+    kernels::add_inplace(hidden_states, ffn_output_, num_tokens * hidden_dim, stream);
 }
 
-void TransformerLayer::attention(const half *x, half *output,
-                                 KVCacheManager &kv_cache, int seq_id,
-                                 int position, int num_tokens,
-                                 cudaStream_t stream) {
-  int hidden_dim = config_.hidden_dim;
-  int num_heads = config_.num_heads;
-  int num_kv_heads = config_.num_kv_heads;
-  int head_dim = config_.head_dim;
-  int group_size = weights_.wq.group_size;
-
-  // Q projection: [num_tokens, hidden_dim] @ [hidden_dim, num_heads * head_dim]
-  kernels::w8a16_matmul(x, weights_.wq.data, weights_.wq.scales, q_buf_,
-                        num_tokens, num_heads * head_dim, hidden_dim,
-                        group_size, stream);
-
-  // K projection: [num_tokens, hidden_dim] @ [hidden_dim, num_kv_heads *
-  // head_dim]
-  kernels::w8a16_matmul(x, weights_.wk.data, weights_.wk.scales, k_buf_,
-                        num_tokens, num_kv_heads * head_dim, hidden_dim,
-                        group_size, stream);
-
-  // V projection: [num_tokens, hidden_dim] @ [hidden_dim, num_kv_heads *
-  // head_dim]
-  kernels::w8a16_matmul(x, weights_.wv.data, weights_.wv.scales, v_buf_,
-                        num_tokens, num_kv_heads * head_dim, hidden_dim,
-                        group_size, stream);
-
-  // Get KV cache pointers
-  auto [k_cache, v_cache] = kv_cache.getCache(seq_id, layer_idx_);
-
-  // Append new K, V to cache
-  kv_cache.appendKV(seq_id, layer_idx_, k_buf_, v_buf_, num_tokens, stream);
-
-  // Compute attention
-  float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
-  int current_seq_len = kv_cache.getSeqLen(seq_id);
-
-  if (num_tokens == 1) {
-    // Decode: appendKV() writes the current token into cache but does not make it
-    // visible via getSeqLen() until the caller advances once after all layers.
-    int attended_seq_len = current_seq_len + 1;
-    kernels::attention_decode(q_buf_, k_cache, v_cache, attn_output_, scale, 1,
-                              num_heads, attended_seq_len, head_dim, stream);
-  } else {
-    // Prefill: full attention with causal mask over the current token batch.
-    kernels::attention_prefill(q_buf_, k_buf_, v_buf_, attn_output_, scale, 1,
-                               num_heads, num_tokens, head_dim, stream);
-  }
-
-  // Output projection: [num_tokens, num_heads * head_dim] @ [num_heads *
-  // head_dim, hidden_dim]
-  kernels::w8a16_matmul(attn_output_, weights_.wo.data, weights_.wo.scales,
-                        output, num_tokens, hidden_dim, num_heads * head_dim,
-                        group_size, stream);
+void TransformerLayer::attention(const half *x, half *output, KVCacheManager &kv_cache, int seq_id,
+                                 int position, int num_tokens, cudaStream_t stream) {
+    int hidden_dim = config_.hidden_dim;
+    int num_heads = config_.num_heads;
+    int num_kv_heads = config_.num_kv_heads;
+    int head_dim = config_.head_dim;
+    int group_size = weights_.wq.group_size;
+
+    // Q projection: [num_tokens, hidden_dim] @ [hidden_dim, num_heads * head_dim]
+    kernels::w8a16_matmul(x, weights_.wq.data, weights_.wq.scales, q_buf_, num_tokens,
+                          num_heads * head_dim, hidden_dim, group_size, stream);
+
+    // K projection: [num_tokens, hidden_dim] @ [hidden_dim, num_kv_heads *
+    // head_dim]
+    kernels::w8a16_matmul(x, weights_.wk.data, weights_.wk.scales, k_buf_, num_tokens,
+                          num_kv_heads * head_dim, hidden_dim, group_size, stream);
+
+    // V projection: [num_tokens, hidden_dim] @ [hidden_dim, num_kv_heads *
+    // head_dim]
+    kernels::w8a16_matmul(x, weights_.wv.data, weights_.wv.scales, v_buf_, num_tokens,
+                          num_kv_heads * head_dim, hidden_dim, group_size, stream);
+
+    // Get KV cache pointers
+    auto [k_cache, v_cache] = kv_cache.getCache(seq_id, layer_idx_);
+
+    // Append new K, V to cache
+    kv_cache.appendKV(seq_id, layer_idx_, k_buf_, v_buf_, num_tokens, stream);
+
+    // Compute attention
+    float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
+    int   current_seq_len = kv_cache.getSeqLen(seq_id);
+
+    if (num_tokens == 1) {
+        // Decode: appendKV() writes the current token into cache but does not make it
+        // visible via getSeqLen() until the caller advances once after all layers.
+        int attended_seq_len = current_seq_len + 1;
+        kernels::attention_decode(q_buf_, k_cache, v_cache, attn_output_, scale, 1, num_heads,
+                                  attended_seq_len, head_dim, stream);
+    } else {
+        // Prefill: full attention with causal mask over the current token batch.
+        kernels::attention_prefill(q_buf_, k_buf_, v_buf_, attn_output_, scale, 1, num_heads,
+                                   num_tokens, head_dim, stream);
+    }
+
+    // Output projection: [num_tokens, num_heads * head_dim] @ [num_heads *
+    // head_dim, hidden_dim]
+    kernels::w8a16_matmul(attn_output_, weights_.wo.data, weights_.wo.scales, output, num_tokens,
+                          hidden_dim, num_heads * head_dim, group_size, stream);
 }
 
 void TransformerLayer::feedForward(const half *x, half *output, int num_tokens,
                                    cudaStream_t stream) {
-  int hidden_dim = config_.hidden_dim;
-  int intermediate_dim = config_.intermediate_dim;
-  int group_size = weights_.w1.group_size;
-
-  // SwiGLU FFN:
-  // gate = silu(x @ w1)
-  // up = x @ w3
-  // output = (gate * up) @ w2
-
-  // Gate projection: [num_tokens, hidden_dim] @ [hidden_dim, intermediate_dim]
-  kernels::w8a16_matmul(x, weights_.w1.data, weights_.w1.scales, ffn_gate_,
-                        num_tokens, intermediate_dim, hidden_dim, group_size,
-                        stream);
-
-  // Up projection: [num_tokens, hidden_dim] @ [hidden_dim, intermediate_dim]
-  kernels::w8a16_matmul(x, weights_.w3.data, weights_.w3.scales, ffn_up_,
-                        num_tokens, intermediate_dim, hidden_dim, group_size,
-                        stream);
-
-  // SiLU activation and element-wise multiply
-  kernels::silu_mul_inplace(ffn_gate_, ffn_up_, num_tokens * intermediate_dim,
-                            stream);
-
-  // Down projection: [num_tokens, intermediate_dim] @ [intermediate_dim,
-  // hidden_dim]
-  kernels::w8a16_matmul(ffn_gate_, weights_.w2.data, weights_.w2.scales, output,
-                        num_tokens, hidden_dim, intermediate_dim, group_size,
-                        stream);
+    int hidden_dim = config_.hidden_dim;
+    int intermediate_dim = config_.intermediate_dim;
+    int group_size = weights_.w1.group_size;
+
+    // SwiGLU FFN:
+    // gate = silu(x @ w1)
+    // up = x @ w3
+    // output = (gate * up) @ w2
+
+    // Gate projection: [num_tokens, hidden_dim] @ [hidden_dim, intermediate_dim]
+    kernels::w8a16_matmul(x, weights_.w1.data, weights_.w1.scales, ffn_gate_, num_tokens,
+                          intermediate_dim, hidden_dim, group_size, stream);
+
+    // Up projection: [num_tokens, hidden_dim] @ [hidden_dim, intermediate_dim]
+    kernels::w8a16_matmul(x, weights_.w3.data, weights_.w3.scales, ffn_up_, num_tokens,
+                          intermediate_dim, hidden_dim, group_size, stream);
+
+    // SiLU activation and element-wise multiply
+    kernels::silu_mul_inplace(ffn_gate_, ffn_up_, num_tokens * intermediate_dim, stream);
+
+    // Down projection: [num_tokens, intermediate_dim] @ [intermediate_dim,
+    // hidden_dim]
+    kernels::w8a16_matmul(ffn_gate_, weights_.w2.data, weights_.w2.scales, output, num_tokens,
+                          hidden_dim, intermediate_dim, group_size, stream);
 }
 
-void TransformerLayer::rmsNorm(const half *x, const half *weight, half *output,
-                               int num_tokens, cudaStream_t stream) {
-  kernels::rmsnorm(x, weight, output, num_tokens, config_.hidden_dim,
-                   config_.rms_norm_eps, stream);
+void TransformerLayer::rmsNorm(const half *x, const half *weight, half *output, int num_tokens,
+                               cudaStream_t stream) {
+    kernels::rmsnorm(x, weight, output, num_tokens, config_.hidden_dim, config_.rms_norm_eps,
+                     stream);
 }
 
 } // namespace tiny_llm
diff --git a/src/types.cpp b/src/types.cpp
index fe1fa12..cb8d2e3 100644
--- a/src/types.cpp
+++ b/src/types.cpp
@@ -4,7 +4,7 @@
 namespace tiny_llm {
 
 Result<void> GenerationConfig::validate() const {
-  return Validator::validateGenerationConfig(*this);
+    return Validator::validateGenerationConfig(*this);
 }
 
 } // namespace tiny_llm
diff --git a/tests/test_cuda_utils.cpp b/tests/test_cuda_utils.cpp
index 8abcd9c..8850638 100644
--- a/tests/test_cuda_utils.cpp
+++ b/tests/test_cuda_utils.cpp
@@ -8,220 +8,220 @@ using namespace tiny_llm;
 class ResultTest : public ::testing::Test {};
 
 TEST_F(ResultTest, OkResultHoldsValue) {
-  auto result = Result<int>::ok(42);
-  EXPECT_TRUE(result.isOk());
-  EXPECT_FALSE(result.isErr());
-  EXPECT_EQ(result.value(), 42);
+    auto result = Result<int>::ok(42);
+    EXPECT_TRUE(result.isOk());
+    EXPECT_FALSE(result.isErr());
+    EXPECT_EQ(result.value(), 42);
 }
 
 TEST_F(ResultTest, ErrResultHoldsMessage) {
-  auto result = Result<int>::err("Something went wrong");
-  EXPECT_FALSE(result.isOk());
-  EXPECT_TRUE(result.isErr());
-  EXPECT_EQ(result.error(), "Something went wrong");
+    auto result = Result<int>::err("Something went wrong");
+    EXPECT_FALSE(result.isOk());
+    EXPECT_TRUE(result.isErr());
+    EXPECT_EQ(result.error(), "Something went wrong");
 }
 
 TEST_F(ResultTest, ValueOrReturnsValueOnOk) {
-  auto result = Result<int>::ok(42);
-  EXPECT_EQ(result.valueOr(0), 42);
+    auto result = Result<int>::ok(42);
+    EXPECT_EQ(result.valueOr(0), 42);
 }
 
 TEST_F(ResultTest, ValueOrReturnsDefaultOnErr) {
-  auto result = Result<int>::err("error");
-  EXPECT_EQ(result.valueOr(99), 99);
+    auto result = Result<int>::err("error");
+    EXPECT_EQ(result.valueOr(99), 99);
 }
 
 TEST_F(ResultTest, AccessingValueOnErrThrows) {
-  auto result = Result<int>::err("error");
-  EXPECT_THROW(result.value(), std::runtime_error);
+    auto result = Result<int>::err("error");
+    EXPECT_THROW(result.value(), std::runtime_error);
 }
 
 TEST_F(ResultTest, AccessingErrorOnOkThrows) {
-  auto result = Result<int>::ok(42);
-  EXPECT_THROW(result.error(), std::runtime_error);
+    auto result = Result<int>::ok(42);
+    EXPECT_THROW(result.error(), std::runtime_error);
 }
 
 TEST_F(ResultTest, MapTransformsValue) {
-  auto result = Result<int>::ok(10);
-  auto mapped = result.map([](int x) { return x * 2; });
-  EXPECT_TRUE(mapped.isOk());
-  EXPECT_EQ(mapped.value(), 20);
+    auto result = Result<int>::ok(10);
+    auto mapped = result.map([](int x) { return x * 2; });
+    EXPECT_TRUE(mapped.isOk());
+    EXPECT_EQ(mapped.value(), 20);
 }
 
 TEST_F(ResultTest, MapPreservesError) {
-  auto result = Result<int>::err("error");
-  auto mapped = result.map([](int x) { return x * 2; });
-  EXPECT_TRUE(mapped.isErr());
-  EXPECT_EQ(mapped.error(), "error");
+    auto result = Result<int>::err("error");
+    auto mapped = result.map([](int x) { return x * 2; });
+    EXPECT_TRUE(mapped.isErr());
+    EXPECT_EQ(mapped.error(), "error");
 }
 
 TEST_F(ResultTest, VoidResultOk) {
-  auto result = Result<void>::ok();
-  EXPECT_TRUE(result.isOk());
-  EXPECT_FALSE(result.isErr());
+    auto result = Result<void>::ok();
+    EXPECT_TRUE(result.isOk());
+    EXPECT_FALSE(result.isErr());
 }
 
 TEST_F(ResultTest, VoidResultErr) {
-  auto result = Result<void>::err("void error");
-  EXPECT_FALSE(result.isOk());
-  EXPECT_TRUE(result.isErr());
-  EXPECT_EQ(result.error(), "void error");
+    auto result = Result<void>::err("void error");
+    EXPECT_FALSE(result.isOk());
+    EXPECT_TRUE(result.isErr());
+    EXPECT_EQ(result.error(), "void error");
 }
 
 TEST_F(ResultTest, StringResult) {
-  auto result = Result<std::string>::ok("hello");
-  EXPECT_TRUE(result.isOk());
-  EXPECT_EQ(result.value(), "hello");
+    auto result = Result<std::string>::ok("hello");
+    EXPECT_TRUE(result.isOk());
+    EXPECT_EQ(result.value(), "hello");
 }
 
 // Test CudaException class
 class CudaExceptionTest : public ::testing::Test {};
 
 TEST_F(CudaExceptionTest, ExceptionContainsErrorInfo) {
-  CudaException ex(cudaErrorMemoryAllocation, "test.cu", 42);
+    CudaException ex(cudaErrorMemoryAllocation, "test.cu", 42);
 
-  EXPECT_EQ(ex.error(), cudaErrorMemoryAllocation);
-  EXPECT_STREQ(ex.file(), "test.cu");
-  EXPECT_EQ(ex.line(), 42);
+    EXPECT_EQ(ex.error(), cudaErrorMemoryAllocation);
+    EXPECT_STREQ(ex.file(), "test.cu");
+    EXPECT_EQ(ex.line(), 42);
 
-  std::string what_str = ex.what();
-  EXPECT_TRUE(what_str.find("test.cu") != std::string::npos);
-  EXPECT_TRUE(what_str.find("42") != std::string::npos);
+    std::string what_str = ex.what();
+    EXPECT_TRUE(what_str.find("test.cu") != std::string::npos);
+    EXPECT_TRUE(what_str.find("42") != std::string::npos);
 }
 
 // Test CUDA_CHECK macro (requires CUDA device)
 class CudaCheckTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    if (err != cudaSuccess || device_count == 0) {
-      GTEST_SKIP() << "No CUDA device available";
+  protected:
+    void SetUp() override {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        if (err != cudaSuccess || device_count == 0) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
     }
-  }
 };
 
 TEST_F(CudaCheckTest, SuccessfulCallDoesNotThrow) {
-  EXPECT_NO_THROW({ CUDA_CHECK(cudaSetDevice(0)); });
+    EXPECT_NO_THROW({ CUDA_CHECK(cudaSetDevice(0)); });
 }
 
 TEST_F(CudaCheckTest, FailedCallThrowsCudaException) {
-  // Try to allocate an impossibly large amount of memory
-  void *ptr = nullptr;
-  EXPECT_THROW({ CUDA_CHECK(cudaMalloc(&ptr, SIZE_MAX)); }, CudaException);
+    // Try to allocate an impossibly large amount of memory
+    void *ptr = nullptr;
+    EXPECT_THROW({ CUDA_CHECK(cudaMalloc(&ptr, SIZE_MAX)); }, CudaException);
 }
 
 // Test DeviceBuffer
 class DeviceBufferTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    if (err != cudaSuccess || device_count == 0) {
-      GTEST_SKIP() << "No CUDA device available";
+  protected:
+    void SetUp() override {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        if (err != cudaSuccess || device_count == 0) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
     }
-  }
 };
 
 TEST_F(DeviceBufferTest, DefaultConstructorCreatesEmptyBuffer) {
-  DeviceBuffer<float> buffer;
-  EXPECT_EQ(buffer.data(), nullptr);
-  EXPECT_EQ(buffer.size(), 0);
-  EXPECT_EQ(buffer.bytes(), 0);
+    DeviceBuffer<float> buffer;
+    EXPECT_EQ(buffer.data(), nullptr);
+    EXPECT_EQ(buffer.size(), 0);
+    EXPECT_EQ(buffer.bytes(), 0);
 }
 
 TEST_F(DeviceBufferTest, AllocatesMemory) {
-  DeviceBuffer<float> buffer(100);
-  EXPECT_NE(buffer.data(), nullptr);
-  EXPECT_EQ(buffer.size(), 100);
-  EXPECT_EQ(buffer.bytes(), 100 * sizeof(float));
+    DeviceBuffer<float> buffer(100);
+    EXPECT_NE(buffer.data(), nullptr);
+    EXPECT_EQ(buffer.size(), 100);
+    EXPECT_EQ(buffer.bytes(), 100 * sizeof(float));
 }
 
 TEST_F(DeviceBufferTest, MoveConstructor) {
-  DeviceBuffer<float> buffer1(100);
-  float *ptr = buffer1.data();
+    DeviceBuffer<float> buffer1(100);
+    float              *ptr = buffer1.data();
 
-  DeviceBuffer<float> buffer2(std::move(buffer1));
-  EXPECT_EQ(buffer2.data(), ptr);
-  EXPECT_EQ(buffer2.size(), 100);
-  EXPECT_EQ(buffer1.data(), nullptr);
-  EXPECT_EQ(buffer1.size(), 0);
+    DeviceBuffer<float> buffer2(std::move(buffer1));
+    EXPECT_EQ(buffer2.data(), ptr);
+    EXPECT_EQ(buffer2.size(), 100);
+    EXPECT_EQ(buffer1.data(), nullptr);
+    EXPECT_EQ(buffer1.size(), 0);
 }
 
 TEST_F(DeviceBufferTest, MoveAssignment) {
-  DeviceBuffer<float> buffer1(100);
-  DeviceBuffer<float> buffer2(50);
-  float *ptr = buffer1.data();
+    DeviceBuffer<float> buffer1(100);
+    DeviceBuffer<float> buffer2(50);
+    float              *ptr = buffer1.data();
 
-  buffer2 = std::move(buffer1);
-  EXPECT_EQ(buffer2.data(), ptr);
-  EXPECT_EQ(buffer2.size(), 100);
+    buffer2 = std::move(buffer1);
+    EXPECT_EQ(buffer2.data(), ptr);
+    EXPECT_EQ(buffer2.size(), 100);
 }
 
 TEST_F(DeviceBufferTest, CopyFromAndToHost) {
-  const size_t count = 100;
-  std::vector<float> host_data(count);
-  for (size_t i = 0; i < count; ++i) {
-    host_data[i] = static_cast<float>(i);
-  }
+    const size_t       count = 100;
+    std::vector<float> host_data(count);
+    for (size_t i = 0; i < count; ++i) {
+        host_data[i] = static_cast<float>(i);
+    }
 
-  DeviceBuffer<float> buffer(count);
-  buffer.copyFromHost(host_data.data(), count);
+    DeviceBuffer<float> buffer(count);
+    buffer.copyFromHost(host_data.data(), count);
 
-  std::vector<float> result(count);
-  buffer.copyToHost(result.data(), count);
-  cudaDeviceSynchronize();
+    std::vector<float> result(count);
+    buffer.copyToHost(result.data(), count);
+    cudaDeviceSynchronize();
 
-  for (size_t i = 0; i < count; ++i) {
-    EXPECT_FLOAT_EQ(result[i], host_data[i]);
-  }
+    for (size_t i = 0; i < count; ++i) {
+        EXPECT_FLOAT_EQ(result[i], host_data[i]);
+    }
 }
 
 // Test CudaStream
 class CudaStreamTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    if (err != cudaSuccess || device_count == 0) {
-      GTEST_SKIP() << "No CUDA device available";
+  protected:
+    void SetUp() override {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        if (err != cudaSuccess || device_count == 0) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
     }
-  }
 };
 
 TEST_F(CudaStreamTest, CreatesValidStream) {
-  CudaStream stream;
-  EXPECT_NE(stream.get(), nullptr);
+    CudaStream stream;
+    EXPECT_NE(stream.get(), nullptr);
 }
 
 TEST_F(CudaStreamTest, MoveConstructor) {
-  CudaStream stream1;
-  cudaStream_t ptr = stream1.get();
+    CudaStream   stream1;
+    cudaStream_t ptr = stream1.get();
 
-  CudaStream stream2(std::move(stream1));
-  EXPECT_EQ(stream2.get(), ptr);
+    CudaStream stream2(std::move(stream1));
+    EXPECT_EQ(stream2.get(), ptr);
 }
 
 TEST_F(CudaStreamTest, Synchronize) {
-  CudaStream stream;
-  EXPECT_NO_THROW(stream.synchronize());
+    CudaStream stream;
+    EXPECT_NO_THROW(stream.synchronize());
 }
 
 // Test getGPUMemoryInfo
 class MemoryInfoTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    if (err != cudaSuccess || device_count == 0) {
-      GTEST_SKIP() << "No CUDA device available";
+  protected:
+    void SetUp() override {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        if (err != cudaSuccess || device_count == 0) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
     }
-  }
 };
 
 TEST_F(MemoryInfoTest, ReturnsValidInfo) {
-  auto info = getGPUMemoryInfo();
-  EXPECT_GT(info.total, 0);
-  EXPECT_GE(info.free, 0);
-  EXPECT_EQ(info.used, info.total - info.free);
+    auto info = getGPUMemoryInfo();
+    EXPECT_GT(info.total, 0);
+    EXPECT_GE(info.free, 0);
+    EXPECT_EQ(info.used, info.total - info.free);
 }
diff --git a/tests/test_inference_engine.cu b/tests/test_inference_engine.cu
index 5d74fde..7d8d440 100644
--- a/tests/test_inference_engine.cu
+++ b/tests/test_inference_engine.cu
@@ -15,414 +15,406 @@ using namespace tiny_llm;
 
 // Helper class for InferenceEngine tests (CPU-based sampling tests)
 class InferenceEngineTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    // Sampling tests are CPU-only, no GPU required
-  }
-
-  void TearDown() override {}
-
-  // Generate random FP16 logits
-  std::vector<half> randomLogits(int vocab_size, float scale = 10.0f,
-                                 unsigned seed = 42) {
-    std::vector<half> data(vocab_size);
-    std::mt19937 gen(seed);
-    std::uniform_real_distribution<float> dist(-scale, scale);
-    for (auto &v : data) {
-      v = __float2half(dist(gen));
+  protected:
+    void SetUp() override {
+        // Sampling tests are CPU-only, no GPU required
     }
-    return data;
-  }
 
-  // Find argmax of logits
-  int argmax(const std::vector<half> &logits) {
-    int max_idx = 0;
-    float max_val = __half2float(logits[0]);
-    for (size_t i = 1; i < logits.size(); ++i) {
-      float val = __half2float(logits[i]);
-      if (val > max_val) {
-        max_val = val;
-        max_idx = static_cast<int>(i);
-      }
+    void TearDown() override {}
+
+    // Generate random FP16 logits
+    std::vector<half> randomLogits(int vocab_size, float scale = 10.0f, unsigned seed = 42) {
+        std::vector<half>                     data(vocab_size);
+        std::mt19937                          gen(seed);
+        std::uniform_real_distribution<float> dist(-scale, scale);
+        for (auto &v : data) {
+            v = __float2half(dist(gen));
+        }
+        return data;
+    }
+
+    // Find argmax of logits
+    int argmax(const std::vector<half> &logits) {
+        int   max_idx = 0;
+        float max_val = __half2float(logits[0]);
+        for (size_t i = 1; i < logits.size(); ++i) {
+            float val = __half2float(logits[i]);
+            if (val > max_val) {
+                max_val = val;
+                max_idx = static_cast<int>(i);
+            }
+        }
+        return max_idx;
     }
-    return max_idx;
-  }
 };
 
 // Unit test: Greedy sampling returns argmax
 TEST_F(InferenceEngineTest, LoadRejectsRuntimeGGUFPath) {
-  ModelConfig config;
-  auto result = InferenceEngine::load("model.gguf", config);
-  EXPECT_TRUE(result.isErr());
-  EXPECT_NE(result.error().find("GGUF runtime loading is not supported yet"),
-            std::string::npos);
+    ModelConfig config;
+    auto        result = InferenceEngine::load("model.gguf", config);
+    EXPECT_TRUE(result.isErr());
+    EXPECT_NE(result.error().find("GGUF runtime loading is not supported yet"), std::string::npos);
 }
 
 TEST_F(InferenceEngineTest, GreedySamplingReturnsArgmax) {
-  int vocab_size = 1000;
-  auto logits = randomLogits(vocab_size, 10.0f, 123);
+    int  vocab_size = 1000;
+    auto logits = randomLogits(vocab_size, 10.0f, 123);
 
-  int expected = argmax(logits);
-  int actual = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
+    int expected = argmax(logits);
+    int actual = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
 
-  EXPECT_EQ(actual, expected);
+    EXPECT_EQ(actual, expected);
 }
 
 // Unit test: Greedy sampling with clear maximum
 TEST_F(InferenceEngineTest, GreedySamplingClearMaximum) {
-  int vocab_size = 100;
-  std::vector<half> logits(vocab_size, __float2half(0.0f));
+    int               vocab_size = 100;
+    std::vector<half> logits(vocab_size, __float2half(0.0f));
 
-  // Set a clear maximum at position 42
-  logits[42] = __float2half(100.0f);
+    // Set a clear maximum at position 42
+    logits[42] = __float2half(100.0f);
 
-  int result = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
-  EXPECT_EQ(result, 42);
+    int result = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
+    EXPECT_EQ(result, 42);
 }
 
 // Unit test: Temperature sampling produces valid indices
 TEST_F(InferenceEngineTest, TemperatureSamplingValidIndex) {
-  int vocab_size = 1000;
-  auto logits = randomLogits(vocab_size, 10.0f, 456);
+    int  vocab_size = 1000;
+    auto logits = randomLogits(vocab_size, 10.0f, 456);
 
-  for (int i = 0; i < 100; ++i) {
-    int result =
-        InferenceEngine::sampleTemperature(logits.data(), vocab_size, 1.0f, i);
-    EXPECT_GE(result, 0);
-    EXPECT_LT(result, vocab_size);
-  }
+    for (int i = 0; i < 100; ++i) {
+        int result = InferenceEngine::sampleTemperature(logits.data(), vocab_size, 1.0f, i);
+        EXPECT_GE(result, 0);
+        EXPECT_LT(result, vocab_size);
+    }
 }
 
 // Unit test: Top-k sampling produces valid indices
 TEST_F(InferenceEngineTest, TopKSamplingValidIndex) {
-  int vocab_size = 1000;
-  int k = 50;
-  auto logits = randomLogits(vocab_size, 10.0f, 789);
-
-  for (int i = 0; i < 100; ++i) {
-    int result =
-        InferenceEngine::sampleTopK(logits.data(), vocab_size, k, 1.0f, i);
-    EXPECT_GE(result, 0);
-    EXPECT_LT(result, vocab_size);
-  }
+    int  vocab_size = 1000;
+    int  k = 50;
+    auto logits = randomLogits(vocab_size, 10.0f, 789);
+
+    for (int i = 0; i < 100; ++i) {
+        int result = InferenceEngine::sampleTopK(logits.data(), vocab_size, k, 1.0f, i);
+        EXPECT_GE(result, 0);
+        EXPECT_LT(result, vocab_size);
+    }
 }
 
 // Unit test: Top-p sampling produces valid indices
 TEST_F(InferenceEngineTest, TopPSamplingValidIndex) {
-  int vocab_size = 1000;
-  float p = 0.9f;
-  auto logits = randomLogits(vocab_size, 10.0f, 101);
-
-  for (int i = 0; i < 100; ++i) {
-    int result =
-        InferenceEngine::sampleTopP(logits.data(), vocab_size, p, 1.0f, i);
-    EXPECT_GE(result, 0);
-    EXPECT_LT(result, vocab_size);
-  }
+    int   vocab_size = 1000;
+    float p = 0.9f;
+    auto  logits = randomLogits(vocab_size, 10.0f, 101);
+
+    for (int i = 0; i < 100; ++i) {
+        int result = InferenceEngine::sampleTopP(logits.data(), vocab_size, p, 1.0f, i);
+        EXPECT_GE(result, 0);
+        EXPECT_LT(result, vocab_size);
+    }
 }
 
 // Unit test: Low temperature approaches greedy
 TEST_F(InferenceEngineTest, LowTemperatureApproachesGreedy) {
-  int vocab_size = 100;
-  auto logits = randomLogits(vocab_size, 10.0f, 202);
+    int  vocab_size = 100;
+    auto logits = randomLogits(vocab_size, 10.0f, 202);
 
-  int greedy_result = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
+    int greedy_result = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
 
-  // With very low temperature, should almost always return argmax
-  int matches = 0;
-  for (int i = 0; i < 100; ++i) {
-    int result =
-        InferenceEngine::sampleTemperature(logits.data(), vocab_size, 0.01f, i);
-    if (result == greedy_result)
-      ++matches;
-  }
+    // With very low temperature, should almost always return argmax
+    int matches = 0;
+    for (int i = 0; i < 100; ++i) {
+        int result = InferenceEngine::sampleTemperature(logits.data(), vocab_size, 0.01f, i);
+        if (result == greedy_result) ++matches;
+    }
 
-  // Should match at least 95% of the time
-  EXPECT_GE(matches, 95);
+    // Should match at least 95% of the time
+    EXPECT_GE(matches, 95);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesInvalidInputsSafely) {
-  EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, 0), 0);
-  EXPECT_EQ(InferenceEngine::sampleTemperature(nullptr, 0, 0.0f, 1), 0);
+    EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, 0), 0);
+    EXPECT_EQ(InferenceEngine::sampleTemperature(nullptr, 0, 0.0f, 1), 0);
 
-  auto logits = randomLogits(16, 10.0f, 303);
-  int top_k_result = InferenceEngine::sampleTopK(logits.data(), 16, 1000, 0.0f, 7);
-  EXPECT_GE(top_k_result, 0);
-  EXPECT_LT(top_k_result, 16);
+    auto logits = randomLogits(16, 10.0f, 303);
+    int  top_k_result = InferenceEngine::sampleTopK(logits.data(), 16, 1000, 0.0f, 7);
+    EXPECT_GE(top_k_result, 0);
+    EXPECT_LT(top_k_result, 16);
 
-  int top_p_result = InferenceEngine::sampleTopP(logits.data(), 16, 0.0f, 0.0f, 9);
-  EXPECT_GE(top_p_result, 0);
-  EXPECT_LT(top_p_result, 16);
+    int top_p_result = InferenceEngine::sampleTopP(logits.data(), 16, 0.0f, 0.0f, 9);
+    EXPECT_GE(top_p_result, 0);
+    EXPECT_LT(top_p_result, 16);
 }
 
 TEST_F(InferenceEngineTest, TopKSamplingClampsToVocabularySize) {
-  auto logits = randomLogits(8, 10.0f, 404);
-  int result = InferenceEngine::sampleTopK(logits.data(), 8, 64, 1.0f, 11);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 8);
+    auto logits = randomLogits(8, 10.0f, 404);
+    int  result = InferenceEngine::sampleTopK(logits.data(), 8, 64, 1.0f, 11);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 8);
 }
 
 TEST_F(InferenceEngineTest, TopPSamplingClampsProbabilityRange) {
-  auto logits = randomLogits(8, 10.0f, 505);
-  int low_result = InferenceEngine::sampleTopP(logits.data(), 8, -1.0f, 1.0f, 13);
-  int high_result = InferenceEngine::sampleTopP(logits.data(), 8, 2.0f, 1.0f, 17);
-  EXPECT_GE(low_result, 0);
-  EXPECT_LT(low_result, 8);
-  EXPECT_GE(high_result, 0);
-  EXPECT_LT(high_result, 8);
+    auto logits = randomLogits(8, 10.0f, 505);
+    int  low_result = InferenceEngine::sampleTopP(logits.data(), 8, -1.0f, 1.0f, 13);
+    int  high_result = InferenceEngine::sampleTopP(logits.data(), 8, 2.0f, 1.0f, 17);
+    EXPECT_GE(low_result, 0);
+    EXPECT_LT(low_result, 8);
+    EXPECT_GE(high_result, 0);
+    EXPECT_LT(high_result, 8);
 }
 
 TEST_F(InferenceEngineTest, TemperatureSamplingClampsNonPositiveTemperature) {
-  auto logits = randomLogits(8, 10.0f, 606);
-  int result = InferenceEngine::sampleTemperature(logits.data(), 8, 0.0f, 19);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 8);
+    auto logits = randomLogits(8, 10.0f, 606);
+    int  result = InferenceEngine::sampleTemperature(logits.data(), 8, 0.0f, 19);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 8);
 }
 
 TEST_F(InferenceEngineTest, GreedySamplingHandlesSingleTokenVocabulary) {
-  half logit = __float2half(1.0f);
-  EXPECT_EQ(InferenceEngine::sampleGreedy(&logit, 1), 0);
+    half logit = __float2half(1.0f);
+    EXPECT_EQ(InferenceEngine::sampleGreedy(&logit, 1), 0);
 }
 
 TEST_F(InferenceEngineTest, TopKSamplingHandlesNonPositiveK) {
-  auto logits = randomLogits(8, 10.0f, 707);
-  int result = InferenceEngine::sampleTopK(logits.data(), 8, 0, 1.0f, 23);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 8);
+    auto logits = randomLogits(8, 10.0f, 707);
+    int  result = InferenceEngine::sampleTopK(logits.data(), 8, 0, 1.0f, 23);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 8);
 }
 
 TEST_F(InferenceEngineTest, TopPSamplingHandlesTinyPositiveProbability) {
-  auto logits = randomLogits(8, 10.0f, 808);
-  int result = InferenceEngine::sampleTopP(logits.data(), 8, 1e-8f, 1.0f, 29);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 8);
+    auto logits = randomLogits(8, 10.0f, 808);
+    int  result = InferenceEngine::sampleTopP(logits.data(), 8, 1e-8f, 1.0f, 29);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 8);
 }
 
 TEST_F(InferenceEngineTest, TemperatureSamplingHandlesTinyPositiveTemperature) {
-  auto logits = randomLogits(8, 10.0f, 909);
-  int result = InferenceEngine::sampleTemperature(logits.data(), 8, 1e-8f, 31);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 8);
+    auto logits = randomLogits(8, 10.0f, 909);
+    int  result = InferenceEngine::sampleTemperature(logits.data(), 8, 1e-8f, 31);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 8);
 }
 
 TEST_F(InferenceEngineTest, TopKSamplingHandlesNullInputSafely) {
-  EXPECT_EQ(InferenceEngine::sampleTopK(nullptr, 0, 5, 1.0f, 37), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopK(nullptr, 0, 5, 1.0f, 37), 0);
 }
 
 TEST_F(InferenceEngineTest, TopPSamplingHandlesNullInputSafely) {
-  EXPECT_EQ(InferenceEngine::sampleTopP(nullptr, 0, 0.9f, 1.0f, 41), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopP(nullptr, 0, 0.9f, 1.0f, 41), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingDoesNotReturnOutOfRangeIndexAfterClamping) {
-  auto logits = randomLogits(3, 10.0f, 1001);
-  for (int seed = 0; seed < 20; ++seed) {
-    int a = InferenceEngine::sampleTemperature(logits.data(), 3, -5.0f, seed);
-    int b = InferenceEngine::sampleTopK(logits.data(), 3, 999, -5.0f, seed + 100);
-    int c = InferenceEngine::sampleTopP(logits.data(), 3, 5.0f, -5.0f, seed + 200);
-    EXPECT_GE(a, 0);
-    EXPECT_LT(a, 3);
-    EXPECT_GE(b, 0);
-    EXPECT_LT(b, 3);
-    EXPECT_GE(c, 0);
-    EXPECT_LT(c, 3);
-  }
+    auto logits = randomLogits(3, 10.0f, 1001);
+    for (int seed = 0; seed < 20; ++seed) {
+        int a = InferenceEngine::sampleTemperature(logits.data(), 3, -5.0f, seed);
+        int b = InferenceEngine::sampleTopK(logits.data(), 3, 999, -5.0f, seed + 100);
+        int c = InferenceEngine::sampleTopP(logits.data(), 3, 5.0f, -5.0f, seed + 200);
+        EXPECT_GE(a, 0);
+        EXPECT_LT(a, 3);
+        EXPECT_GE(b, 0);
+        EXPECT_LT(b, 3);
+        EXPECT_GE(c, 0);
+        EXPECT_LT(c, 3);
+    }
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesNegativeVocabularyGracefully) {
-  EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, -1), 0);
-  EXPECT_EQ(InferenceEngine::sampleTemperature(nullptr, -1, 1.0f, 1), 0);
+    EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, -1), 0);
+    EXPECT_EQ(InferenceEngine::sampleTemperature(nullptr, -1, 1.0f, 1), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesNegativeProbabilityGracefully) {
-  auto logits = randomLogits(5, 10.0f, 1111);
-  int result = InferenceEngine::sampleTopP(logits.data(), 5, -10.0f, 1.0f, 43);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 5);
+    auto logits = randomLogits(5, 10.0f, 1111);
+    int  result = InferenceEngine::sampleTopP(logits.data(), 5, -10.0f, 1.0f, 43);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 5);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesHugeTemperatureGracefully) {
-  auto logits = randomLogits(5, 10.0f, 1212);
-  int result = InferenceEngine::sampleTemperature(logits.data(), 5, 1e6f, 47);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 5);
+    auto logits = randomLogits(5, 10.0f, 1212);
+    int  result = InferenceEngine::sampleTemperature(logits.data(), 5, 1e6f, 47);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 5);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesHugeTopPGracefully) {
-  auto logits = randomLogits(5, 10.0f, 1313);
-  int result = InferenceEngine::sampleTopP(logits.data(), 5, 1e6f, 1.0f, 53);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 5);
+    auto logits = randomLogits(5, 10.0f, 1313);
+    int  result = InferenceEngine::sampleTopP(logits.data(), 5, 1e6f, 1.0f, 53);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 5);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesHugeTopKGracefully) {
-  auto logits = randomLogits(5, 10.0f, 1414);
-  int result = InferenceEngine::sampleTopK(logits.data(), 5, 1000000, 1.0f, 59);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 5);
+    auto logits = randomLogits(5, 10.0f, 1414);
+    int  result = InferenceEngine::sampleTopK(logits.data(), 5, 1000000, 1.0f, 59);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 5);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesZeroVocabularyGracefully) {
-  EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, 0), 0);
+    EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, 0), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesNullInputAcrossStrategies) {
-  EXPECT_EQ(InferenceEngine::sampleTemperature(nullptr, 0, 1.0f, 61), 0);
-  EXPECT_EQ(InferenceEngine::sampleTopK(nullptr, 0, 1, 1.0f, 67), 0);
-  EXPECT_EQ(InferenceEngine::sampleTopP(nullptr, 0, 0.5f, 1.0f, 71), 0);
+    EXPECT_EQ(InferenceEngine::sampleTemperature(nullptr, 0, 1.0f, 61), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopK(nullptr, 0, 1, 1.0f, 67), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopP(nullptr, 0, 0.5f, 1.0f, 71), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesDegenerateSingleElementCases) {
-  half logit = __float2half(0.0f);
-  EXPECT_EQ(InferenceEngine::sampleTemperature(&logit, 1, 0.0f, 73), 0);
-  EXPECT_EQ(InferenceEngine::sampleTopK(&logit, 1, 0, 0.0f, 79), 0);
-  EXPECT_EQ(InferenceEngine::sampleTopP(&logit, 1, 0.0f, 0.0f, 83), 0);
+    half logit = __float2half(0.0f);
+    EXPECT_EQ(InferenceEngine::sampleTemperature(&logit, 1, 0.0f, 73), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopK(&logit, 1, 0, 0.0f, 79), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopP(&logit, 1, 0.0f, 0.0f, 83), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesLargeKOnSmallVocabulary) {
-  auto logits = randomLogits(2, 10.0f, 1515);
-  int result = InferenceEngine::sampleTopK(logits.data(), 2, 9999, 1.0f, 89);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 2);
+    auto logits = randomLogits(2, 10.0f, 1515);
+    int  result = InferenceEngine::sampleTopK(logits.data(), 2, 9999, 1.0f, 89);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 2);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesExtremePBounds) {
-  auto logits = randomLogits(2, 10.0f, 1616);
-  int low = InferenceEngine::sampleTopP(logits.data(), 2, -999.0f, 1.0f, 97);
-  int high = InferenceEngine::sampleTopP(logits.data(), 2, 999.0f, 1.0f, 101);
-  EXPECT_GE(low, 0);
-  EXPECT_LT(low, 2);
-  EXPECT_GE(high, 0);
-  EXPECT_LT(high, 2);
+    auto logits = randomLogits(2, 10.0f, 1616);
+    int  low = InferenceEngine::sampleTopP(logits.data(), 2, -999.0f, 1.0f, 97);
+    int  high = InferenceEngine::sampleTopP(logits.data(), 2, 999.0f, 1.0f, 101);
+    EXPECT_GE(low, 0);
+    EXPECT_LT(low, 2);
+    EXPECT_GE(high, 0);
+    EXPECT_LT(high, 2);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesExtremeTemperatureBounds) {
-  auto logits = randomLogits(2, 10.0f, 1717);
-  int low = InferenceEngine::sampleTemperature(logits.data(), 2, -999.0f, 103);
-  int high = InferenceEngine::sampleTemperature(logits.data(), 2, 999.0f, 107);
-  EXPECT_GE(low, 0);
-  EXPECT_LT(low, 2);
-  EXPECT_GE(high, 0);
-  EXPECT_LT(high, 2);
+    auto logits = randomLogits(2, 10.0f, 1717);
+    int  low = InferenceEngine::sampleTemperature(logits.data(), 2, -999.0f, 103);
+    int  high = InferenceEngine::sampleTemperature(logits.data(), 2, 999.0f, 107);
+    EXPECT_GE(low, 0);
+    EXPECT_LT(low, 2);
+    EXPECT_GE(high, 0);
+    EXPECT_LT(high, 2);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesZeroAndNegativeStrategiesGracefully) {
-  auto logits = randomLogits(4, 10.0f, 1818);
-  EXPECT_GE(InferenceEngine::sampleTopK(logits.data(), 4, -5, 1.0f, 109), 0);
-  EXPECT_GE(InferenceEngine::sampleTopP(logits.data(), 4, -5.0f, 1.0f, 113), 0);
+    auto logits = randomLogits(4, 10.0f, 1818);
+    EXPECT_GE(InferenceEngine::sampleTopK(logits.data(), 4, -5, 1.0f, 109), 0);
+    EXPECT_GE(InferenceEngine::sampleTopP(logits.data(), 4, -5.0f, 1.0f, 113), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingOutputsRemainBounded) {
-  auto logits = randomLogits(4, 10.0f, 1919);
-  for (int seed = 0; seed < 10; ++seed) {
-    int result = InferenceEngine::sampleTopK(logits.data(), 4, seed - 5, 0.0f, seed + 2000);
-    EXPECT_GE(result, 0);
-    EXPECT_LT(result, 4);
-  }
+    auto logits = randomLogits(4, 10.0f, 1919);
+    for (int seed = 0; seed < 10; ++seed) {
+        int result = InferenceEngine::sampleTopK(logits.data(), 4, seed - 5, 0.0f, seed + 2000);
+        EXPECT_GE(result, 0);
+        EXPECT_LT(result, 4);
+    }
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesNullGreedyInputSafely) {
-  EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, 1), 0);
+    EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, 1), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesNullTemperatureInputSafely) {
-  EXPECT_EQ(InferenceEngine::sampleTemperature(nullptr, 1, 1.0f, 211), 0);
+    EXPECT_EQ(InferenceEngine::sampleTemperature(nullptr, 1, 1.0f, 211), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesNullTopKInputSafely) {
-  EXPECT_EQ(InferenceEngine::sampleTopK(nullptr, 1, 1, 1.0f, 223), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopK(nullptr, 1, 1, 1.0f, 223), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesNullTopPInputSafely) {
-  EXPECT_EQ(InferenceEngine::sampleTopP(nullptr, 1, 0.9f, 1.0f, 227), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopP(nullptr, 1, 0.9f, 1.0f, 227), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesInvalidAllAroundGracefully) {
-  EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, 0), 0);
-  EXPECT_EQ(InferenceEngine::sampleTemperature(nullptr, 0, -1.0f, 229), 0);
-  EXPECT_EQ(InferenceEngine::sampleTopK(nullptr, 0, -1, -1.0f, 233), 0);
-  EXPECT_EQ(InferenceEngine::sampleTopP(nullptr, 0, -1.0f, -1.0f, 239), 0);
+    EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, 0), 0);
+    EXPECT_EQ(InferenceEngine::sampleTemperature(nullptr, 0, -1.0f, 229), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopK(nullptr, 0, -1, -1.0f, 233), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopP(nullptr, 0, -1.0f, -1.0f, 239), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesSingleValueAcrossStrategies) {
-  half logit = __float2half(2.0f);
-  EXPECT_EQ(InferenceEngine::sampleGreedy(&logit, 1), 0);
-  EXPECT_EQ(InferenceEngine::sampleTemperature(&logit, 1, 1.0f, 241), 0);
-  EXPECT_EQ(InferenceEngine::sampleTopK(&logit, 1, 1, 1.0f, 251), 0);
-  EXPECT_EQ(InferenceEngine::sampleTopP(&logit, 1, 1.0f, 1.0f, 257), 0);
+    half logit = __float2half(2.0f);
+    EXPECT_EQ(InferenceEngine::sampleGreedy(&logit, 1), 0);
+    EXPECT_EQ(InferenceEngine::sampleTemperature(&logit, 1, 1.0f, 241), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopK(&logit, 1, 1, 1.0f, 251), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopP(&logit, 1, 1.0f, 1.0f, 257), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesMinimalProbabilityCase) {
-  auto logits = randomLogits(3, 10.0f, 2020);
-  int result = InferenceEngine::sampleTopP(logits.data(), 3, 1e-12f, 1.0f, 263);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 3);
+    auto logits = randomLogits(3, 10.0f, 2020);
+    int  result = InferenceEngine::sampleTopP(logits.data(), 3, 1e-12f, 1.0f, 263);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 3);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesMinimalTemperatureCase) {
-  auto logits = randomLogits(3, 10.0f, 2121);
-  int result = InferenceEngine::sampleTemperature(logits.data(), 3, 1e-12f, 269);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 3);
+    auto logits = randomLogits(3, 10.0f, 2121);
+    int  result = InferenceEngine::sampleTemperature(logits.data(), 3, 1e-12f, 269);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 3);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesZeroKGracefully) {
-  auto logits = randomLogits(3, 10.0f, 2222);
-  int result = InferenceEngine::sampleTopK(logits.data(), 3, 0, 1.0f, 271);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 3);
+    auto logits = randomLogits(3, 10.0f, 2222);
+    int  result = InferenceEngine::sampleTopK(logits.data(), 3, 0, 1.0f, 271);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 3);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesNegativeKGracefully) {
-  auto logits = randomLogits(3, 10.0f, 2323);
-  int result = InferenceEngine::sampleTopK(logits.data(), 3, -100, 1.0f, 277);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 3);
+    auto logits = randomLogits(3, 10.0f, 2323);
+    int  result = InferenceEngine::sampleTopK(logits.data(), 3, -100, 1.0f, 277);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 3);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesProbabilityAboveOneGracefully) {
-  auto logits = randomLogits(3, 10.0f, 2424);
-  int result = InferenceEngine::sampleTopP(logits.data(), 3, 100.0f, 1.0f, 281);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 3);
+    auto logits = randomLogits(3, 10.0f, 2424);
+    int  result = InferenceEngine::sampleTopP(logits.data(), 3, 100.0f, 1.0f, 281);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 3);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesProbabilityBelowZeroGracefully) {
-  auto logits = randomLogits(3, 10.0f, 2525);
-  int result = InferenceEngine::sampleTopP(logits.data(), 3, -100.0f, 1.0f, 283);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 3);
+    auto logits = randomLogits(3, 10.0f, 2525);
+    int  result = InferenceEngine::sampleTopP(logits.data(), 3, -100.0f, 1.0f, 283);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 3);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesVeryLargeTemperatureGracefully) {
-  auto logits = randomLogits(3, 10.0f, 2626);
-  int result = InferenceEngine::sampleTemperature(logits.data(), 3, 1e9f, 293);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 3);
+    auto logits = randomLogits(3, 10.0f, 2626);
+    int  result = InferenceEngine::sampleTemperature(logits.data(), 3, 1e9f, 293);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 3);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesVeryNegativeTemperatureGracefully) {
-  auto logits = randomLogits(3, 10.0f, 2727);
-  int result = InferenceEngine::sampleTemperature(logits.data(), 3, -1e9f, 307);
-  EXPECT_GE(result, 0);
-  EXPECT_LT(result, 3);
+    auto logits = randomLogits(3, 10.0f, 2727);
+    int  result = InferenceEngine::sampleTemperature(logits.data(), 3, -1e9f, 307);
+    EXPECT_GE(result, 0);
+    EXPECT_LT(result, 3);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesNullWithPositiveVocabularyGracefully) {
-  EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, 3), 0);
+    EXPECT_EQ(InferenceEngine::sampleGreedy(nullptr, 3), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesNullProbabilityStrategiesGracefully) {
-  EXPECT_EQ(InferenceEngine::sampleTopK(nullptr, 3, 2, 1.0f, 311), 0);
-  EXPECT_EQ(InferenceEngine::sampleTopP(nullptr, 3, 0.5f, 1.0f, 313), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopK(nullptr, 3, 2, 1.0f, 311), 0);
+    EXPECT_EQ(InferenceEngine::sampleTopP(nullptr, 3, 0.5f, 1.0f, 313), 0);
 }
 
 TEST_F(InferenceEngineTest, SamplingHandlesSmallVocabularyAcrossStrategies) {
-  auto logits = randomLogits(1, 10.0f, 2828);
-  EXPECT_EQ(InferenceEngine::sampleGreedy(logits.data(), 1), 0);
-  EXPECT_EQ(InferenceEngine::sampleTemperature(logits.data(), 1, 1.0f, 317), 0);
+    auto logits = randomLogits(1, 10.0f, 2828);
+    EXPECT_EQ(InferenceEngine::sampleGreedy(logits.data(), 1), 0);
+    EXPECT_EQ(InferenceEngine::sampleTemperature(logits.data(), 1, 1.0f, 317), 0);
 }
 
-
 // Property-based tests
 // Feature: tiny-llm-inference-engine, Property 6: Greedy Sampling Correctness
 // Validates: Requirements 5.2
@@ -434,107 +426,102 @@ class SamplingPropertyTest : public InferenceEngineTest {};
 // value
 RC_GTEST_FIXTURE_PROP(SamplingPropertyTest, GreedySamplingEqualsArgmax,
                       (int vocab_raw, unsigned seed)) {
-  // Constrain vocab size to reasonable range
-  int vocab_size = 100 + (std::abs(vocab_raw) % 9900); // 100 to 10000
-
-  // Generate random logits
-  std::vector<half> logits(vocab_size);
-  std::mt19937 gen(seed);
-  std::uniform_real_distribution<float> dist(-100.0f, 100.0f);
-  for (auto &v : logits) {
-    v = __float2half(dist(gen));
-  }
-
-  // Find expected argmax
-  int expected = 0;
-  float max_val = __half2float(logits[0]);
-  for (int i = 1; i < vocab_size; ++i) {
-    float val = __half2float(logits[i]);
-    if (val > max_val) {
-      max_val = val;
-      expected = i;
+    // Constrain vocab size to reasonable range
+    int vocab_size = 100 + (std::abs(vocab_raw) % 9900); // 100 to 10000
+
+    // Generate random logits
+    std::vector<half>                     logits(vocab_size);
+    std::mt19937                          gen(seed);
+    std::uniform_real_distribution<float> dist(-100.0f, 100.0f);
+    for (auto &v : logits) {
+        v = __float2half(dist(gen));
+    }
+
+    // Find expected argmax
+    int   expected = 0;
+    float max_val = __half2float(logits[0]);
+    for (int i = 1; i < vocab_size; ++i) {
+        float val = __half2float(logits[i]);
+        if (val > max_val) {
+            max_val = val;
+            expected = i;
+        }
     }
-  }
 
-  // Property: greedy sampling should return argmax
-  int actual = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
-  RC_ASSERT(actual == expected);
+    // Property: greedy sampling should return argmax
+    int actual = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
+    RC_ASSERT(actual == expected);
 }
 
 // Property: Temperature sampling produces valid indices
 RC_GTEST_FIXTURE_PROP(SamplingPropertyTest, TemperatureSamplingValidRange,
                       (int vocab_raw, float temp_raw, unsigned seed)) {
-  int vocab_size = 100 + (std::abs(vocab_raw) % 9900);
-  float temperature = 0.1f + std::abs(temp_raw) * 0.01f; // 0.1 to ~inf
-  temperature = std::min(temperature, 10.0f);            // Cap at 10
-
-  std::vector<half> logits(vocab_size);
-  std::mt19937 gen(seed);
-  std::uniform_real_distribution<float> dist(-10.0f, 10.0f);
-  for (auto &v : logits) {
-    v = __float2half(dist(gen));
-  }
+    int   vocab_size = 100 + (std::abs(vocab_raw) % 9900);
+    float temperature = 0.1f + std::abs(temp_raw) * 0.01f; // 0.1 to ~inf
+    temperature = std::min(temperature, 10.0f);            // Cap at 10
+
+    std::vector<half>                     logits(vocab_size);
+    std::mt19937                          gen(seed);
+    std::uniform_real_distribution<float> dist(-10.0f, 10.0f);
+    for (auto &v : logits) {
+        v = __float2half(dist(gen));
+    }
 
-  int result = InferenceEngine::sampleTemperature(logits.data(), vocab_size,
-                                                  temperature, seed);
+    int result = InferenceEngine::sampleTemperature(logits.data(), vocab_size, temperature, seed);
 
-  RC_ASSERT(result >= 0);
-  RC_ASSERT(result < vocab_size);
+    RC_ASSERT(result >= 0);
+    RC_ASSERT(result < vocab_size);
 }
 
 // Property: Top-k sampling only selects from top-k tokens
 RC_GTEST_FIXTURE_PROP(SamplingPropertyTest, TopKSamplingFromTopK,
                       (int vocab_raw, int k_raw, unsigned seed)) {
-  int vocab_size = 100 + (std::abs(vocab_raw) % 900); // 100 to 1000
-  int k = 1 + (std::abs(k_raw) %
-               std::min(vocab_size, 100)); // 1 to min(vocab_size, 100)
-
-  std::vector<half> logits(vocab_size);
-  std::mt19937 gen(seed);
-  std::uniform_real_distribution<float> dist(-10.0f, 10.0f);
-  for (auto &v : logits) {
-    v = __float2half(dist(gen));
-  }
-
-  // Find top-k indices
-  std::vector<std::pair<float, int>> sorted_logits(vocab_size);
-  for (int i = 0; i < vocab_size; ++i) {
-    sorted_logits[i] = {__half2float(logits[i]), i};
-  }
-  std::partial_sort(
-      sorted_logits.begin(), sorted_logits.begin() + k, sorted_logits.end(),
-      [](const auto &a, const auto &b) { return a.first > b.first; });
-
-  std::set<int> top_k_indices;
-  for (int i = 0; i < k; ++i) {
-    top_k_indices.insert(sorted_logits[i].second);
-  }
-
-  // Sample multiple times and verify all results are in top-k
-  for (int trial = 0; trial < 10; ++trial) {
-    int result = InferenceEngine::sampleTopK(logits.data(), vocab_size, k, 1.0f,
-                                             seed + trial);
-    RC_ASSERT(top_k_indices.count(result) > 0);
-  }
+    int vocab_size = 100 + (std::abs(vocab_raw) % 900);        // 100 to 1000
+    int k = 1 + (std::abs(k_raw) % std::min(vocab_size, 100)); // 1 to min(vocab_size, 100)
+
+    std::vector<half>                     logits(vocab_size);
+    std::mt19937                          gen(seed);
+    std::uniform_real_distribution<float> dist(-10.0f, 10.0f);
+    for (auto &v : logits) {
+        v = __float2half(dist(gen));
+    }
+
+    // Find top-k indices
+    std::vector<std::pair<float, int>> sorted_logits(vocab_size);
+    for (int i = 0; i < vocab_size; ++i) {
+        sorted_logits[i] = {__half2float(logits[i]), i};
+    }
+    std::partial_sort(sorted_logits.begin(), sorted_logits.begin() + k, sorted_logits.end(),
+                      [](const auto &a, const auto &b) { return a.first > b.first; });
+
+    std::set<int> top_k_indices;
+    for (int i = 0; i < k; ++i) {
+        top_k_indices.insert(sorted_logits[i].second);
+    }
+
+    // Sample multiple times and verify all results are in top-k
+    for (int trial = 0; trial < 10; ++trial) {
+        int result = InferenceEngine::sampleTopK(logits.data(), vocab_size, k, 1.0f, seed + trial);
+        RC_ASSERT(top_k_indices.count(result) > 0);
+    }
 }
 
 // Property: Top-p sampling produces valid indices
 RC_GTEST_FIXTURE_PROP(SamplingPropertyTest, TopPSamplingValidRange,
                       (int vocab_raw, float p_raw, unsigned seed)) {
-  int vocab_size = 100 + (std::abs(vocab_raw) % 900);
-  float p = 0.1f + std::abs(std::fmod(p_raw, 0.9f)); // 0.1 to 1.0
-  p = std::min(p, 1.0f);
-
-  std::vector<half> logits(vocab_size);
-  std::mt19937 gen(seed);
-  std::uniform_real_distribution<float> dist(-10.0f, 10.0f);
-  for (auto &v : logits) {
-    v = __float2half(dist(gen));
-  }
-
-  int result =
-      InferenceEngine::sampleTopP(logits.data(), vocab_size, p, 1.0f, seed);
-
-  RC_ASSERT(result >= 0);
-  RC_ASSERT(result < vocab_size);
+    int   vocab_size = 100 + (std::abs(vocab_raw) % 900);
+    float p = 0.1f + std::abs(std::fmod(p_raw, 0.9f)); // 0.1 to 1.0
+    p = std::min(p, 1.0f);
+
+    std::vector<half>                     logits(vocab_size);
+    std::mt19937                          gen(seed);
+    std::uniform_real_distribution<float> dist(-10.0f, 10.0f);
+    for (auto &v : logits) {
+        v = __float2half(dist(gen));
+    }
+
+    int result = InferenceEngine::sampleTopP(logits.data(), vocab_size, p, 1.0f, seed);
+
+    RC_ASSERT(result >= 0);
+    RC_ASSERT(result < vocab_size);
 }
diff --git a/tests/test_integration.cu b/tests/test_integration.cu
index 7575f5a..8cf9c82 100644
--- a/tests/test_integration.cu
+++ b/tests/test_integration.cu
@@ -14,318 +14,312 @@ using namespace tiny_llm;
 
 // Helper to check if CUDA device is available
 static bool hasCudaDevice() {
-  static bool checked = false;
-  static bool has_device = false;
-  if (!checked) {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    has_device = (err == cudaSuccess && device_count > 0);
-    checked = true;
-  }
-  return has_device;
+    static bool checked = false;
+    static bool has_device = false;
+    if (!checked) {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        has_device = (err == cudaSuccess && device_count > 0);
+        checked = true;
+    }
+    return has_device;
 }
 
 // Helper class for integration tests that require GPU
 class IntegrationTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    if (!hasCudaDevice()) {
-      GTEST_SKIP() << "No CUDA device available";
+  protected:
+    void SetUp() override {
+        if (!hasCudaDevice()) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
+        cudaSetDevice(0);
     }
-    cudaSetDevice(0);
-  }
 
-  void TearDown() override { cudaDeviceSynchronize(); }
+    void TearDown() override { cudaDeviceSynchronize(); }
+
+    // Create a tiny test model config
+    ModelConfig createTinyConfig() {
+        ModelConfig config;
+        config.vocab_size = 256;
+        config.hidden_dim = 64;
+        config.num_layers = 2;
+        config.num_heads = 4;
+        config.num_kv_heads = 4;
+        config.head_dim = 16;
+        config.intermediate_dim = 128;
+        config.max_seq_len = 64;
+        config.rope_theta = 10000.0f;
+        config.rms_norm_eps = 1e-5f;
+        config.eos_token_id = 2;
+        config.bos_token_id = 1;
+        return config;
+    }
 
-  // Create a tiny test model config
-  ModelConfig createTinyConfig() {
-    ModelConfig config;
-    config.vocab_size = 256;
-    config.hidden_dim = 64;
-    config.num_layers = 2;
-    config.num_heads = 4;
-    config.num_kv_heads = 4;
-    config.head_dim = 16;
-    config.intermediate_dim = 128;
-    config.max_seq_len = 64;
-    config.rope_theta = 10000.0f;
-    config.rms_norm_eps = 1e-5f;
-    config.eos_token_id = 2;
-    config.bos_token_id = 1;
-    return config;
-  }
-
-  // Generate random FP16 tensor on device
-  half *randomDeviceFP16(int size, float scale = 1.0f, unsigned seed = 42) {
-    std::vector<half> h_data(size);
-    std::mt19937 gen(seed);
-    std::uniform_real_distribution<float> dist(-scale, scale);
-    for (auto &v : h_data) {
-      v = __float2half(dist(gen));
+    // Generate random FP16 tensor on device
+    half *randomDeviceFP16(int size, float scale = 1.0f, unsigned seed = 42) {
+        std::vector<half>                     h_data(size);
+        std::mt19937                          gen(seed);
+        std::uniform_real_distribution<float> dist(-scale, scale);
+        for (auto &v : h_data) {
+            v = __float2half(dist(gen));
+        }
+
+        half *d_data;
+        cudaMalloc(&d_data, size * sizeof(half));
+        cudaMemcpy(d_data, h_data.data(), size * sizeof(half), cudaMemcpyHostToDevice);
+        return d_data;
     }
 
-    half *d_data;
-    cudaMalloc(&d_data, size * sizeof(half));
-    cudaMemcpy(d_data, h_data.data(), size * sizeof(half),
-               cudaMemcpyHostToDevice);
-    return d_data;
-  }
-
-  // Generate random INT8 tensor on device
-  int8_t *randomDeviceINT8(int size, unsigned seed = 123) {
-    std::vector<int8_t> h_data(size);
-    std::mt19937 gen(seed);
-    std::uniform_int_distribution<int> dist(-127, 127);
-    for (auto &v : h_data) {
-      v = static_cast<int8_t>(dist(gen));
+    // Generate random INT8 tensor on device
+    int8_t *randomDeviceINT8(int size, unsigned seed = 123) {
+        std::vector<int8_t>                h_data(size);
+        std::mt19937                       gen(seed);
+        std::uniform_int_distribution<int> dist(-127, 127);
+        for (auto &v : h_data) {
+            v = static_cast<int8_t>(dist(gen));
+        }
+
+        int8_t *d_data;
+        cudaMalloc(&d_data, size * sizeof(int8_t));
+        cudaMemcpy(d_data, h_data.data(), size * sizeof(int8_t), cudaMemcpyHostToDevice);
+        return d_data;
     }
 
-    int8_t *d_data;
-    cudaMalloc(&d_data, size * sizeof(int8_t));
-    cudaMemcpy(d_data, h_data.data(), size * sizeof(int8_t),
-               cudaMemcpyHostToDevice);
-    return d_data;
-  }
-
-  // Create random quantized weight
-  QuantizedWeight createRandomWeight(int rows, int cols, int group_size,
-                                     unsigned seed) {
-    QuantizedWeight w;
-    w.rows = rows;
-    w.cols = cols;
-    w.group_size = group_size;
-    w.data = randomDeviceINT8(rows * cols, seed);
-
-    int num_groups = (rows + group_size - 1) / group_size;
-    w.scales = randomDeviceFP16(num_groups * cols, 0.1f, seed + 1000);
-
-    return w;
-  }
-
-  // Free quantized weight
-  void freeWeight(QuantizedWeight &w) {
-    if (w.data) {
-      cudaFree(w.data);
-      w.data = nullptr;
+    // Create random quantized weight
+    QuantizedWeight createRandomWeight(int rows, int cols, int group_size, unsigned seed) {
+        QuantizedWeight w;
+        w.rows = rows;
+        w.cols = cols;
+        w.group_size = group_size;
+        w.data = randomDeviceINT8(rows * cols, seed);
+
+        int num_groups = (rows + group_size - 1) / group_size;
+        w.scales = randomDeviceFP16(num_groups * cols, 0.1f, seed + 1000);
+
+        return w;
     }
-    if (w.scales) {
-      cudaFree(w.scales);
-      w.scales = nullptr;
+
+    // Free quantized weight
+    void freeWeight(QuantizedWeight &w) {
+        if (w.data) {
+            cudaFree(w.data);
+            w.data = nullptr;
+        }
+        if (w.scales) {
+            cudaFree(w.scales);
+            w.scales = nullptr;
+        }
     }
-  }
 };
 
 // Test: Stream pool creation and usage
 TEST_F(IntegrationTest, StreamPoolBasicUsage) {
-  StreamPool pool(4);
+    StreamPool pool(4);
 
-  EXPECT_EQ(pool.numStreams(), 4);
+    EXPECT_EQ(pool.numStreams(), 4);
 
-  // Get streams in round-robin
-  cudaStream_t s0 = pool.getStream();
-  cudaStream_t s1 = pool.getStream();
-  cudaStream_t s2 = pool.getStream();
-  cudaStream_t s3 = pool.getStream();
-  cudaStream_t s4 = pool.getStream(); // Should wrap around
+    // Get streams in round-robin
+    cudaStream_t s0 = pool.getStream();
+    cudaStream_t s1 = pool.getStream();
+    cudaStream_t s2 = pool.getStream();
+    cudaStream_t s3 = pool.getStream();
+    cudaStream_t s4 = pool.getStream(); // Should wrap around
 
-  EXPECT_NE(s0, nullptr);
-  EXPECT_NE(s1, nullptr);
-  EXPECT_EQ(s0, s4); // Round-robin wrap
+    EXPECT_NE(s0, nullptr);
+    EXPECT_NE(s1, nullptr);
+    EXPECT_EQ(s0, s4); // Round-robin wrap
 
-  pool.synchronizeAll();
+    pool.synchronizeAll();
 }
 
 // Test: CUDA event timing
 TEST_F(IntegrationTest, CudaEventTiming) {
-  CudaEvent start, end;
+    CudaEvent start, end;
 
-  start.record();
+    start.record();
 
-  // Do some work
-  std::vector<float> data(1000000, 1.0f);
-  float *d_data;
-  cudaMalloc(&d_data, data.size() * sizeof(float));
-  cudaMemcpy(d_data, data.data(), data.size() * sizeof(float),
-             cudaMemcpyHostToDevice);
-  cudaFree(d_data);
+    // Do some work
+    std::vector<float> data(1000000, 1.0f);
+    float             *d_data;
+    cudaMalloc(&d_data, data.size() * sizeof(float));
+    cudaMemcpy(d_data, data.data(), data.size() * sizeof(float), cudaMemcpyHostToDevice);
+    cudaFree(d_data);
 
-  end.record();
-  end.synchronize();
+    end.record();
+    end.synchronize();
 
-  float elapsed = CudaEvent::elapsedMs(start, end);
-  EXPECT_GT(elapsed, 0.0f);
+    float elapsed = CudaEvent::elapsedMs(start, end);
+    EXPECT_GT(elapsed, 0.0f);
 }
 
 // Test: Memory alignment helper
 TEST_F(IntegrationTest, MemoryAlignment) {
-  EXPECT_EQ(alignTo(100, 128), 128);
-  EXPECT_EQ(alignTo(128, 128), 128);
-  EXPECT_EQ(alignTo(129, 128), 256);
-  EXPECT_EQ(alignTo(0, 128), 0);
+    EXPECT_EQ(alignTo(100, 128), 128);
+    EXPECT_EQ(alignTo(128, 128), 128);
+    EXPECT_EQ(alignTo(129, 128), 256);
+    EXPECT_EQ(alignTo(0, 128), 0);
 }
 
 // Test: Kernel config auto-tuning
 TEST_F(IntegrationTest, KernelConfigAutoTune) {
-  auto config1 = KernelConfig::autoTune(100);
-  EXPECT_GE(config1.block_size, 32);
+    auto config1 = KernelConfig::autoTune(100);
+    EXPECT_GE(config1.block_size, 32);
 
-  auto config2 = KernelConfig::autoTune(10000);
-  EXPECT_GE(config2.block_size, 256);
+    auto config2 = KernelConfig::autoTune(10000);
+    EXPECT_GE(config2.block_size, 256);
 }
 
 // Test: KV Cache with multiple sequences
 TEST_F(IntegrationTest, KVCacheMultipleSequences) {
-  KVCacheConfig config;
-  config.num_layers = 2;
-  config.num_heads = 4;
-  config.head_dim = 16;
-  config.max_seq_len = 32;
-  config.max_batch_size = 4;
-
-  KVCacheManager cache(config);
-
-  // Allocate multiple sequences
-  std::vector<int> seq_ids;
-  for (int i = 0; i < 3; ++i) {
-    auto result = cache.allocateSequence(16);
-    ASSERT_TRUE(result.isOk());
-    seq_ids.push_back(result.value());
-  }
-
-  // Verify all sequences are independent
-  EXPECT_EQ(seq_ids.size(), 3);
-  for (size_t i = 0; i < seq_ids.size(); ++i) {
-    for (size_t j = i + 1; j < seq_ids.size(); ++j) {
-      EXPECT_NE(seq_ids[i], seq_ids[j]);
+    KVCacheConfig config;
+    config.num_layers = 2;
+    config.num_heads = 4;
+    config.head_dim = 16;
+    config.max_seq_len = 32;
+    config.max_batch_size = 4;
+
+    KVCacheManager cache(config);
+
+    // Allocate multiple sequences
+    std::vector<int> seq_ids;
+    for (int i = 0; i < 3; ++i) {
+        auto result = cache.allocateSequence(16);
+        ASSERT_TRUE(result.isOk());
+        seq_ids.push_back(result.value());
     }
-  }
 
-  // Release sequences
-  for (int seq_id : seq_ids) {
-    cache.releaseSequence(seq_id);
-  }
+    // Verify all sequences are independent
+    EXPECT_EQ(seq_ids.size(), 3);
+    for (size_t i = 0; i < seq_ids.size(); ++i) {
+        for (size_t j = i + 1; j < seq_ids.size(); ++j) {
+            EXPECT_NE(seq_ids[i], seq_ids[j]);
+        }
+    }
+
+    // Release sequences
+    for (int seq_id : seq_ids) {
+        cache.releaseSequence(seq_id);
+    }
 }
 
 // Test: Transformer layer forward pass dimensions
 TEST_F(IntegrationTest, TransformerLayerDimensions) {
-  auto config = createTinyConfig();
-
-  // Create random weights for one layer
-  TransformerWeights weights;
-  int hidden = config.hidden_dim;
-  int kv_dim = config.num_kv_heads * config.head_dim;
-  int inter = config.intermediate_dim;
-  int group_size = 32;
-
-  weights.wq = createRandomWeight(hidden, hidden, group_size, 100);
-  weights.wk = createRandomWeight(hidden, kv_dim, group_size, 101);
-  weights.wv = createRandomWeight(hidden, kv_dim, group_size, 102);
-  weights.wo = createRandomWeight(hidden, hidden, group_size, 103);
-  weights.w1 = createRandomWeight(hidden, inter, group_size, 104);
-  weights.w2 = createRandomWeight(inter, hidden, group_size, 105);
-  weights.w3 = createRandomWeight(hidden, inter, group_size, 106);
-  weights.rms_att_weight = randomDeviceFP16(hidden, 1.0f, 107);
-  weights.rms_ffn_weight = randomDeviceFP16(hidden, 1.0f, 108);
-
-  // Create KV cache
-  KVCacheConfig kv_config;
-  kv_config.num_layers = 1;
-  kv_config.num_heads = config.num_kv_heads;
-  kv_config.head_dim = config.head_dim;
-  kv_config.max_seq_len = config.max_seq_len;
-  kv_config.max_batch_size = 1;
-
-  KVCacheManager kv_cache(kv_config);
-  auto alloc_result = kv_cache.allocateSequence(32);
-  ASSERT_TRUE(alloc_result.isOk());
-  int seq_id = alloc_result.value();
-
-  // Create transformer layer
-  TransformerLayer layer(0, weights, config);
-
-  // Create input hidden states
-  half *hidden_states = randomDeviceFP16(hidden, 1.0f, 200);
-
-  // Forward pass should not crash
-  layer.forward(hidden_states, kv_cache, seq_id, 0);
-  cudaDeviceSynchronize();
-
-  // TransformerLayer appends KV, but the caller owns seq_len advancement.
-  EXPECT_EQ(kv_cache.getSeqLen(seq_id), 0);
-  kv_cache.advanceSeqLen(seq_id, 1);
-  EXPECT_EQ(kv_cache.getSeqLen(seq_id), 1);
-
-  // Cleanup
-  cudaFree(hidden_states);
-  freeWeight(weights.wq);
-  freeWeight(weights.wk);
-  freeWeight(weights.wv);
-  freeWeight(weights.wo);
-  freeWeight(weights.w1);
-  freeWeight(weights.w2);
-  freeWeight(weights.w3);
-  cudaFree(weights.rms_att_weight);
-  cudaFree(weights.rms_ffn_weight);
+    auto config = createTinyConfig();
+
+    // Create random weights for one layer
+    TransformerWeights weights;
+    int                hidden = config.hidden_dim;
+    int                kv_dim = config.num_kv_heads * config.head_dim;
+    int                inter = config.intermediate_dim;
+    int                group_size = 32;
+
+    weights.wq = createRandomWeight(hidden, hidden, group_size, 100);
+    weights.wk = createRandomWeight(hidden, kv_dim, group_size, 101);
+    weights.wv = createRandomWeight(hidden, kv_dim, group_size, 102);
+    weights.wo = createRandomWeight(hidden, hidden, group_size, 103);
+    weights.w1 = createRandomWeight(hidden, inter, group_size, 104);
+    weights.w2 = createRandomWeight(inter, hidden, group_size, 105);
+    weights.w3 = createRandomWeight(hidden, inter, group_size, 106);
+    weights.rms_att_weight = randomDeviceFP16(hidden, 1.0f, 107);
+    weights.rms_ffn_weight = randomDeviceFP16(hidden, 1.0f, 108);
+
+    // Create KV cache
+    KVCacheConfig kv_config;
+    kv_config.num_layers = 1;
+    kv_config.num_heads = config.num_kv_heads;
+    kv_config.head_dim = config.head_dim;
+    kv_config.max_seq_len = config.max_seq_len;
+    kv_config.max_batch_size = 1;
+
+    KVCacheManager kv_cache(kv_config);
+    auto           alloc_result = kv_cache.allocateSequence(32);
+    ASSERT_TRUE(alloc_result.isOk());
+    int seq_id = alloc_result.value();
+
+    // Create transformer layer
+    TransformerLayer layer(0, weights, config);
+
+    // Create input hidden states
+    half *hidden_states = randomDeviceFP16(hidden, 1.0f, 200);
+
+    // Forward pass should not crash
+    layer.forward(hidden_states, kv_cache, seq_id, 0);
+    cudaDeviceSynchronize();
+
+    // TransformerLayer appends KV, but the caller owns seq_len advancement.
+    EXPECT_EQ(kv_cache.getSeqLen(seq_id), 0);
+    kv_cache.advanceSeqLen(seq_id, 1);
+    EXPECT_EQ(kv_cache.getSeqLen(seq_id), 1);
+
+    // Cleanup
+    cudaFree(hidden_states);
+    freeWeight(weights.wq);
+    freeWeight(weights.wk);
+    freeWeight(weights.wv);
+    freeWeight(weights.wo);
+    freeWeight(weights.w1);
+    freeWeight(weights.w2);
+    freeWeight(weights.w3);
+    cudaFree(weights.rms_att_weight);
+    cudaFree(weights.rms_ffn_weight);
 }
 
 // Test: Greedy sampling determinism
 TEST_F(IntegrationTest, GreedySamplingDeterministic) {
-  int vocab_size = 1000;
-  std::vector<half> logits(vocab_size);
-
-  std::mt19937 gen(42);
-  std::uniform_real_distribution<float> dist(-10.0f, 10.0f);
-  for (auto &v : logits) {
-    v = __float2half(dist(gen));
-  }
-
-  // Greedy sampling should always return the same result
-  int result1 = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
-  int result2 = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
-  int result3 = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
-
-  EXPECT_EQ(result1, result2);
-  EXPECT_EQ(result2, result3);
+    int               vocab_size = 1000;
+    std::vector<half> logits(vocab_size);
+
+    std::mt19937                          gen(42);
+    std::uniform_real_distribution<float> dist(-10.0f, 10.0f);
+    for (auto &v : logits) {
+        v = __float2half(dist(gen));
+    }
+
+    // Greedy sampling should always return the same result
+    int result1 = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
+    int result2 = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
+    int result3 = InferenceEngine::sampleGreedy(logits.data(), vocab_size);
+
+    EXPECT_EQ(result1, result2);
+    EXPECT_EQ(result2, result3);
 }
 
 // Test: Temperature affects sampling distribution
 TEST_F(IntegrationTest, TemperatureAffectsSampling) {
-  int vocab_size = 100;
-  std::vector<half> logits(vocab_size);
-
-  // Create logits with a clear peak
-  for (int i = 0; i < vocab_size; ++i) {
-    logits[i] = __float2half(static_cast<float>(i) / 10.0f);
-  }
-
-  // Low temperature should concentrate on high logits
-  std::map<int, int> low_temp_counts;
-  for (int i = 0; i < 100; ++i) {
-    int result =
-        InferenceEngine::sampleTemperature(logits.data(), vocab_size, 0.1f, i);
-    low_temp_counts[result]++;
-  }
-
-  // High temperature should spread more
-  std::map<int, int> high_temp_counts;
-  for (int i = 0; i < 100; ++i) {
-    int result = InferenceEngine::sampleTemperature(logits.data(), vocab_size,
-                                                    2.0f, i + 1000);
-    high_temp_counts[result]++;
-  }
-
-  // Low temperature should have fewer unique values
-  EXPECT_LE(low_temp_counts.size(), high_temp_counts.size());
+    int               vocab_size = 100;
+    std::vector<half> logits(vocab_size);
+
+    // Create logits with a clear peak
+    for (int i = 0; i < vocab_size; ++i) {
+        logits[i] = __float2half(static_cast<float>(i) / 10.0f);
+    }
+
+    // Low temperature should concentrate on high logits
+    std::map<int, int> low_temp_counts;
+    for (int i = 0; i < 100; ++i) {
+        int result = InferenceEngine::sampleTemperature(logits.data(), vocab_size, 0.1f, i);
+        low_temp_counts[result]++;
+    }
+
+    // High temperature should spread more
+    std::map<int, int> high_temp_counts;
+    for (int i = 0; i < 100; ++i) {
+        int result = InferenceEngine::sampleTemperature(logits.data(), vocab_size, 2.0f, i + 1000);
+        high_temp_counts[result]++;
+    }
+
+    // Low temperature should have fewer unique values
+    EXPECT_LE(low_temp_counts.size(), high_temp_counts.size());
 }
 
 // Test: Generation statistics tracking
 TEST_F(IntegrationTest, GenerationStatsTracking) {
-  GenerationStats stats;
-
-  // Default values
-  EXPECT_EQ(stats.prefill_time_ms, 0.0f);
-  EXPECT_EQ(stats.decode_time_ms, 0.0f);
-  EXPECT_EQ(stats.prompt_tokens, 0);
-  EXPECT_EQ(stats.tokens_generated, 0);
-  EXPECT_EQ(stats.tokens_per_second, 0.0f);
+    GenerationStats stats;
+
+    // Default values
+    EXPECT_EQ(stats.prefill_time_ms, 0.0f);
+    EXPECT_EQ(stats.decode_time_ms, 0.0f);
+    EXPECT_EQ(stats.prompt_tokens, 0);
+    EXPECT_EQ(stats.tokens_generated, 0);
+    EXPECT_EQ(stats.tokens_per_second, 0.0f);
 }
diff --git a/tests/test_kernels.cu b/tests/test_kernels.cu
index 2dc1732..29711cd 100644
--- a/tests/test_kernels.cu
+++ b/tests/test_kernels.cu
@@ -14,173 +14,169 @@ using namespace tiny_llm::kernels;
 
 // Helper to check if CUDA device is available
 static bool hasCudaDevice() {
-  static bool checked = false;
-  static bool has_device = false;
-  if (!checked) {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    has_device = (err == cudaSuccess && device_count > 0);
-    checked = true;
-  }
-  return has_device;
+    static bool checked = false;
+    static bool has_device = false;
+    if (!checked) {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        has_device = (err == cudaSuccess && device_count > 0);
+        checked = true;
+    }
+    return has_device;
 }
 
 // Helper class for GPU test fixtures
 class RMSNormTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    if (err != cudaSuccess || device_count == 0) {
-      GTEST_SKIP() << "No CUDA device available";
-    }
-    cudaSetDevice(0);
-  }
-
-  void TearDown() override { cudaDeviceSynchronize(); }
-
-  // Generate random FP16 vector
-  std::vector<half> randomFP16(int size, float scale = 1.0f,
-                               unsigned seed = 42) {
-    std::vector<half> data(size);
-    std::mt19937 gen(seed);
-    std::uniform_real_distribution<float> dist(-scale, scale);
-    for (auto &v : data) {
-      v = __float2half(dist(gen));
-    }
-    return data;
-  }
-
-  // Generate FP16 weights (positive values for RMSNorm weights)
-  std::vector<half> randomWeights(int size, unsigned seed = 123) {
-    std::vector<half> data(size);
-    std::mt19937 gen(seed);
-    std::uniform_real_distribution<float> dist(0.5f, 1.5f);
-    for (auto &v : data) {
-      v = __float2half(dist(gen));
-    }
-    return data;
-  }
-
-  // Compute RMS of a vector (on host)
-  float computeRMS(const std::vector<half> &data) {
-    float sum_sq = 0.0f;
-    for (const auto &v : data) {
-      float val = __half2float(v);
-      sum_sq += val * val;
-    }
-    return std::sqrt(sum_sq / data.size());
-  }
-
-  // Compute RMS for a specific row in a batch
-  float computeRowRMS(const std::vector<half> &data, int row, int hidden_dim) {
-    float sum_sq = 0.0f;
-    for (int i = 0; i < hidden_dim; ++i) {
-      float val = __half2float(data[row * hidden_dim + i]);
-      sum_sq += val * val;
-    }
-    return std::sqrt(sum_sq / hidden_dim);
-  }
+  protected:
+    void SetUp() override {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        if (err != cudaSuccess || device_count == 0) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
+        cudaSetDevice(0);
+    }
+
+    void TearDown() override { cudaDeviceSynchronize(); }
+
+    // Generate random FP16 vector
+    std::vector<half> randomFP16(int size, float scale = 1.0f, unsigned seed = 42) {
+        std::vector<half>                     data(size);
+        std::mt19937                          gen(seed);
+        std::uniform_real_distribution<float> dist(-scale, scale);
+        for (auto &v : data) {
+            v = __float2half(dist(gen));
+        }
+        return data;
+    }
+
+    // Generate FP16 weights (positive values for RMSNorm weights)
+    std::vector<half> randomWeights(int size, unsigned seed = 123) {
+        std::vector<half>                     data(size);
+        std::mt19937                          gen(seed);
+        std::uniform_real_distribution<float> dist(0.5f, 1.5f);
+        for (auto &v : data) {
+            v = __float2half(dist(gen));
+        }
+        return data;
+    }
+
+    // Compute RMS of a vector (on host)
+    float computeRMS(const std::vector<half> &data) {
+        float sum_sq = 0.0f;
+        for (const auto &v : data) {
+            float val = __half2float(v);
+            sum_sq += val * val;
+        }
+        return std::sqrt(sum_sq / data.size());
+    }
+
+    // Compute RMS for a specific row in a batch
+    float computeRowRMS(const std::vector<half> &data, int row, int hidden_dim) {
+        float sum_sq = 0.0f;
+        for (int i = 0; i < hidden_dim; ++i) {
+            float val = __half2float(data[row * hidden_dim + i]);
+            sum_sq += val * val;
+        }
+        return std::sqrt(sum_sq / hidden_dim);
+    }
 };
 
 // Unit tests
 TEST_F(RMSNormTest, BasicCorrectness) {
-  int batch_size = 2;
-  int hidden_dim = 64;
-  float eps = 1e-5f;
+    int   batch_size = 2;
+    int   hidden_dim = 64;
+    float eps = 1e-5f;
 
-  auto input = randomFP16(batch_size * hidden_dim, 1.0f);
-  auto weight = randomWeights(hidden_dim);
+    auto input = randomFP16(batch_size * hidden_dim, 1.0f);
+    auto weight = randomWeights(hidden_dim);
 
-  DeviceBuffer<half> d_input(batch_size * hidden_dim);
-  DeviceBuffer<half> d_weight(hidden_dim);
-  DeviceBuffer<half> d_output(batch_size * hidden_dim);
+    DeviceBuffer<half> d_input(batch_size * hidden_dim);
+    DeviceBuffer<half> d_weight(hidden_dim);
+    DeviceBuffer<half> d_output(batch_size * hidden_dim);
 
-  d_input.copyFromHost(input.data(), batch_size * hidden_dim);
-  d_weight.copyFromHost(weight.data(), hidden_dim);
+    d_input.copyFromHost(input.data(), batch_size * hidden_dim);
+    d_weight.copyFromHost(weight.data(), hidden_dim);
 
-  rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size,
-          hidden_dim, eps);
+    rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size, hidden_dim, eps);
 
-  cudaDeviceSynchronize();
+    cudaDeviceSynchronize();
 
-  std::vector<half> output(batch_size * hidden_dim);
-  d_output.copyToHost(output.data(), batch_size * hidden_dim);
-  cudaDeviceSynchronize();
+    std::vector<half> output(batch_size * hidden_dim);
+    d_output.copyToHost(output.data(), batch_size * hidden_dim);
+    cudaDeviceSynchronize();
 
-  // Verify output is not all zeros
-  bool has_nonzero = false;
-  for (const auto &v : output) {
-    if (__half2float(v) != 0.0f) {
-      has_nonzero = true;
-      break;
+    // Verify output is not all zeros
+    bool has_nonzero = false;
+    for (const auto &v : output) {
+        if (__half2float(v) != 0.0f) {
+            has_nonzero = true;
+            break;
+        }
     }
-  }
-  EXPECT_TRUE(has_nonzero);
+    EXPECT_TRUE(has_nonzero);
 }
 
 TEST_F(RMSNormTest, SmallHiddenDim) {
-  int batch_size = 4;
-  int hidden_dim = 32;
-  float eps = 1e-5f;
+    int   batch_size = 4;
+    int   hidden_dim = 32;
+    float eps = 1e-5f;
 
-  auto input = randomFP16(batch_size * hidden_dim, 1.0f);
-  auto weight = randomWeights(hidden_dim);
+    auto input = randomFP16(batch_size * hidden_dim, 1.0f);
+    auto weight = randomWeights(hidden_dim);
 
-  DeviceBuffer<half> d_input(batch_size * hidden_dim);
-  DeviceBuffer<half> d_weight(hidden_dim);
-  DeviceBuffer<half> d_output(batch_size * hidden_dim);
+    DeviceBuffer<half> d_input(batch_size * hidden_dim);
+    DeviceBuffer<half> d_weight(hidden_dim);
+    DeviceBuffer<half> d_output(batch_size * hidden_dim);
 
-  d_input.copyFromHost(input.data(), batch_size * hidden_dim);
-  d_weight.copyFromHost(weight.data(), hidden_dim);
+    d_input.copyFromHost(input.data(), batch_size * hidden_dim);
+    d_weight.copyFromHost(weight.data(), hidden_dim);
 
-  EXPECT_NO_THROW({
-    rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size,
-            hidden_dim, eps);
-    cudaDeviceSynchronize();
-  });
+    EXPECT_NO_THROW({
+        rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size, hidden_dim, eps);
+        cudaDeviceSynchronize();
+    });
 }
 
 TEST_F(RMSNormTest, LargeHiddenDim) {
-  int batch_size = 2;
-  int hidden_dim = 4096;
-  float eps = 1e-5f;
+    int   batch_size = 2;
+    int   hidden_dim = 4096;
+    float eps = 1e-5f;
 
-  auto input = randomFP16(batch_size * hidden_dim, 1.0f);
-  auto weight = randomWeights(hidden_dim);
+    auto input = randomFP16(batch_size * hidden_dim, 1.0f);
+    auto weight = randomWeights(hidden_dim);
 
-  DeviceBuffer<half> d_input(batch_size * hidden_dim);
-  DeviceBuffer<half> d_weight(hidden_dim);
-  DeviceBuffer<half> d_output(batch_size * hidden_dim);
+    DeviceBuffer<half> d_input(batch_size * hidden_dim);
+    DeviceBuffer<half> d_weight(hidden_dim);
+    DeviceBuffer<half> d_output(batch_size * hidden_dim);
 
-  d_input.copyFromHost(input.data(), batch_size * hidden_dim);
-  d_weight.copyFromHost(weight.data(), hidden_dim);
+    d_input.copyFromHost(input.data(), batch_size * hidden_dim);
+    d_weight.copyFromHost(weight.data(), hidden_dim);
 
-  EXPECT_NO_THROW({
-    rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size,
-            hidden_dim, eps);
-    cudaDeviceSynchronize();
-  });
+    EXPECT_NO_THROW({
+        rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size, hidden_dim, eps);
+        cudaDeviceSynchronize();
+    });
 }
 
 TEST_F(RMSNormTest, InPlaceVersion) {
-  int batch_size = 2;
-  int hidden_dim = 128;
-  float eps = 1e-5f;
+    int   batch_size = 2;
+    int   hidden_dim = 128;
+    float eps = 1e-5f;
 
-  auto input = randomFP16(batch_size * hidden_dim, 1.0f);
-  auto weight = randomWeights(hidden_dim);
+    auto input = randomFP16(batch_size * hidden_dim, 1.0f);
+    auto weight = randomWeights(hidden_dim);
 
-  DeviceBuffer<half> d_x(batch_size * hidden_dim);
-  DeviceBuffer<half> d_weight(hidden_dim);
+    DeviceBuffer<half> d_x(batch_size * hidden_dim);
+    DeviceBuffer<half> d_weight(hidden_dim);
 
-  d_x.copyFromHost(input.data(), batch_size * hidden_dim);
-  d_weight.copyFromHost(weight.data(), hidden_dim);
+    d_x.copyFromHost(input.data(), batch_size * hidden_dim);
+    d_weight.copyFromHost(weight.data(), hidden_dim);
 
-  EXPECT_NO_THROW({
-    rmsnorm_inplace(d_x.data(), d_weight.data(), batch_size, hidden_dim, eps);
-    cudaDeviceSynchronize();
-  });
+    EXPECT_NO_THROW({
+        rmsnorm_inplace(d_x.data(), d_weight.data(), batch_size, hidden_dim, eps);
+        cudaDeviceSynchronize();
+    });
 }
 
 // Property-based tests
@@ -188,15 +184,19 @@ TEST_F(RMSNormTest, InPlaceVersion) {
 // Validates: Requirements 4.4
 // NOTE: Property-based tests are disabled when no CUDA device is available
 
-class RMSNormPropertyTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    if (!hasCudaDevice()) {
-      GTEST_SKIP() << "No CUDA device available";
+class RMSNormPropertyTest : public RMSNormTest {
+  protected:
+    void SetUp() override {
+        if (hasCudaDevice()) {
+            cudaSetDevice(0);
+        }
+    }
+
+    void TearDown() override {
+        if (hasCudaDevice()) {
+            cudaDeviceSynchronize();
+        }
     }
-    cudaSetDevice(0);
-  }
-  void TearDown() override { cudaDeviceSynchronize(); }
 };
 
 // Property 4: RMSNorm Output Properties
@@ -209,196 +209,191 @@ protected:
 
 RC_GTEST_FIXTURE_PROP(RMSNormPropertyTest, OutputRMSIsOne,
                       (int batch_raw, int dim_raw, unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions to reasonable ranges
-  int batch_size = 1 + (std::abs(batch_raw) % 16);
-  int hidden_dim = 32 + (std::abs(dim_raw) % 2016); // 32 to 2048
-  float eps = 1e-5f;
-
-  // Generate random input
-  auto input = randomFP16(batch_size * hidden_dim, 2.0f, seed);
-
-  // Use unit weights to test pure normalization
-  std::vector<half> unit_weight(hidden_dim);
-  for (auto &w : unit_weight) {
-    w = __float2half(1.0f);
-  }
-
-  DeviceBuffer<half> d_input(batch_size * hidden_dim);
-  DeviceBuffer<half> d_weight(hidden_dim);
-  DeviceBuffer<half> d_output(batch_size * hidden_dim);
-
-  d_input.copyFromHost(input.data(), batch_size * hidden_dim);
-  d_weight.copyFromHost(unit_weight.data(), hidden_dim);
-
-  rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size,
-          hidden_dim, eps);
-
-  cudaDeviceSynchronize();
-
-  std::vector<half> output(batch_size * hidden_dim);
-  d_output.copyToHost(output.data(), batch_size * hidden_dim);
-  cudaDeviceSynchronize();
-
-  // Property: For each row, RMS of output should be approximately 1.0
-  for (int b = 0; b < batch_size; ++b) {
-    float rms = computeRowRMS(output, b, hidden_dim);
-
-    // Allow tolerance for FP16 precision
-    // RMS should be close to 1.0 (within 5% for FP16)
-    RC_ASSERT(rms > 0.95f && rms < 1.05f);
-  }
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions to reasonable ranges
+    int   batch_size = 1 + (std::abs(batch_raw) % 16);
+    int   hidden_dim = 32 + (std::abs(dim_raw) % 2016); // 32 to 2048
+    float eps = 1e-5f;
+
+    // Generate random input
+    auto input = randomFP16(batch_size * hidden_dim, 2.0f, seed);
+
+    // Use unit weights to test pure normalization
+    std::vector<half> unit_weight(hidden_dim);
+    for (auto &w : unit_weight) {
+        w = __float2half(1.0f);
+    }
+
+    DeviceBuffer<half> d_input(batch_size * hidden_dim);
+    DeviceBuffer<half> d_weight(hidden_dim);
+    DeviceBuffer<half> d_output(batch_size * hidden_dim);
+
+    d_input.copyFromHost(input.data(), batch_size * hidden_dim);
+    d_weight.copyFromHost(unit_weight.data(), hidden_dim);
+
+    rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size, hidden_dim, eps);
+
+    cudaDeviceSynchronize();
+
+    std::vector<half> output(batch_size * hidden_dim);
+    d_output.copyToHost(output.data(), batch_size * hidden_dim);
+    cudaDeviceSynchronize();
+
+    // Property: For each row, RMS of output should be approximately 1.0
+    for (int b = 0; b < batch_size; ++b) {
+        float rms = computeRowRMS(output, b, hidden_dim);
+
+        // Allow tolerance for FP16 precision
+        // RMS should be close to 1.0 (within 5% for FP16)
+        RC_ASSERT(rms > 0.95f && rms < 1.05f);
+    }
 }
 
 RC_GTEST_FIXTURE_PROP(RMSNormPropertyTest, WeightScaling,
                       (int batch_raw, int dim_raw, unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions
-  int batch_size = 1 + (std::abs(batch_raw) % 8);
-  int hidden_dim = 64 + (std::abs(dim_raw) % 448); // 64 to 512
-  float eps = 1e-5f;
-
-  // Generate random input
-  auto input = randomFP16(batch_size * hidden_dim, 1.0f, seed);
-
-  // Test with constant weight = 2.0
-  std::vector<half> const_weight(hidden_dim);
-  float weight_val = 2.0f;
-  for (auto &w : const_weight) {
-    w = __float2half(weight_val);
-  }
-
-  DeviceBuffer<half> d_input(batch_size * hidden_dim);
-  DeviceBuffer<half> d_weight(hidden_dim);
-  DeviceBuffer<half> d_output(batch_size * hidden_dim);
-
-  d_input.copyFromHost(input.data(), batch_size * hidden_dim);
-  d_weight.copyFromHost(const_weight.data(), hidden_dim);
-
-  rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size,
-          hidden_dim, eps);
-
-  cudaDeviceSynchronize();
-
-  std::vector<half> output(batch_size * hidden_dim);
-  d_output.copyToHost(output.data(), batch_size * hidden_dim);
-  cudaDeviceSynchronize();
-
-  // Property: With constant weight w, RMS of output should be approximately w
-  for (int b = 0; b < batch_size; ++b) {
-    float rms = computeRowRMS(output, b, hidden_dim);
-
-    // RMS should be close to weight_val (within 10% for FP16)
-    RC_ASSERT(rms > weight_val * 0.9f && rms < weight_val * 1.1f);
-  }
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions
+    int   batch_size = 1 + (std::abs(batch_raw) % 8);
+    int   hidden_dim = 64 + (std::abs(dim_raw) % 448); // 64 to 512
+    float eps = 1e-5f;
+
+    // Generate random input
+    auto input = randomFP16(batch_size * hidden_dim, 1.0f, seed);
+
+    // Test with constant weight = 2.0
+    std::vector<half> const_weight(hidden_dim);
+    float             weight_val = 2.0f;
+    for (auto &w : const_weight) {
+        w = __float2half(weight_val);
+    }
+
+    DeviceBuffer<half> d_input(batch_size * hidden_dim);
+    DeviceBuffer<half> d_weight(hidden_dim);
+    DeviceBuffer<half> d_output(batch_size * hidden_dim);
+
+    d_input.copyFromHost(input.data(), batch_size * hidden_dim);
+    d_weight.copyFromHost(const_weight.data(), hidden_dim);
+
+    rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size, hidden_dim, eps);
+
+    cudaDeviceSynchronize();
+
+    std::vector<half> output(batch_size * hidden_dim);
+    d_output.copyToHost(output.data(), batch_size * hidden_dim);
+    cudaDeviceSynchronize();
+
+    // Property: With constant weight w, RMS of output should be approximately w
+    for (int b = 0; b < batch_size; ++b) {
+        float rms = computeRowRMS(output, b, hidden_dim);
+
+        // RMS should be close to weight_val (within 10% for FP16)
+        RC_ASSERT(rms > weight_val * 0.9f && rms < weight_val * 1.1f);
+    }
 }
 
 RC_GTEST_FIXTURE_PROP(RMSNormPropertyTest, NonZeroOutput,
                       (int batch_raw, int dim_raw, unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions
-  int batch_size = 1 + (std::abs(batch_raw) % 8);
-  int hidden_dim = 32 + (std::abs(dim_raw) % 480);
-  float eps = 1e-5f;
-
-  // Generate non-zero input
-  auto input = randomFP16(batch_size * hidden_dim, 1.0f, seed);
-  auto weight = randomWeights(hidden_dim, seed + 1);
-
-  // Ensure input is not all zeros
-  bool input_has_nonzero = false;
-  for (const auto &v : input) {
-    if (std::abs(__half2float(v)) > 1e-6f) {
-      input_has_nonzero = true;
-      break;
-    }
-  }
-  RC_PRE(input_has_nonzero);
-
-  DeviceBuffer<half> d_input(batch_size * hidden_dim);
-  DeviceBuffer<half> d_weight(hidden_dim);
-  DeviceBuffer<half> d_output(batch_size * hidden_dim);
-
-  d_input.copyFromHost(input.data(), batch_size * hidden_dim);
-  d_weight.copyFromHost(weight.data(), hidden_dim);
-
-  rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size,
-          hidden_dim, eps);
-
-  cudaDeviceSynchronize();
-
-  std::vector<half> output(batch_size * hidden_dim);
-  d_output.copyToHost(output.data(), batch_size * hidden_dim);
-  cudaDeviceSynchronize();
-
-  // Property: Output should have non-zero values
-  bool has_nonzero = false;
-  for (const auto &v : output) {
-    if (std::abs(__half2float(v)) > 1e-6f) {
-      has_nonzero = true;
-      break;
-    }
-  }
-  RC_ASSERT(has_nonzero);
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions
+    int   batch_size = 1 + (std::abs(batch_raw) % 8);
+    int   hidden_dim = 32 + (std::abs(dim_raw) % 480);
+    float eps = 1e-5f;
+
+    // Generate non-zero input
+    auto input = randomFP16(batch_size * hidden_dim, 1.0f, seed);
+    auto weight = randomWeights(hidden_dim, seed + 1);
+
+    // Ensure input is not all zeros
+    bool input_has_nonzero = false;
+    for (const auto &v : input) {
+        if (std::abs(__half2float(v)) > 1e-6f) {
+            input_has_nonzero = true;
+            break;
+        }
+    }
+    RC_PRE(input_has_nonzero);
+
+    DeviceBuffer<half> d_input(batch_size * hidden_dim);
+    DeviceBuffer<half> d_weight(hidden_dim);
+    DeviceBuffer<half> d_output(batch_size * hidden_dim);
+
+    d_input.copyFromHost(input.data(), batch_size * hidden_dim);
+    d_weight.copyFromHost(weight.data(), hidden_dim);
+
+    rmsnorm(d_input.data(), d_weight.data(), d_output.data(), batch_size, hidden_dim, eps);
+
+    cudaDeviceSynchronize();
+
+    std::vector<half> output(batch_size * hidden_dim);
+    d_output.copyToHost(output.data(), batch_size * hidden_dim);
+    cudaDeviceSynchronize();
+
+    // Property: Output should have non-zero values
+    bool has_nonzero = false;
+    for (const auto &v : output) {
+        if (std::abs(__half2float(v)) > 1e-6f) {
+            has_nonzero = true;
+            break;
+        }
+    }
+    RC_ASSERT(has_nonzero);
 }
 
 RC_GTEST_FIXTURE_PROP(RMSNormPropertyTest, InPlaceEquivalence,
                       (int batch_raw, int dim_raw, unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions
-  int batch_size = 1 + (std::abs(batch_raw) % 8);
-  int hidden_dim = 64 + (std::abs(dim_raw) % 448);
-  float eps = 1e-5f;
-
-  // Generate random input
-  auto input = randomFP16(batch_size * hidden_dim, 1.0f, seed);
-  auto weight = randomWeights(hidden_dim, seed + 1);
-
-  // Run out-of-place version
-  DeviceBuffer<half> d_input1(batch_size * hidden_dim);
-  DeviceBuffer<half> d_weight(hidden_dim);
-  DeviceBuffer<half> d_output(batch_size * hidden_dim);
-
-  d_input1.copyFromHost(input.data(), batch_size * hidden_dim);
-  d_weight.copyFromHost(weight.data(), hidden_dim);
-
-  rmsnorm(d_input1.data(), d_weight.data(), d_output.data(), batch_size,
-          hidden_dim, eps);
-
-  // Run in-place version
-  DeviceBuffer<half> d_input2(batch_size * hidden_dim);
-  d_input2.copyFromHost(input.data(), batch_size * hidden_dim);
-
-  rmsnorm_inplace(d_input2.data(), d_weight.data(), batch_size, hidden_dim,
-                  eps);
-
-  cudaDeviceSynchronize();
-
-  std::vector<half> output_oop(batch_size * hidden_dim);
-  std::vector<half> output_ip(batch_size * hidden_dim);
-  d_output.copyToHost(output_oop.data(), batch_size * hidden_dim);
-  d_input2.copyToHost(output_ip.data(), batch_size * hidden_dim);
-  cudaDeviceSynchronize();
-
-  // Property: In-place and out-of-place should produce same results
-  for (int i = 0; i < batch_size * hidden_dim; ++i) {
-    float v1 = __half2float(output_oop[i]);
-    float v2 = __half2float(output_ip[i]);
-    float diff = std::abs(v1 - v2);
-    float max_val = std::max(std::abs(v1), std::abs(v2));
-    float rel_diff = max_val > 1e-6f ? diff / max_val : diff;
-
-    // Allow small tolerance for floating point differences
-    RC_ASSERT(rel_diff < 0.01f);
-  }
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions
+    int   batch_size = 1 + (std::abs(batch_raw) % 8);
+    int   hidden_dim = 64 + (std::abs(dim_raw) % 448);
+    float eps = 1e-5f;
+
+    // Generate random input
+    auto input = randomFP16(batch_size * hidden_dim, 1.0f, seed);
+    auto weight = randomWeights(hidden_dim, seed + 1);
+
+    // Run out-of-place version
+    DeviceBuffer<half> d_input1(batch_size * hidden_dim);
+    DeviceBuffer<half> d_weight(hidden_dim);
+    DeviceBuffer<half> d_output(batch_size * hidden_dim);
+
+    d_input1.copyFromHost(input.data(), batch_size * hidden_dim);
+    d_weight.copyFromHost(weight.data(), hidden_dim);
+
+    rmsnorm(d_input1.data(), d_weight.data(), d_output.data(), batch_size, hidden_dim, eps);
+
+    // Run in-place version
+    DeviceBuffer<half> d_input2(batch_size * hidden_dim);
+    d_input2.copyFromHost(input.data(), batch_size * hidden_dim);
+
+    rmsnorm_inplace(d_input2.data(), d_weight.data(), batch_size, hidden_dim, eps);
+
+    cudaDeviceSynchronize();
+
+    std::vector<half> output_oop(batch_size * hidden_dim);
+    std::vector<half> output_ip(batch_size * hidden_dim);
+    d_output.copyToHost(output_oop.data(), batch_size * hidden_dim);
+    d_input2.copyToHost(output_ip.data(), batch_size * hidden_dim);
+    cudaDeviceSynchronize();
+
+    // Property: In-place and out-of-place should produce same results
+    for (int i = 0; i < batch_size * hidden_dim; ++i) {
+        float v1 = __half2float(output_oop[i]);
+        float v2 = __half2float(output_ip[i]);
+        float diff = std::abs(v1 - v2);
+        float max_val = std::max(std::abs(v1), std::abs(v2));
+        float rel_diff = max_val > 1e-6f ? diff / max_val : diff;
+
+        // Allow small tolerance for floating point differences
+        RC_ASSERT(rel_diff < 0.01f);
+    }
 }
 
 // ============================================================================
@@ -408,128 +403,125 @@ RC_GTEST_FIXTURE_PROP(RMSNormPropertyTest, InPlaceEquivalence,
 #include "attention.cuh"
 
 class AttentionTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    if (err != cudaSuccess || device_count == 0) {
-      GTEST_SKIP() << "No CUDA device available";
-    }
-    cudaSetDevice(0);
-  }
-
-  void TearDown() override { cudaDeviceSynchronize(); }
-
-  // Generate random FP16 tensor
-  std::vector<half> randomFP16(int size, float scale = 1.0f,
-                               unsigned seed = 42) {
-    std::vector<half> data(size);
-    std::mt19937 gen(seed);
-    std::uniform_real_distribution<float> dist(-scale, scale);
-    for (auto &v : data) {
-      v = __float2half(dist(gen));
-    }
-    return data;
-  }
+  protected:
+    void SetUp() override {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        if (err != cudaSuccess || device_count == 0) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
+        cudaSetDevice(0);
+    }
+
+    void TearDown() override { cudaDeviceSynchronize(); }
+
+    // Generate random FP16 tensor
+    std::vector<half> randomFP16(int size, float scale = 1.0f, unsigned seed = 42) {
+        std::vector<half>                     data(size);
+        std::mt19937                          gen(seed);
+        std::uniform_real_distribution<float> dist(-scale, scale);
+        for (auto &v : data) {
+            v = __float2half(dist(gen));
+        }
+        return data;
+    }
 };
 
 // Unit tests for Attention
 TEST_F(AttentionTest, BasicDecodeAttention) {
-  int batch_size = 1;
-  int num_heads = 2;
-  int seq_len = 8;
-  int head_dim = 32;
-  float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
-
-  auto query = randomFP16(batch_size * num_heads * head_dim);
-  auto k_cache = randomFP16(batch_size * num_heads * seq_len * head_dim);
-  auto v_cache = randomFP16(batch_size * num_heads * seq_len * head_dim);
-
-  DeviceBuffer<half> d_query(batch_size * num_heads * head_dim);
-  DeviceBuffer<half> d_k_cache(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_v_cache(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_output(batch_size * num_heads * head_dim);
-
-  d_query.copyFromHost(query.data(), query.size());
-  d_k_cache.copyFromHost(k_cache.data(), k_cache.size());
-  d_v_cache.copyFromHost(v_cache.data(), v_cache.size());
-
-  EXPECT_NO_THROW({
-    attention_decode(d_query.data(), d_k_cache.data(), d_v_cache.data(),
-                     d_output.data(), scale, batch_size, num_heads, seq_len,
-                     head_dim);
+    int   batch_size = 1;
+    int   num_heads = 2;
+    int   seq_len = 8;
+    int   head_dim = 32;
+    float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
+
+    auto query = randomFP16(batch_size * num_heads * head_dim);
+    auto k_cache = randomFP16(batch_size * num_heads * seq_len * head_dim);
+    auto v_cache = randomFP16(batch_size * num_heads * seq_len * head_dim);
+
+    DeviceBuffer<half> d_query(batch_size * num_heads * head_dim);
+    DeviceBuffer<half> d_k_cache(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_v_cache(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_output(batch_size * num_heads * head_dim);
+
+    d_query.copyFromHost(query.data(), query.size());
+    d_k_cache.copyFromHost(k_cache.data(), k_cache.size());
+    d_v_cache.copyFromHost(v_cache.data(), v_cache.size());
+
+    EXPECT_NO_THROW({
+        attention_decode(d_query.data(), d_k_cache.data(), d_v_cache.data(), d_output.data(), scale,
+                         batch_size, num_heads, seq_len, head_dim);
+        cudaDeviceSynchronize();
+    });
+
+    std::vector<half> output(batch_size * num_heads * head_dim);
+    d_output.copyToHost(output.data(), output.size());
     cudaDeviceSynchronize();
-  });
 
-  std::vector<half> output(batch_size * num_heads * head_dim);
-  d_output.copyToHost(output.data(), output.size());
-  cudaDeviceSynchronize();
-
-  // Verify output is not all zeros
-  bool has_nonzero = false;
-  for (const auto &v : output) {
-    if (__half2float(v) != 0.0f) {
-      has_nonzero = true;
-      break;
+    // Verify output is not all zeros
+    bool has_nonzero = false;
+    for (const auto &v : output) {
+        if (__half2float(v) != 0.0f) {
+            has_nonzero = true;
+            break;
+        }
     }
-  }
-  EXPECT_TRUE(has_nonzero);
+    EXPECT_TRUE(has_nonzero);
 }
 
 TEST_F(AttentionTest, BasicPrefillAttention) {
-  int batch_size = 1;
-  int num_heads = 2;
-  int seq_len = 8;
-  int head_dim = 32;
-  float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
-
-  auto query = randomFP16(batch_size * num_heads * seq_len * head_dim);
-  auto key = randomFP16(batch_size * num_heads * seq_len * head_dim);
-  auto value = randomFP16(batch_size * num_heads * seq_len * head_dim);
-
-  DeviceBuffer<half> d_query(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_key(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_value(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_output(batch_size * num_heads * seq_len * head_dim);
-
-  d_query.copyFromHost(query.data(), query.size());
-  d_key.copyFromHost(key.data(), key.size());
-  d_value.copyFromHost(value.data(), value.size());
-
-  EXPECT_NO_THROW({
-    attention_prefill(d_query.data(), d_key.data(), d_value.data(),
-                      d_output.data(), scale, batch_size, num_heads, seq_len,
-                      head_dim);
-    cudaDeviceSynchronize();
-  });
+    int   batch_size = 1;
+    int   num_heads = 2;
+    int   seq_len = 8;
+    int   head_dim = 32;
+    float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
+
+    auto query = randomFP16(batch_size * num_heads * seq_len * head_dim);
+    auto key = randomFP16(batch_size * num_heads * seq_len * head_dim);
+    auto value = randomFP16(batch_size * num_heads * seq_len * head_dim);
+
+    DeviceBuffer<half> d_query(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_key(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_value(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_output(batch_size * num_heads * seq_len * head_dim);
+
+    d_query.copyFromHost(query.data(), query.size());
+    d_key.copyFromHost(key.data(), key.size());
+    d_value.copyFromHost(value.data(), value.size());
+
+    EXPECT_NO_THROW({
+        attention_prefill(d_query.data(), d_key.data(), d_value.data(), d_output.data(), scale,
+                          batch_size, num_heads, seq_len, head_dim);
+        cudaDeviceSynchronize();
+    });
 }
 
 TEST_F(AttentionTest, SoftmaxSumsToOne) {
-  int batch_size = 4;
-  int seq_len = 16;
+    int batch_size = 4;
+    int seq_len = 16;
 
-  auto input = randomFP16(batch_size * seq_len, 2.0f);
+    auto input = randomFP16(batch_size * seq_len, 2.0f);
 
-  DeviceBuffer<half> d_input(batch_size * seq_len);
-  DeviceBuffer<half> d_output(batch_size * seq_len);
+    DeviceBuffer<half> d_input(batch_size * seq_len);
+    DeviceBuffer<half> d_output(batch_size * seq_len);
 
-  d_input.copyFromHost(input.data(), input.size());
+    d_input.copyFromHost(input.data(), input.size());
 
-  softmax(d_input.data(), d_output.data(), batch_size, seq_len);
-  cudaDeviceSynchronize();
+    softmax(d_input.data(), d_output.data(), batch_size, seq_len);
+    cudaDeviceSynchronize();
 
-  std::vector<half> output(batch_size * seq_len);
-  d_output.copyToHost(output.data(), output.size());
-  cudaDeviceSynchronize();
+    std::vector<half> output(batch_size * seq_len);
+    d_output.copyToHost(output.data(), output.size());
+    cudaDeviceSynchronize();
 
-  // Verify each row sums to approximately 1.0
-  for (int b = 0; b < batch_size; ++b) {
-    float sum = 0.0f;
-    for (int i = 0; i < seq_len; ++i) {
-      sum += __half2float(output[b * seq_len + i]);
+    // Verify each row sums to approximately 1.0
+    for (int b = 0; b < batch_size; ++b) {
+        float sum = 0.0f;
+        for (int i = 0; i < seq_len; ++i) {
+            sum += __half2float(output[b * seq_len + i]);
+        }
+        EXPECT_NEAR(sum, 1.0f, 0.01f) << "Row " << b << " sum: " << sum;
     }
-    EXPECT_NEAR(sum, 1.0f, 0.01f) << "Row " << b << " sum: " << sum;
-  }
 }
 
 // Property-based tests
@@ -537,15 +529,19 @@ TEST_F(AttentionTest, SoftmaxSumsToOne) {
 // Validates: Requirements 4.2
 // NOTE: Property-based tests are disabled when no CUDA device is available
 
-class AttentionPropertyTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    if (!hasCudaDevice()) {
-      GTEST_SKIP() << "No CUDA device available";
+class AttentionPropertyTest : public AttentionTest {
+  protected:
+    void SetUp() override {
+        if (hasCudaDevice()) {
+            cudaSetDevice(0);
+        }
+    }
+
+    void TearDown() override {
+        if (hasCudaDevice()) {
+            cudaDeviceSynchronize();
+        }
     }
-    cudaSetDevice(0);
-  }
-  void TearDown() override { cudaDeviceSynchronize(); }
 };
 
 // Property 3: Causal Masking Correctness
@@ -554,196 +550,189 @@ protected:
 // future tokens.
 
 RC_GTEST_FIXTURE_PROP(AttentionPropertyTest, CausalMaskZerosFuturePositions,
-                      (int batch_raw, int heads_raw, int seq_raw, int dim_raw,
-                       unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions to reasonable ranges
-  int batch_size = 1 + (std::abs(batch_raw) % 4);
-  int num_heads = 1 + (std::abs(heads_raw) % 8);
-  int seq_len = 4 + (std::abs(seq_raw) % 60);   // 4 to 64
-  int head_dim = 16 + (std::abs(dim_raw) % 48); // 16 to 64
-  float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
-
-  // Generate random Q and K
-  auto query =
-      randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, seed);
-  auto key =
-      randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, seed + 1);
-
-  DeviceBuffer<half> d_query(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_key(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_weights(batch_size * num_heads * seq_len * seq_len);
-
-  d_query.copyFromHost(query.data(), query.size());
-  d_key.copyFromHost(key.data(), key.size());
-
-  // Get attention weights with causal mask
-  get_attention_weights(d_query.data(), d_key.data(), d_weights.data(), scale,
-                        batch_size, num_heads, seq_len, seq_len, head_dim,
-                        true); // apply_causal_mask = true
-
-  cudaDeviceSynchronize();
-
-  std::vector<half> weights(batch_size * num_heads * seq_len * seq_len);
-  d_weights.copyToHost(weights.data(), weights.size());
-  cudaDeviceSynchronize();
-
-  // Property: For each query position t, weights for key positions > t must be
-  // zero
-  for (int b = 0; b < batch_size; ++b) {
-    for (int h = 0; h < num_heads; ++h) {
-      for (int q_pos = 0; q_pos < seq_len; ++q_pos) {
-        for (int k_pos = q_pos + 1; k_pos < seq_len; ++k_pos) {
-          int idx = ((b * num_heads + h) * seq_len + q_pos) * seq_len + k_pos;
-          float weight = __half2float(weights[idx]);
-
-          // Future positions must have zero weight
-          RC_ASSERT(weight == 0.0f);
+                      (int batch_raw, int heads_raw, int seq_raw, int dim_raw, unsigned seed)) {
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions to reasonable ranges
+    int   batch_size = 1 + (std::abs(batch_raw) % 4);
+    int   num_heads = 1 + (std::abs(heads_raw) % 8);
+    int   seq_len = 4 + (std::abs(seq_raw) % 60);   // 4 to 64
+    int   head_dim = 16 + (std::abs(dim_raw) % 48); // 16 to 64
+    float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
+
+    // Generate random Q and K
+    auto query = randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, seed);
+    auto key = randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, seed + 1);
+
+    DeviceBuffer<half> d_query(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_key(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_weights(batch_size * num_heads * seq_len * seq_len);
+
+    d_query.copyFromHost(query.data(), query.size());
+    d_key.copyFromHost(key.data(), key.size());
+
+    // Get attention weights with causal mask
+    get_attention_weights(d_query.data(), d_key.data(), d_weights.data(), scale, batch_size,
+                          num_heads, seq_len, seq_len, head_dim,
+                          true); // apply_causal_mask = true
+
+    cudaDeviceSynchronize();
+
+    std::vector<half> weights(batch_size * num_heads * seq_len * seq_len);
+    d_weights.copyToHost(weights.data(), weights.size());
+    cudaDeviceSynchronize();
+
+    // Property: For each query position t, weights for key positions > t must be
+    // zero
+    for (int b = 0; b < batch_size; ++b) {
+        for (int h = 0; h < num_heads; ++h) {
+            for (int q_pos = 0; q_pos < seq_len; ++q_pos) {
+                for (int k_pos = q_pos + 1; k_pos < seq_len; ++k_pos) {
+                    int   idx = ((b * num_heads + h) * seq_len + q_pos) * seq_len + k_pos;
+                    float weight = __half2float(weights[idx]);
+
+                    // Future positions must have zero weight
+                    RC_ASSERT(weight == 0.0f);
+                }
+            }
         }
-      }
     }
-  }
 }
 
 RC_GTEST_FIXTURE_PROP(AttentionPropertyTest, CausalMaskAllowsPastPositions,
-                      (int batch_raw, int heads_raw, int seq_raw, int dim_raw,
-                       unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions
-  int batch_size = 1 + (std::abs(batch_raw) % 4);
-  int num_heads = 1 + (std::abs(heads_raw) % 4);
-  int seq_len = 4 + (std::abs(seq_raw) % 28); // 4 to 32
-  int head_dim = 16 + (std::abs(dim_raw) % 48);
-  float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
-
-  // Generate random Q and K with non-zero values
-  auto query =
-      randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, seed);
-  auto key =
-      randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, seed + 1);
-
-  DeviceBuffer<half> d_query(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_key(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_weights(batch_size * num_heads * seq_len * seq_len);
-
-  d_query.copyFromHost(query.data(), query.size());
-  d_key.copyFromHost(key.data(), key.size());
-
-  // Get attention weights with causal mask
-  get_attention_weights(d_query.data(), d_key.data(), d_weights.data(), scale,
-                        batch_size, num_heads, seq_len, seq_len, head_dim,
-                        true);
-
-  cudaDeviceSynchronize();
-
-  std::vector<half> weights(batch_size * num_heads * seq_len * seq_len);
-  d_weights.copyToHost(weights.data(), weights.size());
-  cudaDeviceSynchronize();
-
-  // Property: For each query position t, at least one weight for positions <= t
-  // should be non-zero (unless all Q*K products happen to be exactly zero,
-  // which is extremely unlikely)
-  for (int b = 0; b < batch_size; ++b) {
-    for (int h = 0; h < num_heads; ++h) {
-      for (int q_pos = 0; q_pos < seq_len; ++q_pos) {
-        bool has_nonzero = false;
-        for (int k_pos = 0; k_pos <= q_pos; ++k_pos) {
-          int idx = ((b * num_heads + h) * seq_len + q_pos) * seq_len + k_pos;
-          float weight = __half2float(weights[idx]);
-          if (weight != 0.0f) {
-            has_nonzero = true;
-            break;
-          }
+                      (int batch_raw, int heads_raw, int seq_raw, int dim_raw, unsigned seed)) {
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions
+    int   batch_size = 1 + (std::abs(batch_raw) % 4);
+    int   num_heads = 1 + (std::abs(heads_raw) % 4);
+    int   seq_len = 4 + (std::abs(seq_raw) % 28); // 4 to 32
+    int   head_dim = 16 + (std::abs(dim_raw) % 48);
+    float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
+
+    // Generate random Q and K with non-zero values
+    auto query = randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, seed);
+    auto key = randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, seed + 1);
+
+    DeviceBuffer<half> d_query(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_key(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_weights(batch_size * num_heads * seq_len * seq_len);
+
+    d_query.copyFromHost(query.data(), query.size());
+    d_key.copyFromHost(key.data(), key.size());
+
+    // Get attention weights with causal mask
+    get_attention_weights(d_query.data(), d_key.data(), d_weights.data(), scale, batch_size,
+                          num_heads, seq_len, seq_len, head_dim, true);
+
+    cudaDeviceSynchronize();
+
+    std::vector<half> weights(batch_size * num_heads * seq_len * seq_len);
+    d_weights.copyToHost(weights.data(), weights.size());
+    cudaDeviceSynchronize();
+
+    // Property: For each query position t, at least one weight for positions <= t
+    // should be non-zero (unless all Q*K products happen to be exactly zero,
+    // which is extremely unlikely)
+    for (int b = 0; b < batch_size; ++b) {
+        for (int h = 0; h < num_heads; ++h) {
+            for (int q_pos = 0; q_pos < seq_len; ++q_pos) {
+                bool has_nonzero = false;
+                for (int k_pos = 0; k_pos <= q_pos; ++k_pos) {
+                    int   idx = ((b * num_heads + h) * seq_len + q_pos) * seq_len + k_pos;
+                    float weight = __half2float(weights[idx]);
+                    if (weight != 0.0f) {
+                        has_nonzero = true;
+                        break;
+                    }
+                }
+                // Past/current positions should have non-zero weights
+                RC_ASSERT(has_nonzero);
+            }
         }
-        // Past/current positions should have non-zero weights
-        RC_ASSERT(has_nonzero);
-      }
     }
-  }
 }
 
 RC_GTEST_FIXTURE_PROP(AttentionPropertyTest, SoftmaxOutputSumsToOne,
                       (int batch_raw, int seq_raw, unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions
-  int batch_size = 1 + (std::abs(batch_raw) % 16);
-  int seq_len = 4 + (std::abs(seq_raw) % 124); // 4 to 128
-
-  // Generate random input
-  auto input = randomFP16(batch_size * seq_len, 2.0f, seed);
-
-  DeviceBuffer<half> d_input(batch_size * seq_len);
-  DeviceBuffer<half> d_output(batch_size * seq_len);
-
-  d_input.copyFromHost(input.data(), input.size());
-
-  softmax(d_input.data(), d_output.data(), batch_size, seq_len);
-  cudaDeviceSynchronize();
-
-  std::vector<half> output(batch_size * seq_len);
-  d_output.copyToHost(output.data(), output.size());
-  cudaDeviceSynchronize();
-
-  // Property: Each row should sum to approximately 1.0
-  for (int b = 0; b < batch_size; ++b) {
-    float sum = 0.0f;
-    for (int i = 0; i < seq_len; ++i) {
-      float val = __half2float(output[b * seq_len + i]);
-      RC_ASSERT(val >= 0.0f); // Softmax outputs should be non-negative
-      sum += val;
-    }
-    // Sum should be close to 1.0 (within FP16 tolerance)
-    RC_ASSERT(sum > 0.98f && sum < 1.02f);
-  }
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions
+    int batch_size = 1 + (std::abs(batch_raw) % 16);
+    int seq_len = 4 + (std::abs(seq_raw) % 124); // 4 to 128
+
+    // Generate random input
+    auto input = randomFP16(batch_size * seq_len, 2.0f, seed);
+
+    DeviceBuffer<half> d_input(batch_size * seq_len);
+    DeviceBuffer<half> d_output(batch_size * seq_len);
+
+    d_input.copyFromHost(input.data(), input.size());
+
+    softmax(d_input.data(), d_output.data(), batch_size, seq_len);
+    cudaDeviceSynchronize();
+
+    std::vector<half> output(batch_size * seq_len);
+    d_output.copyToHost(output.data(), output.size());
+    cudaDeviceSynchronize();
+
+    // Property: Each row should sum to approximately 1.0
+    for (int b = 0; b < batch_size; ++b) {
+        float sum = 0.0f;
+        for (int i = 0; i < seq_len; ++i) {
+            float val = __half2float(output[b * seq_len + i]);
+            RC_ASSERT(val >= 0.0f); // Softmax outputs should be non-negative
+            sum += val;
+        }
+        // Sum should be close to 1.0 (within FP16 tolerance)
+        RC_ASSERT(sum > 0.98f && sum < 1.02f);
+    }
 }
 
 RC_GTEST_FIXTURE_PROP(AttentionPropertyTest, SoftmaxPreservesOrder,
                       (int batch_raw, int seq_raw, unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions
-  int batch_size = 1 + (std::abs(batch_raw) % 8);
-  int seq_len = 4 + (std::abs(seq_raw) % 60);
-
-  // Generate random input
-  auto input = randomFP16(batch_size * seq_len, 2.0f, seed);
-
-  DeviceBuffer<half> d_input(batch_size * seq_len);
-  DeviceBuffer<half> d_output(batch_size * seq_len);
-
-  d_input.copyFromHost(input.data(), input.size());
-
-  softmax(d_input.data(), d_output.data(), batch_size, seq_len);
-  cudaDeviceSynchronize();
-
-  std::vector<half> output(batch_size * seq_len);
-  d_output.copyToHost(output.data(), output.size());
-  cudaDeviceSynchronize();
-
-  // Property: Softmax should preserve relative ordering
-  // If input[i] > input[j], then output[i] > output[j]
-  for (int b = 0; b < batch_size; ++b) {
-    for (int i = 0; i < seq_len; ++i) {
-      for (int j = i + 1; j < seq_len; ++j) {
-        float in_i = __half2float(input[b * seq_len + i]);
-        float in_j = __half2float(input[b * seq_len + j]);
-        float out_i = __half2float(output[b * seq_len + i]);
-        float out_j = __half2float(output[b * seq_len + j]);
-
-        // If inputs differ significantly, outputs should maintain order
-        if (in_i > in_j + 0.1f) {
-          RC_ASSERT(out_i >= out_j);
-        } else if (in_j > in_i + 0.1f) {
-          RC_ASSERT(out_j >= out_i);
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions
+    int batch_size = 1 + (std::abs(batch_raw) % 8);
+    int seq_len = 4 + (std::abs(seq_raw) % 60);
+
+    // Generate random input
+    auto input = randomFP16(batch_size * seq_len, 2.0f, seed);
+
+    DeviceBuffer<half> d_input(batch_size * seq_len);
+    DeviceBuffer<half> d_output(batch_size * seq_len);
+
+    d_input.copyFromHost(input.data(), input.size());
+
+    softmax(d_input.data(), d_output.data(), batch_size, seq_len);
+    cudaDeviceSynchronize();
+
+    std::vector<half> output(batch_size * seq_len);
+    d_output.copyToHost(output.data(), output.size());
+    cudaDeviceSynchronize();
+
+    // Property: Softmax should preserve relative ordering
+    // If input[i] > input[j], then output[i] > output[j]
+    for (int b = 0; b < batch_size; ++b) {
+        for (int i = 0; i < seq_len; ++i) {
+            for (int j = i + 1; j < seq_len; ++j) {
+                float in_i = __half2float(input[b * seq_len + i]);
+                float in_j = __half2float(input[b * seq_len + j]);
+                float out_i = __half2float(output[b * seq_len + i]);
+                float out_j = __half2float(output[b * seq_len + j]);
+
+                // If inputs differ significantly, outputs should maintain order
+                if (in_i > in_j + 0.1f) {
+                    RC_ASSERT(out_i >= out_j);
+                } else if (in_j > in_i + 0.1f) {
+                    RC_ASSERT(out_j >= out_i);
+                }
+            }
         }
-      }
     }
-  }
 }
diff --git a/tests/test_kv_cache.cpp b/tests/test_kv_cache.cpp
index 5f0dedb..9d0a124 100644
--- a/tests/test_kv_cache.cpp
+++ b/tests/test_kv_cache.cpp
@@ -8,262 +8,261 @@
 using namespace tiny_llm;
 
 class KVCacheTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    if (err != cudaSuccess || device_count == 0) {
-      GTEST_SKIP() << "No CUDA device available";
+  protected:
+    void SetUp() override {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        if (err != cudaSuccess || device_count == 0) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
+        cudaSetDevice(0);
     }
-    cudaSetDevice(0);
-  }
 
-  void TearDown() override { cudaDeviceSynchronize(); }
-
-  KVCacheConfig createConfig(int num_layers = 2, int num_heads = 4,
-                             int head_dim = 64, int max_seq_len = 128,
-                             int max_batch_size = 4) {
-    KVCacheConfig config;
-    config.num_layers = num_layers;
-    config.num_heads = num_heads;
-    config.head_dim = head_dim;
-    config.max_seq_len = max_seq_len;
-    config.max_batch_size = max_batch_size;
-    return config;
-  }
+    void TearDown() override { cudaDeviceSynchronize(); }
+
+    KVCacheConfig createConfig(int num_layers = 2, int num_heads = 4, int head_dim = 64,
+                               int max_seq_len = 128, int max_batch_size = 4) {
+        KVCacheConfig config;
+        config.num_layers = num_layers;
+        config.num_heads = num_heads;
+        config.head_dim = head_dim;
+        config.max_seq_len = max_seq_len;
+        config.max_batch_size = max_batch_size;
+        return config;
+    }
 };
 
 // Unit tests
 TEST_F(KVCacheTest, InitializationAllocatesMemory) {
-  auto config = createConfig();
-  KVCacheManager cache(config);
+    auto           config = createConfig();
+    KVCacheManager cache(config);
 
-  EXPECT_GT(cache.getTotalMemory(), 0);
-  EXPECT_EQ(cache.getUsedMemory(), 0);
-  EXPECT_EQ(cache.getActiveSequenceCount(), 0);
+    EXPECT_GT(cache.getTotalMemory(), 0);
+    EXPECT_EQ(cache.getUsedMemory(), 0);
+    EXPECT_EQ(cache.getActiveSequenceCount(), 0);
 }
 
 TEST_F(KVCacheTest, AllocateSequenceReturnsValidId) {
-  auto config = createConfig();
-  KVCacheManager cache(config);
+    auto           config = createConfig();
+    KVCacheManager cache(config);
 
-  auto result = cache.allocateSequence(64);
-  ASSERT_TRUE(result.isOk());
+    auto result = cache.allocateSequence(64);
+    ASSERT_TRUE(result.isOk());
 
-  int seq_id = result.value();
-  EXPECT_GE(seq_id, 0);
-  EXPECT_TRUE(cache.hasSequence(seq_id));
-  EXPECT_EQ(cache.getSeqLen(seq_id), 0);
+    int seq_id = result.value();
+    EXPECT_GE(seq_id, 0);
+    EXPECT_TRUE(cache.hasSequence(seq_id));
+    EXPECT_EQ(cache.getSeqLen(seq_id), 0);
 }
 
 TEST_F(KVCacheTest, AllocateMultipleSequences) {
-  auto config = createConfig(2, 4, 64, 128, 4);
-  KVCacheManager cache(config);
-
-  std::vector<int> seq_ids;
-  for (int i = 0; i < 4; ++i) {
-    auto result = cache.allocateSequence(64);
-    ASSERT_TRUE(result.isOk());
-    seq_ids.push_back(result.value());
-  }
+    auto           config = createConfig(2, 4, 64, 128, 4);
+    KVCacheManager cache(config);
+
+    std::vector<int> seq_ids;
+    for (int i = 0; i < 4; ++i) {
+        auto result = cache.allocateSequence(64);
+        ASSERT_TRUE(result.isOk());
+        seq_ids.push_back(result.value());
+    }
 
-  EXPECT_EQ(cache.getActiveSequenceCount(), 4);
+    EXPECT_EQ(cache.getActiveSequenceCount(), 4);
 
-  // All IDs should be unique
-  std::sort(seq_ids.begin(), seq_ids.end());
-  auto last = std::unique(seq_ids.begin(), seq_ids.end());
-  EXPECT_EQ(last, seq_ids.end());
+    // All IDs should be unique
+    std::sort(seq_ids.begin(), seq_ids.end());
+    auto last = std::unique(seq_ids.begin(), seq_ids.end());
+    EXPECT_EQ(last, seq_ids.end());
 }
 
 TEST_F(KVCacheTest, ExhaustionReturnsError) {
-  auto config = createConfig(2, 4, 64, 128, 2); // Only 2 slots
-  KVCacheManager cache(config);
+    auto           config = createConfig(2, 4, 64, 128, 2); // Only 2 slots
+    KVCacheManager cache(config);
 
-  // Allocate all slots
-  ASSERT_TRUE(cache.allocateSequence(64).isOk());
-  ASSERT_TRUE(cache.allocateSequence(64).isOk());
+    // Allocate all slots
+    ASSERT_TRUE(cache.allocateSequence(64).isOk());
+    ASSERT_TRUE(cache.allocateSequence(64).isOk());
 
-  // Third allocation should fail
-  auto result = cache.allocateSequence(64);
-  EXPECT_TRUE(result.isErr());
-  EXPECT_TRUE(result.error().find("exhausted") != std::string::npos);
+    // Third allocation should fail
+    auto result = cache.allocateSequence(64);
+    EXPECT_TRUE(result.isErr());
+    EXPECT_TRUE(result.error().find("exhausted") != std::string::npos);
 }
 
 TEST_F(KVCacheTest, ReleaseSequenceFreesSlot) {
-  auto config = createConfig(2, 4, 64, 128, 2);
-  KVCacheManager cache(config);
+    auto           config = createConfig(2, 4, 64, 128, 2);
+    KVCacheManager cache(config);
 
-  auto r1 = cache.allocateSequence(64);
-  auto r2 = cache.allocateSequence(64);
-  ASSERT_TRUE(r1.isOk());
-  ASSERT_TRUE(r2.isOk());
+    auto r1 = cache.allocateSequence(64);
+    auto r2 = cache.allocateSequence(64);
+    ASSERT_TRUE(r1.isOk());
+    ASSERT_TRUE(r2.isOk());
 
-  int seq1 = r1.value();
+    int seq1 = r1.value();
 
-  // Release first sequence
-  cache.releaseSequence(seq1);
-  EXPECT_FALSE(cache.hasSequence(seq1));
-  EXPECT_EQ(cache.getActiveSequenceCount(), 1);
+    // Release first sequence
+    cache.releaseSequence(seq1);
+    EXPECT_FALSE(cache.hasSequence(seq1));
+    EXPECT_EQ(cache.getActiveSequenceCount(), 1);
 
-  // Should be able to allocate again
-  auto r3 = cache.allocateSequence(64);
-  EXPECT_TRUE(r3.isOk());
+    // Should be able to allocate again
+    auto r3 = cache.allocateSequence(64);
+    EXPECT_TRUE(r3.isOk());
 }
 
 TEST_F(KVCacheTest, GetCacheReturnsValidPointers) {
-  auto config = createConfig();
-  KVCacheManager cache(config);
+    auto           config = createConfig();
+    KVCacheManager cache(config);
 
-  auto result = cache.allocateSequence(64);
-  ASSERT_TRUE(result.isOk());
-  int seq_id = result.value();
-
-  for (int layer = 0; layer < config.num_layers; ++layer) {
-    auto [k_cache, v_cache] = cache.getCache(seq_id, layer);
-    EXPECT_NE(k_cache, nullptr);
-    EXPECT_NE(v_cache, nullptr);
-    EXPECT_NE(k_cache, v_cache); // K and V should be different
-  }
+    auto result = cache.allocateSequence(64);
+    ASSERT_TRUE(result.isOk());
+    int seq_id = result.value();
+
+    for (int layer = 0; layer < config.num_layers; ++layer) {
+        auto [k_cache, v_cache] = cache.getCache(seq_id, layer);
+        EXPECT_NE(k_cache, nullptr);
+        EXPECT_NE(v_cache, nullptr);
+        EXPECT_NE(k_cache, v_cache); // K and V should be different
+    }
 }
 
 TEST_F(KVCacheTest, GetCacheForInvalidSequenceReturnsNull) {
-  auto config = createConfig();
-  KVCacheManager cache(config);
+    auto           config = createConfig();
+    KVCacheManager cache(config);
 
-  auto [k_cache, v_cache] = cache.getCache(999, 0);
-  EXPECT_EQ(k_cache, nullptr);
-  EXPECT_EQ(v_cache, nullptr);
+    auto [k_cache, v_cache] = cache.getCache(999, 0);
+    EXPECT_EQ(k_cache, nullptr);
+    EXPECT_EQ(v_cache, nullptr);
 }
 
 TEST_F(KVCacheTest, InvalidMaxLenReturnsError) {
-  auto config = createConfig(2, 4, 64, 128, 4);
-  KVCacheManager cache(config);
+    auto           config = createConfig(2, 4, 64, 128, 4);
+    KVCacheManager cache(config);
 
-  // Zero length
-  auto r1 = cache.allocateSequence(0);
-  EXPECT_TRUE(r1.isErr());
+    // Zero length
+    auto r1 = cache.allocateSequence(0);
+    EXPECT_TRUE(r1.isErr());
 
-  // Negative length
-  auto r2 = cache.allocateSequence(-1);
-  EXPECT_TRUE(r2.isErr());
+    // Negative length
+    auto r2 = cache.allocateSequence(-1);
+    EXPECT_TRUE(r2.isErr());
 
-  // Exceeds max
-  auto r3 = cache.allocateSequence(256);
-  EXPECT_TRUE(r3.isErr());
+    // Exceeds max
+    auto r3 = cache.allocateSequence(256);
+    EXPECT_TRUE(r3.isErr());
 }
 
 TEST_F(KVCacheTest, MemoryAccountingIsCorrect) {
-  auto config = createConfig(2, 4, 64, 128, 4);
-  KVCacheManager cache(config);
+    auto           config = createConfig(2, 4, 64, 128, 4);
+    KVCacheManager cache(config);
 
-  size_t initial_free = cache.getFreeMemory();
-  size_t total = cache.getTotalMemory();
+    size_t initial_free = cache.getFreeMemory();
+    size_t total = cache.getTotalMemory();
 
-  EXPECT_EQ(initial_free, total);
-  EXPECT_EQ(cache.getUsedMemory(), 0);
+    EXPECT_EQ(initial_free, total);
+    EXPECT_EQ(cache.getUsedMemory(), 0);
 
-  // Allocate one sequence
-  auto r1 = cache.allocateSequence(64);
-  ASSERT_TRUE(r1.isOk());
+    // Allocate one sequence
+    auto r1 = cache.allocateSequence(64);
+    ASSERT_TRUE(r1.isOk());
 
-  size_t used_after_one = cache.getUsedMemory();
-  EXPECT_GT(used_after_one, 0);
-  EXPECT_EQ(cache.getFreeMemory(), total - used_after_one);
+    size_t used_after_one = cache.getUsedMemory();
+    EXPECT_GT(used_after_one, 0);
+    EXPECT_EQ(cache.getFreeMemory(), total - used_after_one);
 
-  // Allocate another
-  auto r2 = cache.allocateSequence(64);
-  ASSERT_TRUE(r2.isOk());
+    // Allocate another
+    auto r2 = cache.allocateSequence(64);
+    ASSERT_TRUE(r2.isOk());
 
-  size_t used_after_two = cache.getUsedMemory();
-  EXPECT_EQ(used_after_two, used_after_one * 2);
+    size_t used_after_two = cache.getUsedMemory();
+    EXPECT_EQ(used_after_two, used_after_one * 2);
 }
 
 TEST_F(KVCacheTest, AppendDoesNotAdvanceVisibleSequenceLength) {
-  auto config = createConfig(2, 4, 8, 32, 2);
-  KVCacheManager cache(config);
+    auto           config = createConfig(2, 4, 8, 32, 2);
+    KVCacheManager cache(config);
 
-  auto result = cache.allocateSequence(16);
-  ASSERT_TRUE(result.isOk());
-  int seq_id = result.value();
-
-  int num_tokens = 3;
-  size_t elements = static_cast<size_t>(num_tokens) * config.num_heads * config.head_dim;
-  std::vector<half> host_k(elements, __float2half(1.0f));
-  std::vector<half> host_v(elements, __float2half(2.0f));
-  half *device_k = nullptr;
-  half *device_v = nullptr;
-  cudaMalloc(&device_k, elements * sizeof(half));
-  cudaMalloc(&device_v, elements * sizeof(half));
-  cudaMemcpy(device_k, host_k.data(), elements * sizeof(half), cudaMemcpyHostToDevice);
-  cudaMemcpy(device_v, host_v.data(), elements * sizeof(half), cudaMemcpyHostToDevice);
-
-  cache.appendKV(seq_id, 0, device_k, device_v, num_tokens);
-  cudaDeviceSynchronize();
-  EXPECT_EQ(cache.getSeqLen(seq_id), 0);
-
-  cache.advanceSeqLen(seq_id, num_tokens);
-  EXPECT_EQ(cache.getSeqLen(seq_id), num_tokens);
-
-  cudaFree(device_k);
-  cudaFree(device_v);
+    auto result = cache.allocateSequence(16);
+    ASSERT_TRUE(result.isOk());
+    int seq_id = result.value();
+
+    int    num_tokens = 3;
+    size_t elements = static_cast<size_t>(num_tokens) * config.num_heads * config.head_dim;
+    std::vector<half> host_k(elements, __float2half(1.0f));
+    std::vector<half> host_v(elements, __float2half(2.0f));
+    half             *device_k = nullptr;
+    half             *device_v = nullptr;
+    cudaMalloc(&device_k, elements * sizeof(half));
+    cudaMalloc(&device_v, elements * sizeof(half));
+    cudaMemcpy(device_k, host_k.data(), elements * sizeof(half), cudaMemcpyHostToDevice);
+    cudaMemcpy(device_v, host_v.data(), elements * sizeof(half), cudaMemcpyHostToDevice);
+
+    cache.appendKV(seq_id, 0, device_k, device_v, num_tokens);
+    cudaDeviceSynchronize();
+    EXPECT_EQ(cache.getSeqLen(seq_id), 0);
+
+    cache.advanceSeqLen(seq_id, num_tokens);
+    EXPECT_EQ(cache.getSeqLen(seq_id), num_tokens);
+
+    cudaFree(device_k);
+    cudaFree(device_v);
 }
 
 TEST_F(KVCacheTest, InvalidLayerReturnsNullCachePointers) {
-  auto config = createConfig(2, 4, 8, 32, 2);
-  KVCacheManager cache(config);
+    auto           config = createConfig(2, 4, 8, 32, 2);
+    KVCacheManager cache(config);
 
-  auto result = cache.allocateSequence(16);
-  ASSERT_TRUE(result.isOk());
-  int seq_id = result.value();
+    auto result = cache.allocateSequence(16);
+    ASSERT_TRUE(result.isOk());
+    int seq_id = result.value();
 
-  auto [k_cache, v_cache] = cache.getCache(seq_id, -1);
-  EXPECT_EQ(k_cache, nullptr);
-  EXPECT_EQ(v_cache, nullptr);
+    auto [k_cache, v_cache] = cache.getCache(seq_id, -1);
+    EXPECT_EQ(k_cache, nullptr);
+    EXPECT_EQ(v_cache, nullptr);
 
-  auto [k_cache2, v_cache2] = cache.getCache(seq_id, config.num_layers);
-  EXPECT_EQ(k_cache2, nullptr);
-  EXPECT_EQ(v_cache2, nullptr);
+    auto [k_cache2, v_cache2] = cache.getCache(seq_id, config.num_layers);
+    EXPECT_EQ(k_cache2, nullptr);
+    EXPECT_EQ(v_cache2, nullptr);
 }
 
 TEST_F(KVCacheTest, InvalidAppendInputsDoNotAdvanceSequenceLength) {
-  auto config = createConfig(2, 4, 8, 32, 2);
-  KVCacheManager cache(config);
+    auto           config = createConfig(2, 4, 8, 32, 2);
+    KVCacheManager cache(config);
 
-  auto result = cache.allocateSequence(16);
-  ASSERT_TRUE(result.isOk());
-  int seq_id = result.value();
+    auto result = cache.allocateSequence(16);
+    ASSERT_TRUE(result.isOk());
+    int seq_id = result.value();
 
-  cache.appendKV(seq_id, -1, nullptr, nullptr, 0);
-  cache.appendKV(seq_id, config.num_layers, nullptr, nullptr, 1);
-  cache.appendKV(seq_id, 0, nullptr, nullptr, 1);
-  cudaDeviceSynchronize();
+    cache.appendKV(seq_id, -1, nullptr, nullptr, 0);
+    cache.appendKV(seq_id, config.num_layers, nullptr, nullptr, 1);
+    cache.appendKV(seq_id, 0, nullptr, nullptr, 1);
+    cudaDeviceSynchronize();
 
-  EXPECT_EQ(cache.getSeqLen(seq_id), 0);
+    EXPECT_EQ(cache.getSeqLen(seq_id), 0);
 }
 
 TEST_F(KVCacheTest, AdvanceSeqLenClampsToSequenceCapacity) {
-  auto config = createConfig(2, 4, 8, 32, 2);
-  KVCacheManager cache(config);
+    auto           config = createConfig(2, 4, 8, 32, 2);
+    KVCacheManager cache(config);
 
-  auto result = cache.allocateSequence(5);
-  ASSERT_TRUE(result.isOk());
-  int seq_id = result.value();
+    auto result = cache.allocateSequence(5);
+    ASSERT_TRUE(result.isOk());
+    int seq_id = result.value();
 
-  cache.advanceSeqLen(seq_id, 100);
-  EXPECT_EQ(cache.getSeqLen(seq_id), 5);
+    cache.advanceSeqLen(seq_id, 100);
+    EXPECT_EQ(cache.getSeqLen(seq_id), 5);
 }
 
 TEST_F(KVCacheTest, AdvanceSeqLenIgnoresNonPositiveValues) {
-  auto config = createConfig(2, 4, 8, 32, 2);
-  KVCacheManager cache(config);
+    auto           config = createConfig(2, 4, 8, 32, 2);
+    KVCacheManager cache(config);
 
-  auto result = cache.allocateSequence(5);
-  ASSERT_TRUE(result.isOk());
-  int seq_id = result.value();
+    auto result = cache.allocateSequence(5);
+    ASSERT_TRUE(result.isOk());
+    int seq_id = result.value();
 
-  cache.advanceSeqLen(seq_id, 0);
-  cache.advanceSeqLen(seq_id, -3);
-  EXPECT_EQ(cache.getSeqLen(seq_id), 0);
+    cache.advanceSeqLen(seq_id, 0);
+    cache.advanceSeqLen(seq_id, -3);
+    EXPECT_EQ(cache.getSeqLen(seq_id), 0);
 }
 
 // Property-based tests
diff --git a/tests/test_main.cpp b/tests/test_main.cpp
index 1de1eab..6ce9895 100644
--- a/tests/test_main.cpp
+++ b/tests/test_main.cpp
@@ -2,6 +2,6 @@
 
 // Main entry point for all tests
 int main(int argc, char **argv) {
-  ::testing::InitGoogleTest(&argc, argv);
-  return RUN_ALL_TESTS();
+    ::testing::InitGoogleTest(&argc, argv);
+    return RUN_ALL_TESTS();
 }
diff --git a/tests/test_model_loader.cpp b/tests/test_model_loader.cpp
index 6ebb84f..88c0783 100644
--- a/tests/test_model_loader.cpp
+++ b/tests/test_model_loader.cpp
@@ -9,303 +9,301 @@
 #include <rapidcheck/gtest.h>
 #include <string>
 #include <vector>
-# ifdef _WIN32
+#ifdef _WIN32
 #include <process.h>
-# else
+#else
 #include <unistd.h>
-# endif
+#endif
 
 using namespace tiny_llm;
 
 // Helper to create temporary files
 class TempFile {
-public:
-  TempFile(const std::string &suffix = ".bin") {
+  public:
+    TempFile(const std::string &suffix = ".bin") {
 #ifdef _WIN32
-    int pid = _getpid();
+        int pid = _getpid();
 #else
-    int pid = getpid();
+        int pid = getpid();
 #endif
-    path_ = "/tmp/tiny_llm_test_" + std::to_string(pid) + "_" +
-            std::to_string(std::random_device{}()) + suffix;
-  }
+        path_ = "/tmp/tiny_llm_test_" + std::to_string(pid) + "_" +
+                std::to_string(std::random_device{}()) + suffix;
+    }
 
-  ~TempFile() { std::remove(path_.c_str()); }
+    ~TempFile() { std::remove(path_.c_str()); }
 
-  const std::string &path() const { return path_; }
+    const std::string &path() const { return path_; }
 
-  void write(const void *data, size_t size) {
-    std::ofstream file(path_, std::ios::binary);
-    file.write(reinterpret_cast<const char *>(data), size);
-  }
+    void write(const void *data, size_t size) {
+        std::ofstream file(path_, std::ios::binary);
+        file.write(reinterpret_cast<const char *>(data), size);
+    }
 
-  template <typename T> void write(const T &value) { write(&value, sizeof(T)); }
+    template <typename T>
+    void write(const T &value) {
+        write(&value, sizeof(T));
+    }
 
-  void writeBytes(const std::vector<uint8_t> &bytes) {
-    std::ofstream file(path_, std::ios::binary);
-    file.write(reinterpret_cast<const char *>(bytes.data()), bytes.size());
-  }
+    void writeBytes(const std::vector<uint8_t> &bytes) {
+        std::ofstream file(path_, std::ios::binary);
+        file.write(reinterpret_cast<const char *>(bytes.data()), bytes.size());
+    }
 
-private:
-  std::string path_;
+  private:
+    std::string path_;
 };
 
 // Unit tests for GGUF header parsing
 class GGUFHeaderTest : public ::testing::Test {};
 
 TEST_F(GGUFHeaderTest, ValidHeader) {
-  TempFile file(".gguf");
+    TempFile file(".gguf");
 
-  // Write valid GGUF header
-  std::vector<uint8_t> header;
+    // Write valid GGUF header
+    std::vector<uint8_t> header;
 
-  // Magic: "GGUF" = 0x46554747
-  uint32_t magic = GGUF_MAGIC;
-  header.insert(header.end(), reinterpret_cast<uint8_t *>(&magic),
-                reinterpret_cast<uint8_t *>(&magic) + 4);
+    // Magic: "GGUF" = 0x46554747
+    uint32_t magic = GGUF_MAGIC;
+    header.insert(header.end(), reinterpret_cast<uint8_t *>(&magic),
+                  reinterpret_cast<uint8_t *>(&magic) + 4);
 
-  // Version: 3
-  uint32_t version = 3;
-  header.insert(header.end(), reinterpret_cast<uint8_t *>(&version),
-                reinterpret_cast<uint8_t *>(&version) + 4);
+    // Version: 3
+    uint32_t version = 3;
+    header.insert(header.end(), reinterpret_cast<uint8_t *>(&version),
+                  reinterpret_cast<uint8_t *>(&version) + 4);
 
-  // Tensor count: 10
-  uint64_t tensor_count = 10;
-  header.insert(header.end(), reinterpret_cast<uint8_t *>(&tensor_count),
-                reinterpret_cast<uint8_t *>(&tensor_count) + 8);
+    // Tensor count: 10
+    uint64_t tensor_count = 10;
+    header.insert(header.end(), reinterpret_cast<uint8_t *>(&tensor_count),
+                  reinterpret_cast<uint8_t *>(&tensor_count) + 8);
 
-  // Metadata KV count: 5
-  uint64_t metadata_count = 5;
-  header.insert(header.end(), reinterpret_cast<uint8_t *>(&metadata_count),
-                reinterpret_cast<uint8_t *>(&metadata_count) + 8);
+    // Metadata KV count: 5
+    uint64_t metadata_count = 5;
+    header.insert(header.end(), reinterpret_cast<uint8_t *>(&metadata_count),
+                  reinterpret_cast<uint8_t *>(&metadata_count) + 8);
 
-  file.writeBytes(header);
+    file.writeBytes(header);
 
-  ModelConfig config;
-  auto result = ModelLoader::loadGGUF(file.path(), config);
+    ModelConfig config;
+    auto        result = ModelLoader::loadGGUF(file.path(), config);
 
-  // Should fail with partial implementation message or parsing error (not crash)
-  EXPECT_TRUE(result.isErr());
+    // Should fail with partial implementation message or parsing error (not crash)
+    EXPECT_TRUE(result.isErr());
 }
 
 TEST_F(GGUFHeaderTest, InvalidMagic) {
-  TempFile file(".gguf");
+    TempFile file(".gguf");
 
-  std::vector<uint8_t> header;
-  uint32_t bad_magic = 0x12345678;
-  header.insert(header.end(), reinterpret_cast<uint8_t *>(&bad_magic),
-                reinterpret_cast<uint8_t *>(&bad_magic) + 4);
+    std::vector<uint8_t> header;
+    uint32_t             bad_magic = 0x12345678;
+    header.insert(header.end(), reinterpret_cast<uint8_t *>(&bad_magic),
+                  reinterpret_cast<uint8_t *>(&bad_magic) + 4);
 
-  file.writeBytes(header);
+    file.writeBytes(header);
 
-  ModelConfig config;
-  auto result = ModelLoader::loadGGUF(file.path(), config);
+    ModelConfig config;
+    auto        result = ModelLoader::loadGGUF(file.path(), config);
 
-  EXPECT_TRUE(result.isErr());
-  // Error message should indicate header or magic issue
-  EXPECT_TRUE(result.error().find("header") != std::string::npos ||
-              result.error().find("magic") != std::string::npos ||
-              result.error().find("Invalid") != std::string::npos);
+    EXPECT_TRUE(result.isErr());
+    // Error message should indicate header or magic issue
+    EXPECT_TRUE(result.error().find("header") != std::string::npos ||
+                result.error().find("magic") != std::string::npos ||
+                result.error().find("Invalid") != std::string::npos);
 }
 
 TEST_F(GGUFHeaderTest, UnsupportedVersion) {
-  TempFile file(".gguf");
+    TempFile file(".gguf");
 
-  std::vector<uint8_t> header;
-  uint32_t magic = GGUF_MAGIC;
-  uint32_t bad_version = 99;
+    std::vector<uint8_t> header;
+    uint32_t             magic = GGUF_MAGIC;
+    uint32_t             bad_version = 99;
 
-  header.insert(header.end(), reinterpret_cast<uint8_t *>(&magic),
-                reinterpret_cast<uint8_t *>(&magic) + 4);
-  header.insert(header.end(), reinterpret_cast<uint8_t *>(&bad_version),
-                reinterpret_cast<uint8_t *>(&bad_version) + 4);
+    header.insert(header.end(), reinterpret_cast<uint8_t *>(&magic),
+                  reinterpret_cast<uint8_t *>(&magic) + 4);
+    header.insert(header.end(), reinterpret_cast<uint8_t *>(&bad_version),
+                  reinterpret_cast<uint8_t *>(&bad_version) + 4);
 
-  file.writeBytes(header);
+    file.writeBytes(header);
 
-  ModelConfig config;
-  auto result = ModelLoader::loadGGUF(file.path(), config);
+    ModelConfig config;
+    auto        result = ModelLoader::loadGGUF(file.path(), config);
 
-  EXPECT_TRUE(result.isErr());
-  // Error message should indicate version issue
-  EXPECT_TRUE(result.error().find("version") != std::string::npos ||
-              result.error().find("Unsupported") != std::string::npos ||
-              result.error().find("header") != std::string::npos);
+    EXPECT_TRUE(result.isErr());
+    // Error message should indicate version issue
+    EXPECT_TRUE(result.error().find("version") != std::string::npos ||
+                result.error().find("Unsupported") != std::string::npos ||
+                result.error().find("header") != std::string::npos);
 }
 
 // Unit tests for binary format
 class BinLoaderTest : public ::testing::Test {};
 
 TEST_F(BinLoaderTest, InvalidMagic) {
-  TempFile file(".bin");
+    TempFile file(".bin");
 
-  uint32_t bad_magic = 0x12345678;
-  file.write(bad_magic);
+    uint32_t bad_magic = 0x12345678;
+    file.write(bad_magic);
 
-  ModelConfig config;
-  auto result = ModelLoader::loadBin(file.path(), config);
+    ModelConfig config;
+    auto        result = ModelLoader::loadBin(file.path(), config);
 
-  EXPECT_TRUE(result.isErr());
-  EXPECT_TRUE(result.error().find("magic") != std::string::npos);
+    EXPECT_TRUE(result.isErr());
+    EXPECT_TRUE(result.error().find("magic") != std::string::npos);
 }
 
 TEST_F(BinLoaderTest, FileNotFound) {
-  ModelConfig config;
-  auto result = ModelLoader::loadBin("/nonexistent/path/model.bin", config);
+    ModelConfig config;
+    auto        result = ModelLoader::loadBin("/nonexistent/path/model.bin", config);
 
-  EXPECT_TRUE(result.isErr());
-  EXPECT_TRUE(result.error().find("open") != std::string::npos ||
-              result.error().find("Failed") != std::string::npos);
+    EXPECT_TRUE(result.isErr());
+    EXPECT_TRUE(result.error().find("open") != std::string::npos ||
+                result.error().find("Failed") != std::string::npos);
 }
 
 TEST_F(BinLoaderTest, RuntimeLoadRejectsGGUFPath) {
-  ModelConfig config;
-  auto result = InferenceEngine::load("model.gguf", config);
+    ModelConfig config;
+    auto        result = InferenceEngine::load("model.gguf", config);
 
-  EXPECT_TRUE(result.isErr());
-  EXPECT_NE(result.error().find("GGUF runtime loading is not supported yet"),
-            std::string::npos);
+    EXPECT_TRUE(result.isErr());
+    EXPECT_NE(result.error().find("GGUF runtime loading is not supported yet"), std::string::npos);
 }
 
 TEST_F(BinLoaderTest, TruncatedHeader) {
-  TempFile file(".bin");
+    TempFile file(".bin");
 
-  // Write only magic, no version
-  uint32_t magic = BIN_MAGIC;
-  file.write(magic);
+    // Write only magic, no version
+    uint32_t magic = BIN_MAGIC;
+    file.write(magic);
 
-  ModelConfig config;
-  auto result = ModelLoader::loadBin(file.path(), config);
+    ModelConfig config;
+    auto        result = ModelLoader::loadBin(file.path(), config);
 
-  EXPECT_TRUE(result.isErr());
+    EXPECT_TRUE(result.isErr());
 }
 
 // Property-based tests for corrupted file handling
 // Feature: tiny-llm-inference-engine, Property 9: Corrupted File Error Handling
 // Validates: Requirements 1.5
 
-RC_GTEST_PROP(CorruptedFileProperty, RandomBytesReturnError,
-              (std::vector<uint8_t> random_bytes)) {
-  // Skip empty files
-  RC_PRE(!random_bytes.empty());
+RC_GTEST_PROP(CorruptedFileProperty, RandomBytesReturnError, (std::vector<uint8_t> random_bytes)) {
+    // Skip empty files
+    RC_PRE(!random_bytes.empty());
 
-  TempFile file(".bin");
-  file.writeBytes(random_bytes);
+    TempFile file(".bin");
+    file.writeBytes(random_bytes);
 
-  ModelConfig config;
-  auto result = ModelLoader::loadBin(file.path(), config);
+    ModelConfig config;
+    auto        result = ModelLoader::loadBin(file.path(), config);
 
-  // Property: random bytes should always result in error, never crash
-  // The result should be an error (unless by extreme chance it's valid)
-  if (random_bytes.size() < sizeof(BinHeader)) {
-    RC_ASSERT(result.isErr());
-  }
-  // Even if it passes magic check, it should fail somewhere
+    // Property: random bytes should always result in error, never crash
+    // The result should be an error (unless by extreme chance it's valid)
+    if (random_bytes.size() < sizeof(BinHeader)) {
+        RC_ASSERT(result.isErr());
+    }
+    // Even if it passes magic check, it should fail somewhere
 }
 
-RC_GTEST_PROP(CorruptedFileProperty, TruncatedFilesReturnError,
-              (int truncate_at)) {
-  // Create a minimal valid-looking header
-  std::vector<uint8_t> data;
+RC_GTEST_PROP(CorruptedFileProperty, TruncatedFilesReturnError, (int truncate_at)) {
+    // Create a minimal valid-looking header
+    std::vector<uint8_t> data;
 
-  uint32_t magic = BIN_MAGIC;
-  uint32_t version = BIN_VERSION;
-  ModelConfig config;
+    uint32_t    magic = BIN_MAGIC;
+    uint32_t    version = BIN_VERSION;
+    ModelConfig config;
 
-  data.insert(data.end(), reinterpret_cast<uint8_t *>(&magic),
-              reinterpret_cast<uint8_t *>(&magic) + 4);
-  data.insert(data.end(), reinterpret_cast<uint8_t *>(&version),
-              reinterpret_cast<uint8_t *>(&version) + 4);
-  data.insert(data.end(), reinterpret_cast<uint8_t *>(&config),
-              reinterpret_cast<uint8_t *>(&config) + sizeof(config));
+    data.insert(data.end(), reinterpret_cast<uint8_t *>(&magic),
+                reinterpret_cast<uint8_t *>(&magic) + 4);
+    data.insert(data.end(), reinterpret_cast<uint8_t *>(&version),
+                reinterpret_cast<uint8_t *>(&version) + 4);
+    data.insert(data.end(), reinterpret_cast<uint8_t *>(&config),
+                reinterpret_cast<uint8_t *>(&config) + sizeof(config));
 
-  // Truncate at random position
-  truncate_at = std::abs(truncate_at) % (data.size() + 1);
-  data.resize(truncate_at);
+    // Truncate at random position
+    truncate_at = std::abs(truncate_at) % (data.size() + 1);
+    data.resize(truncate_at);
 
-  TempFile file(".bin");
-  file.writeBytes(data);
+    TempFile file(".bin");
+    file.writeBytes(data);
 
-  auto result = ModelLoader::loadBin(file.path(), config);
+    auto result = ModelLoader::loadBin(file.path(), config);
 
-  // Property: truncated files should return error
-  RC_ASSERT(result.isErr());
+    // Property: truncated files should return error
+    RC_ASSERT(result.isErr());
 }
 
-RC_GTEST_PROP(CorruptedFileProperty, WrongVersionReturnError,
-              (uint32_t bad_version)) {
-  // Ensure version is not valid
-  RC_PRE(bad_version != BIN_VERSION);
+RC_GTEST_PROP(CorruptedFileProperty, WrongVersionReturnError, (uint32_t bad_version)) {
+    // Ensure version is not valid
+    RC_PRE(bad_version != BIN_VERSION);
 
-  std::vector<uint8_t> data;
+    std::vector<uint8_t> data;
 
-  uint32_t magic = BIN_MAGIC;
-  data.insert(data.end(), reinterpret_cast<uint8_t *>(&magic),
-              reinterpret_cast<uint8_t *>(&magic) + 4);
-  data.insert(data.end(), reinterpret_cast<uint8_t *>(&bad_version),
-              reinterpret_cast<uint8_t *>(&bad_version) + 4);
+    uint32_t magic = BIN_MAGIC;
+    data.insert(data.end(), reinterpret_cast<uint8_t *>(&magic),
+                reinterpret_cast<uint8_t *>(&magic) + 4);
+    data.insert(data.end(), reinterpret_cast<uint8_t *>(&bad_version),
+                reinterpret_cast<uint8_t *>(&bad_version) + 4);
 
-  TempFile file(".bin");
-  file.writeBytes(data);
+    TempFile file(".bin");
+    file.writeBytes(data);
 
-  ModelConfig config;
-  auto result = ModelLoader::loadBin(file.path(), config);
+    ModelConfig config;
+    auto        result = ModelLoader::loadBin(file.path(), config);
 
-  // Property: wrong version should return error
-  RC_ASSERT(result.isErr());
-  RC_ASSERT(result.error().find("version") != std::string::npos);
+    // Property: wrong version should return error
+    RC_ASSERT(result.isErr());
+    RC_ASSERT(result.error().find("version") != std::string::npos);
 }
 
 RC_GTEST_PROP(CorruptedFileProperty, GGUFRandomBytesReturnError,
               (std::vector<uint8_t> random_bytes)) {
-  RC_PRE(!random_bytes.empty());
+    RC_PRE(!random_bytes.empty());
 
-  TempFile file(".gguf");
-  file.writeBytes(random_bytes);
+    TempFile file(".gguf");
+    file.writeBytes(random_bytes);
 
-  ModelConfig config;
-  auto result = ModelLoader::loadGGUF(file.path(), config);
+    ModelConfig config;
+    auto        result = ModelLoader::loadGGUF(file.path(), config);
 
-  // Property: random bytes should result in error for GGUF too
-  // Unless by chance they form valid GGUF magic
-  if (random_bytes.size() < 4 ||
-      *reinterpret_cast<const uint32_t *>(random_bytes.data()) != GGUF_MAGIC) {
-    RC_ASSERT(result.isErr());
-  }
+    // Property: random bytes should result in error for GGUF too
+    // Unless by chance they form valid GGUF magic
+    if (random_bytes.size() < 4 ||
+        *reinterpret_cast<const uint32_t *>(random_bytes.data()) != GGUF_MAGIC) {
+        RC_ASSERT(result.isErr());
+    }
 }
 
 // Test dimension mismatch
 TEST_F(BinLoaderTest, DimensionMismatch) {
-  TempFile file(".bin");
+    TempFile file(".bin");
 
-  std::vector<uint8_t> data;
+    std::vector<uint8_t> data;
 
-  uint32_t magic = BIN_MAGIC;
-  uint32_t version = BIN_VERSION;
+    uint32_t magic = BIN_MAGIC;
+    uint32_t version = BIN_VERSION;
 
-  // Create config with different dimensions
-  ModelConfig stored_config;
-  stored_config.hidden_dim = 256;
-  stored_config.num_layers = 2;
-  stored_config.vocab_size = 1000;
+    // Create config with different dimensions
+    ModelConfig stored_config;
+    stored_config.hidden_dim = 256;
+    stored_config.num_layers = 2;
+    stored_config.vocab_size = 1000;
 
-  data.insert(data.end(), reinterpret_cast<uint8_t *>(&magic),
-              reinterpret_cast<uint8_t *>(&magic) + 4);
-  data.insert(data.end(), reinterpret_cast<uint8_t *>(&version),
-              reinterpret_cast<uint8_t *>(&version) + 4);
-  data.insert(data.end(), reinterpret_cast<uint8_t *>(&stored_config),
-              reinterpret_cast<uint8_t *>(&stored_config) +
-                  sizeof(stored_config));
+    data.insert(data.end(), reinterpret_cast<uint8_t *>(&magic),
+                reinterpret_cast<uint8_t *>(&magic) + 4);
+    data.insert(data.end(), reinterpret_cast<uint8_t *>(&version),
+                reinterpret_cast<uint8_t *>(&version) + 4);
+    data.insert(data.end(), reinterpret_cast<uint8_t *>(&stored_config),
+                reinterpret_cast<uint8_t *>(&stored_config) + sizeof(stored_config));
 
-  file.writeBytes(data);
+    file.writeBytes(data);
 
-  // Try to load with different config
-  ModelConfig expected_config;
-  expected_config.hidden_dim = 512; // Different!
-  expected_config.num_layers = 2;
-  expected_config.vocab_size = 1000;
+    // Try to load with different config
+    ModelConfig expected_config;
+    expected_config.hidden_dim = 512; // Different!
+    expected_config.num_layers = 2;
+    expected_config.vocab_size = 1000;
 
-  auto result = ModelLoader::loadBin(file.path(), expected_config);
+    auto result = ModelLoader::loadBin(file.path(), expected_config);
 
-  EXPECT_TRUE(result.isErr());
-  EXPECT_TRUE(result.error().find("mismatch") != std::string::npos);
+    EXPECT_TRUE(result.isErr());
+    EXPECT_TRUE(result.error().find("mismatch") != std::string::npos);
 }
diff --git a/tests/test_transformer.cu b/tests/test_transformer.cu
index ad546f7..b6296c5 100644
--- a/tests/test_transformer.cu
+++ b/tests/test_transformer.cu
@@ -16,186 +16,177 @@ using namespace tiny_llm::kernels;
 
 // Helper to check if CUDA device is available
 static bool hasCudaDevice() {
-  static bool checked = false;
-  static bool has_device = false;
-  if (!checked) {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    has_device = (err == cudaSuccess && device_count > 0);
-    checked = true;
-  }
-  return has_device;
+    static bool checked = false;
+    static bool has_device = false;
+    if (!checked) {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        has_device = (err == cudaSuccess && device_count > 0);
+        checked = true;
+    }
+    return has_device;
 }
 
 // Helper class for Transformer tests
 class TransformerTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    if (err != cudaSuccess || device_count == 0) {
-      GTEST_SKIP() << "No CUDA device available";
-    }
-    cudaSetDevice(0);
-  }
-
-  void TearDown() override { cudaDeviceSynchronize(); }
-
-  // Generate random FP16 tensor
-  std::vector<half> randomFP16(int size, float scale = 1.0f,
-                               unsigned seed = 42) {
-    std::vector<half> data(size);
-    std::mt19937 gen(seed);
-    std::uniform_real_distribution<float> dist(-scale, scale);
-    for (auto &v : data) {
-      v = __float2half(dist(gen));
+  protected:
+    void SetUp() override {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        if (err != cudaSuccess || device_count == 0) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
+        cudaSetDevice(0);
     }
-    return data;
-  }
-
-  // Generate random INT8 weights
-  std::vector<int8_t> randomINT8(int size, unsigned seed = 123) {
-    std::vector<int8_t> data(size);
-    std::mt19937 gen(seed);
-    std::uniform_int_distribution<int> dist(-127, 127);
-    for (auto &v : data) {
-      v = static_cast<int8_t>(dist(gen));
+
+    void TearDown() override { cudaDeviceSynchronize(); }
+
+    // Generate random FP16 tensor
+    std::vector<half> randomFP16(int size, float scale = 1.0f, unsigned seed = 42) {
+        std::vector<half>                     data(size);
+        std::mt19937                          gen(seed);
+        std::uniform_real_distribution<float> dist(-scale, scale);
+        for (auto &v : data) {
+            v = __float2half(dist(gen));
+        }
+        return data;
     }
-    return data;
-  }
-
-  // Generate random scales
-  std::vector<half> randomScales(int size, unsigned seed = 456) {
-    std::vector<half> data(size);
-    std::mt19937 gen(seed);
-    std::uniform_real_distribution<float> dist(0.001f, 0.1f);
-    for (auto &v : data) {
-      v = __float2half(dist(gen));
+
+    // Generate random INT8 weights
+    std::vector<int8_t> randomINT8(int size, unsigned seed = 123) {
+        std::vector<int8_t>                data(size);
+        std::mt19937                       gen(seed);
+        std::uniform_int_distribution<int> dist(-127, 127);
+        for (auto &v : data) {
+            v = static_cast<int8_t>(dist(gen));
+        }
+        return data;
     }
-    return data;
-  }
-
-  // Compute relative error between two tensors
-  float computeRelativeError(const std::vector<half> &a,
-                             const std::vector<half> &b) {
-    float max_diff = 0.0f;
-    float max_val = 0.0f;
-
-    for (size_t i = 0; i < a.size(); ++i) {
-      float va = __half2float(a[i]);
-      float vb = __half2float(b[i]);
-      max_diff = std::max(max_diff, std::abs(va - vb));
-      max_val = std::max(max_val, std::max(std::abs(va), std::abs(vb)));
+
+    // Generate random scales
+    std::vector<half> randomScales(int size, unsigned seed = 456) {
+        std::vector<half>                     data(size);
+        std::mt19937                          gen(seed);
+        std::uniform_real_distribution<float> dist(0.001f, 0.1f);
+        for (auto &v : data) {
+            v = __float2half(dist(gen));
+        }
+        return data;
     }
 
-    return max_val > 0 ? max_diff / max_val : 0.0f;
-  }
+    // Compute relative error between two tensors
+    float computeRelativeError(const std::vector<half> &a, const std::vector<half> &b) {
+        float max_diff = 0.0f;
+        float max_val = 0.0f;
+
+        for (size_t i = 0; i < a.size(); ++i) {
+            float va = __half2float(a[i]);
+            float vb = __half2float(b[i]);
+            max_diff = std::max(max_diff, std::abs(va - vb));
+            max_val = std::max(max_val, std::max(std::abs(va), std::abs(vb)));
+        }
+
+        return max_val > 0 ? max_diff / max_val : 0.0f;
+    }
 };
 
 // Unit test: Basic attention decode vs prefill equivalence
 TEST_F(TransformerTest, AttentionDecodeVsPrefillSingleToken) {
-  // Test that decode attention produces same result as prefill for single token
-  int batch_size = 1;
-  int num_heads = 4;
-  int seq_len = 8;
-  int head_dim = 32;
-  float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
-
-  // Generate random Q, K, V
-  auto query = randomFP16(batch_size * num_heads * head_dim, 1.0f, 100);
-  auto k_cache =
-      randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, 101);
-  auto v_cache =
-      randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, 102);
-
-  // Allocate device memory
-  DeviceBuffer<half> d_query(batch_size * num_heads * head_dim);
-  DeviceBuffer<half> d_k_cache(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_v_cache(batch_size * num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_output_decode(batch_size * num_heads * head_dim);
-
-  d_query.copyFromHost(query.data(), query.size());
-  d_k_cache.copyFromHost(k_cache.data(), k_cache.size());
-  d_v_cache.copyFromHost(v_cache.data(), v_cache.size());
-
-  // Run decode attention
-  attention_decode(d_query.data(), d_k_cache.data(), d_v_cache.data(),
-                   d_output_decode.data(), scale, batch_size, num_heads,
-                   seq_len, head_dim);
-
-  cudaDeviceSynchronize();
-
-  std::vector<half> output_decode(batch_size * num_heads * head_dim);
-  d_output_decode.copyToHost(output_decode.data(), output_decode.size());
-  cudaDeviceSynchronize();
-
-  // Verify output is not all zeros
-  bool has_nonzero = false;
-  for (const auto &v : output_decode) {
-    if (__half2float(v) != 0.0f) {
-      has_nonzero = true;
-      break;
+    // Test that decode attention produces same result as prefill for single token
+    int   batch_size = 1;
+    int   num_heads = 4;
+    int   seq_len = 8;
+    int   head_dim = 32;
+    float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
+
+    // Generate random Q, K, V
+    auto query = randomFP16(batch_size * num_heads * head_dim, 1.0f, 100);
+    auto k_cache = randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, 101);
+    auto v_cache = randomFP16(batch_size * num_heads * seq_len * head_dim, 1.0f, 102);
+
+    // Allocate device memory
+    DeviceBuffer<half> d_query(batch_size * num_heads * head_dim);
+    DeviceBuffer<half> d_k_cache(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_v_cache(batch_size * num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_output_decode(batch_size * num_heads * head_dim);
+
+    d_query.copyFromHost(query.data(), query.size());
+    d_k_cache.copyFromHost(k_cache.data(), k_cache.size());
+    d_v_cache.copyFromHost(v_cache.data(), v_cache.size());
+
+    // Run decode attention
+    attention_decode(d_query.data(), d_k_cache.data(), d_v_cache.data(), d_output_decode.data(),
+                     scale, batch_size, num_heads, seq_len, head_dim);
+
+    cudaDeviceSynchronize();
+
+    std::vector<half> output_decode(batch_size * num_heads * head_dim);
+    d_output_decode.copyToHost(output_decode.data(), output_decode.size());
+    cudaDeviceSynchronize();
+
+    // Verify output is not all zeros
+    bool has_nonzero = false;
+    for (const auto &v : output_decode) {
+        if (__half2float(v) != 0.0f) {
+            has_nonzero = true;
+            break;
+        }
     }
-  }
-  EXPECT_TRUE(has_nonzero);
+    EXPECT_TRUE(has_nonzero);
 }
 
 // Unit test: KV Cache append and retrieve
 TEST_F(TransformerTest, KVCacheAppendRetrieve) {
-  KVCacheConfig config;
-  config.num_layers = 2;
-  config.num_heads = 4;
-  config.head_dim = 32;
-  config.max_seq_len = 64;
-  config.max_batch_size = 2;
-
-  KVCacheManager cache(config);
-
-  // Allocate sequence
-  auto result = cache.allocateSequence(32);
-  ASSERT_TRUE(result.isOk());
-  int seq_id = result.value();
-
-  // Generate random K, V
-  int num_tokens = 4;
-  auto k_data =
-      randomFP16(num_tokens * config.num_heads * config.head_dim, 1.0f, 200);
-  auto v_data =
-      randomFP16(num_tokens * config.num_heads * config.head_dim, 1.0f, 201);
-
-  DeviceBuffer<half> d_k(k_data.size());
-  DeviceBuffer<half> d_v(v_data.size());
-  d_k.copyFromHost(k_data.data(), k_data.size());
-  d_v.copyFromHost(v_data.data(), v_data.size());
-  cudaDeviceSynchronize();
-
-  // Append to cache
-  cache.appendKV(seq_id, 0, d_k.data(), d_v.data(), num_tokens);
-  cudaDeviceSynchronize();
-
-  // appendKV writes data but does not advance the visible sequence length.
-  EXPECT_EQ(cache.getSeqLen(seq_id), 0);
-  cache.advanceSeqLen(seq_id, num_tokens);
-  EXPECT_EQ(cache.getSeqLen(seq_id), num_tokens);
-
-  // Get cache pointers
-  auto [k_cache, v_cache] = cache.getCache(seq_id, 0);
-  EXPECT_NE(k_cache, nullptr);
-  EXPECT_NE(v_cache, nullptr);
-
-  // Verify data was copied correctly
-  std::vector<half> k_retrieved(k_data.size());
-  std::vector<half> v_retrieved(v_data.size());
-  cudaMemcpy(k_retrieved.data(), k_cache, k_data.size() * sizeof(half),
-             cudaMemcpyDeviceToHost);
-  cudaMemcpy(v_retrieved.data(), v_cache, v_data.size() * sizeof(half),
-             cudaMemcpyDeviceToHost);
-
-  float k_error = computeRelativeError(k_data, k_retrieved);
-  float v_error = computeRelativeError(v_data, v_retrieved);
-
-  EXPECT_LT(k_error, 0.001f) << "K cache data mismatch";
-  EXPECT_LT(v_error, 0.001f) << "V cache data mismatch";
+    KVCacheConfig config;
+    config.num_layers = 2;
+    config.num_heads = 4;
+    config.head_dim = 32;
+    config.max_seq_len = 64;
+    config.max_batch_size = 2;
+
+    KVCacheManager cache(config);
+
+    // Allocate sequence
+    auto result = cache.allocateSequence(32);
+    ASSERT_TRUE(result.isOk());
+    int seq_id = result.value();
+
+    // Generate random K, V
+    int  num_tokens = 4;
+    auto k_data = randomFP16(num_tokens * config.num_heads * config.head_dim, 1.0f, 200);
+    auto v_data = randomFP16(num_tokens * config.num_heads * config.head_dim, 1.0f, 201);
+
+    DeviceBuffer<half> d_k(k_data.size());
+    DeviceBuffer<half> d_v(v_data.size());
+    d_k.copyFromHost(k_data.data(), k_data.size());
+    d_v.copyFromHost(v_data.data(), v_data.size());
+    cudaDeviceSynchronize();
+
+    // Append to cache
+    cache.appendKV(seq_id, 0, d_k.data(), d_v.data(), num_tokens);
+    cudaDeviceSynchronize();
+
+    // appendKV writes data but does not advance the visible sequence length.
+    EXPECT_EQ(cache.getSeqLen(seq_id), 0);
+    cache.advanceSeqLen(seq_id, num_tokens);
+    EXPECT_EQ(cache.getSeqLen(seq_id), num_tokens);
+
+    // Get cache pointers
+    auto [k_cache, v_cache] = cache.getCache(seq_id, 0);
+    EXPECT_NE(k_cache, nullptr);
+    EXPECT_NE(v_cache, nullptr);
+
+    // Verify data was copied correctly
+    std::vector<half> k_retrieved(k_data.size());
+    std::vector<half> v_retrieved(v_data.size());
+    cudaMemcpy(k_retrieved.data(), k_cache, k_data.size() * sizeof(half), cudaMemcpyDeviceToHost);
+    cudaMemcpy(v_retrieved.data(), v_cache, v_data.size() * sizeof(half), cudaMemcpyDeviceToHost);
+
+    float k_error = computeRelativeError(k_data, k_retrieved);
+    float v_error = computeRelativeError(v_data, v_retrieved);
+
+    EXPECT_LT(k_error, 0.001f) << "K cache data mismatch";
+    EXPECT_LT(v_error, 0.001f) << "V cache data mismatch";
 }
 
 // Property-based tests
@@ -203,15 +194,19 @@ TEST_F(TransformerTest, KVCacheAppendRetrieve) {
 // Equivalence Validates: Requirements 4.6
 // NOTE: Property-based tests are disabled when no CUDA device is available
 
-class TransformerPropertyTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    if (!hasCudaDevice()) {
-      GTEST_SKIP() << "No CUDA device available";
+class TransformerPropertyTest : public TransformerTest {
+  protected:
+    void SetUp() override {
+        if (hasCudaDevice()) {
+            cudaSetDevice(0);
+        }
+    }
+
+    void TearDown() override {
+        if (hasCudaDevice()) {
+            cudaDeviceSynchronize();
+        }
     }
-    cudaSetDevice(0);
-  }
-  void TearDown() override { cudaDeviceSynchronize(); }
 };
 
 // Property 5: Incremental Decoding Equivalence
@@ -219,228 +214,223 @@ protected:
 // must be identical to full sequence recomputation.
 
 RC_GTEST_FIXTURE_PROP(TransformerPropertyTest, IncrementalDecodingEquivalence,
-                      (int heads_raw, int seq_raw, int dim_raw,
-                       unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions to reasonable ranges
-  int num_heads = 2 + (std::abs(heads_raw) % 6); // 2 to 8
-  int seq_len = 4 + (std::abs(seq_raw) % 28);    // 4 to 32
-  int head_dim = 16 + (std::abs(dim_raw) % 48);  // 16 to 64
-  float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
-
-  // Generate random Q, K, V for full sequence
-  auto query_full = randomFP16(num_heads * seq_len * head_dim, 1.0f, seed);
-  auto key_full = randomFP16(num_heads * seq_len * head_dim, 1.0f, seed + 1);
-  auto value_full = randomFP16(num_heads * seq_len * head_dim, 1.0f, seed + 2);
-
-  // Allocate device memory
-  DeviceBuffer<half> d_query_full(num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_key_full(num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_value_full(num_heads * seq_len * head_dim);
-  DeviceBuffer<half> d_output_full(num_heads * seq_len * head_dim);
-
-  d_query_full.copyFromHost(query_full.data(), query_full.size());
-  d_key_full.copyFromHost(key_full.data(), key_full.size());
-  d_value_full.copyFromHost(value_full.data(), value_full.size());
-
-  // Run full prefill attention
-  attention_prefill(d_query_full.data(), d_key_full.data(), d_value_full.data(),
-                    d_output_full.data(), scale, 1, num_heads, seq_len,
-                    head_dim);
-
-  cudaDeviceSynchronize();
-
-  std::vector<half> output_full(num_heads * seq_len * head_dim);
-  d_output_full.copyToHost(output_full.data(), output_full.size());
-  cudaDeviceSynchronize();
-
-  // Now run incremental decoding for the last token
-  // Use the same K, V as cache, and query the last position
-  int last_pos = seq_len - 1;
-
-  // Extract last query
-  std::vector<half> query_last(num_heads * head_dim);
-  for (int h = 0; h < num_heads; ++h) {
-    for (int d = 0; d < head_dim; ++d) {
-      query_last[h * head_dim + d] =
-          query_full[(h * seq_len + last_pos) * head_dim + d];
+                      (int heads_raw, int seq_raw, int dim_raw, unsigned seed)) {
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions to reasonable ranges
+    int   num_heads = 2 + (std::abs(heads_raw) % 6); // 2 to 8
+    int   seq_len = 4 + (std::abs(seq_raw) % 28);    // 4 to 32
+    int   head_dim = 16 + (std::abs(dim_raw) % 48);  // 16 to 64
+    float scale = 1.0f / std::sqrt(static_cast<float>(head_dim));
+
+    // Generate random Q, K, V for full sequence
+    auto query_full = randomFP16(num_heads * seq_len * head_dim, 1.0f, seed);
+    auto key_full = randomFP16(num_heads * seq_len * head_dim, 1.0f, seed + 1);
+    auto value_full = randomFP16(num_heads * seq_len * head_dim, 1.0f, seed + 2);
+
+    // Allocate device memory
+    DeviceBuffer<half> d_query_full(num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_key_full(num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_value_full(num_heads * seq_len * head_dim);
+    DeviceBuffer<half> d_output_full(num_heads * seq_len * head_dim);
+
+    d_query_full.copyFromHost(query_full.data(), query_full.size());
+    d_key_full.copyFromHost(key_full.data(), key_full.size());
+    d_value_full.copyFromHost(value_full.data(), value_full.size());
+
+    // Run full prefill attention
+    attention_prefill(d_query_full.data(), d_key_full.data(), d_value_full.data(),
+                      d_output_full.data(), scale, 1, num_heads, seq_len, head_dim);
+
+    cudaDeviceSynchronize();
+
+    std::vector<half> output_full(num_heads * seq_len * head_dim);
+    d_output_full.copyToHost(output_full.data(), output_full.size());
+    cudaDeviceSynchronize();
+
+    // Now run incremental decoding for the last token
+    // Use the same K, V as cache, and query the last position
+    int last_pos = seq_len - 1;
+
+    // Extract last query
+    std::vector<half> query_last(num_heads * head_dim);
+    for (int h = 0; h < num_heads; ++h) {
+        for (int d = 0; d < head_dim; ++d) {
+            query_last[h * head_dim + d] = query_full[(h * seq_len + last_pos) * head_dim + d];
+        }
     }
-  }
 
-  DeviceBuffer<half> d_query_last(num_heads * head_dim);
-  DeviceBuffer<half> d_output_decode(num_heads * head_dim);
+    DeviceBuffer<half> d_query_last(num_heads * head_dim);
+    DeviceBuffer<half> d_output_decode(num_heads * head_dim);
 
-  d_query_last.copyFromHost(query_last.data(), query_last.size());
+    d_query_last.copyFromHost(query_last.data(), query_last.size());
 
-  // Run decode attention (query last token against full K, V cache)
-  attention_decode(d_query_last.data(), d_key_full.data(), d_value_full.data(),
-                   d_output_decode.data(), scale, 1, num_heads, seq_len,
-                   head_dim);
+    // Run decode attention (query last token against full K, V cache)
+    attention_decode(d_query_last.data(), d_key_full.data(), d_value_full.data(),
+                     d_output_decode.data(), scale, 1, num_heads, seq_len, head_dim);
 
-  cudaDeviceSynchronize();
+    cudaDeviceSynchronize();
 
-  std::vector<half> output_decode(num_heads * head_dim);
-  d_output_decode.copyToHost(output_decode.data(), output_decode.size());
-  cudaDeviceSynchronize();
+    std::vector<half> output_decode(num_heads * head_dim);
+    d_output_decode.copyToHost(output_decode.data(), output_decode.size());
+    cudaDeviceSynchronize();
 
-  // Extract last position output from full computation
-  std::vector<half> output_full_last(num_heads * head_dim);
-  for (int h = 0; h < num_heads; ++h) {
-    for (int d = 0; d < head_dim; ++d) {
-      output_full_last[h * head_dim + d] =
-          output_full[(h * seq_len + last_pos) * head_dim + d];
+    // Extract last position output from full computation
+    std::vector<half> output_full_last(num_heads * head_dim);
+    for (int h = 0; h < num_heads; ++h) {
+        for (int d = 0; d < head_dim; ++d) {
+            output_full_last[h * head_dim + d] =
+                output_full[(h * seq_len + last_pos) * head_dim + d];
+        }
     }
-  }
 
-  // Property: Incremental decode output should match full prefill output for
-  // last position
-  float rel_error = computeRelativeError(output_decode, output_full_last);
+    // Property: Incremental decode output should match full prefill output for
+    // last position
+    float rel_error = computeRelativeError(output_decode, output_full_last);
 
-  // Allow some tolerance for floating point differences
-  RC_ASSERT(rel_error < 0.05f); // 5% tolerance for FP16
+    // Allow some tolerance for floating point differences
+    RC_ASSERT(rel_error < 0.05f); // 5% tolerance for FP16
 }
 
 RC_GTEST_FIXTURE_PROP(TransformerPropertyTest, KVCachePreservesData,
-                      (int layers_raw, int heads_raw, int seq_raw, int dim_raw,
-                       unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions
-  int num_layers = 1 + (std::abs(layers_raw) % 4); // 1 to 4
-  int num_heads = 2 + (std::abs(heads_raw) % 6);   // 2 to 8
-  int max_seq_len = 32 + (std::abs(seq_raw) % 96); // 32 to 128
-  int head_dim = 16 + (std::abs(dim_raw) % 48);    // 16 to 64
-
-  KVCacheConfig config;
-  config.num_layers = num_layers;
-  config.num_heads = num_heads;
-  config.head_dim = head_dim;
-  config.max_seq_len = max_seq_len;
-  config.max_batch_size = 2;
-
-  KVCacheManager cache(config);
-
-  // Allocate sequence
-  int alloc_len = max_seq_len / 2;
-  auto result = cache.allocateSequence(alloc_len);
-  RC_ASSERT(result.isOk());
-  int seq_id = result.value();
-
-  // Generate and append random K, V for each layer
-  // In real usage, all layers append at the same time for each token batch
-  int num_tokens = 4;
-  std::vector<std::vector<half>> k_data_per_layer(num_layers);
-  std::vector<std::vector<half>> v_data_per_layer(num_layers);
-  std::vector<DeviceBuffer<half>> d_k_buffers;
-  std::vector<DeviceBuffer<half>> d_v_buffers;
-
-  // First, generate all data and copy to device
-  for (int layer = 0; layer < num_layers; ++layer) {
-    k_data_per_layer[layer] =
-        randomFP16(num_tokens * num_heads * head_dim, 1.0f, seed + layer * 2);
-    v_data_per_layer[layer] = randomFP16(num_tokens * num_heads * head_dim,
-                                         1.0f, seed + layer * 2 + 1);
-
-    d_k_buffers.emplace_back(k_data_per_layer[layer].size());
-    d_v_buffers.emplace_back(v_data_per_layer[layer].size());
-    d_k_buffers.back().copyFromHost(k_data_per_layer[layer].data(),
-                                    k_data_per_layer[layer].size());
-    d_v_buffers.back().copyFromHost(v_data_per_layer[layer].data(),
-                                    v_data_per_layer[layer].size());
-  }
-  cudaDeviceSynchronize();
-
-  // Append all layers in order (layer 0 first to update seq_len, then others)
-  // This simulates how TransformerLayer would use it
-  for (int layer = 0; layer < num_layers; ++layer) {
-    cache.appendKV(seq_id, layer, d_k_buffers[layer].data(),
-                   d_v_buffers[layer].data(), num_tokens);
-  }
-  cudaDeviceSynchronize();
-
-  // Property: Data should be preserved in cache
-  for (int layer = 0; layer < num_layers; ++layer) {
-    auto [k_cache, v_cache] = cache.getCache(seq_id, layer);
-    RC_ASSERT(k_cache != nullptr);
-    RC_ASSERT(v_cache != nullptr);
-
-    std::vector<half> k_retrieved(k_data_per_layer[layer].size());
-    std::vector<half> v_retrieved(v_data_per_layer[layer].size());
-    cudaMemcpy(k_retrieved.data(), k_cache, k_retrieved.size() * sizeof(half),
-               cudaMemcpyDeviceToHost);
-    cudaMemcpy(v_retrieved.data(), v_cache, v_retrieved.size() * sizeof(half),
-               cudaMemcpyDeviceToHost);
+                      (int layers_raw, int heads_raw, int seq_raw, int dim_raw, unsigned seed)) {
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions
+    int num_layers = 1 + (std::abs(layers_raw) % 4); // 1 to 4
+    int num_heads = 2 + (std::abs(heads_raw) % 6);   // 2 to 8
+    int max_seq_len = 32 + (std::abs(seq_raw) % 96); // 32 to 128
+    int head_dim = 16 + (std::abs(dim_raw) % 48);    // 16 to 64
+
+    KVCacheConfig config;
+    config.num_layers = num_layers;
+    config.num_heads = num_heads;
+    config.head_dim = head_dim;
+    config.max_seq_len = max_seq_len;
+    config.max_batch_size = 2;
+
+    KVCacheManager cache(config);
+
+    // Allocate sequence
+    int  alloc_len = max_seq_len / 2;
+    auto result = cache.allocateSequence(alloc_len);
+    RC_ASSERT(result.isOk());
+    int seq_id = result.value();
+
+    // Generate and append random K, V for each layer
+    // In real usage, all layers append at the same time for each token batch
+    int                             num_tokens = 4;
+    std::vector<std::vector<half>>  k_data_per_layer(num_layers);
+    std::vector<std::vector<half>>  v_data_per_layer(num_layers);
+    std::vector<DeviceBuffer<half>> d_k_buffers;
+    std::vector<DeviceBuffer<half>> d_v_buffers;
+
+    // First, generate all data and copy to device
+    for (int layer = 0; layer < num_layers; ++layer) {
+        k_data_per_layer[layer] =
+            randomFP16(num_tokens * num_heads * head_dim, 1.0f, seed + layer * 2);
+        v_data_per_layer[layer] =
+            randomFP16(num_tokens * num_heads * head_dim, 1.0f, seed + layer * 2 + 1);
+
+        d_k_buffers.emplace_back(k_data_per_layer[layer].size());
+        d_v_buffers.emplace_back(v_data_per_layer[layer].size());
+        d_k_buffers.back().copyFromHost(k_data_per_layer[layer].data(),
+                                        k_data_per_layer[layer].size());
+        d_v_buffers.back().copyFromHost(v_data_per_layer[layer].data(),
+                                        v_data_per_layer[layer].size());
+    }
+    cudaDeviceSynchronize();
 
-    float k_error = computeRelativeError(k_data_per_layer[layer], k_retrieved);
-    float v_error = computeRelativeError(v_data_per_layer[layer], v_retrieved);
+    // Append all layers in order (layer 0 first to update seq_len, then others)
+    // This simulates how TransformerLayer would use it
+    for (int layer = 0; layer < num_layers; ++layer) {
+        cache.appendKV(seq_id, layer, d_k_buffers[layer].data(), d_v_buffers[layer].data(),
+                       num_tokens);
+    }
+    cudaDeviceSynchronize();
 
-    RC_ASSERT(k_error < 0.001f);
-    RC_ASSERT(v_error < 0.001f);
-  }
+    // Property: Data should be preserved in cache
+    for (int layer = 0; layer < num_layers; ++layer) {
+        auto [k_cache, v_cache] = cache.getCache(seq_id, layer);
+        RC_ASSERT(k_cache != nullptr);
+        RC_ASSERT(v_cache != nullptr);
+
+        std::vector<half> k_retrieved(k_data_per_layer[layer].size());
+        std::vector<half> v_retrieved(v_data_per_layer[layer].size());
+        cudaMemcpy(k_retrieved.data(), k_cache, k_retrieved.size() * sizeof(half),
+                   cudaMemcpyDeviceToHost);
+        cudaMemcpy(v_retrieved.data(), v_cache, v_retrieved.size() * sizeof(half),
+                   cudaMemcpyDeviceToHost);
+
+        float k_error = computeRelativeError(k_data_per_layer[layer], k_retrieved);
+        float v_error = computeRelativeError(v_data_per_layer[layer], v_retrieved);
+
+        RC_ASSERT(k_error < 0.001f);
+        RC_ASSERT(v_error < 0.001f);
+    }
 }
 
 RC_GTEST_FIXTURE_PROP(TransformerPropertyTest, SequentialAppendEquivalence,
                       (int heads_raw, int dim_raw, unsigned seed)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions
-  int num_heads = 2 + (std::abs(heads_raw) % 6);
-  int head_dim = 16 + (std::abs(dim_raw) % 48);
-  int max_seq_len = 64;
-
-  KVCacheConfig config;
-  config.num_layers = 1;
-  config.num_heads = num_heads;
-  config.head_dim = head_dim;
-  config.max_seq_len = max_seq_len;
-  config.max_batch_size = 2;
-
-  KVCacheManager cache(config);
-
-  auto result = cache.allocateSequence(max_seq_len);
-  RC_ASSERT(result.isOk());
-  int seq_id = result.value();
-
-  // Append tokens one by one
-  int total_tokens = 8;
-  std::vector<half> all_k, all_v;
-
-  for (int t = 0; t < total_tokens; ++t) {
-    auto k_token = randomFP16(num_heads * head_dim, 1.0f, seed + t * 2);
-    auto v_token = randomFP16(num_heads * head_dim, 1.0f, seed + t * 2 + 1);
-
-    all_k.insert(all_k.end(), k_token.begin(), k_token.end());
-    all_v.insert(all_v.end(), v_token.begin(), v_token.end());
-
-    DeviceBuffer<half> d_k(k_token.size());
-    DeviceBuffer<half> d_v(v_token.size());
-    d_k.copyFromHost(k_token.data(), k_token.size());
-    d_v.copyFromHost(v_token.data(), v_token.size());
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions
+    int num_heads = 2 + (std::abs(heads_raw) % 6);
+    int head_dim = 16 + (std::abs(dim_raw) % 48);
+    int max_seq_len = 64;
+
+    KVCacheConfig config;
+    config.num_layers = 1;
+    config.num_heads = num_heads;
+    config.head_dim = head_dim;
+    config.max_seq_len = max_seq_len;
+    config.max_batch_size = 2;
+
+    KVCacheManager cache(config);
+
+    auto result = cache.allocateSequence(max_seq_len);
+    RC_ASSERT(result.isOk());
+    int seq_id = result.value();
+
+    // Append tokens one by one
+    int               total_tokens = 8;
+    std::vector<half> all_k, all_v;
+
+    for (int t = 0; t < total_tokens; ++t) {
+        auto k_token = randomFP16(num_heads * head_dim, 1.0f, seed + t * 2);
+        auto v_token = randomFP16(num_heads * head_dim, 1.0f, seed + t * 2 + 1);
+
+        all_k.insert(all_k.end(), k_token.begin(), k_token.end());
+        all_v.insert(all_v.end(), v_token.begin(), v_token.end());
+
+        DeviceBuffer<half> d_k(k_token.size());
+        DeviceBuffer<half> d_v(v_token.size());
+        d_k.copyFromHost(k_token.data(), k_token.size());
+        d_v.copyFromHost(v_token.data(), v_token.size());
+        cudaDeviceSynchronize();
+
+        cache.appendKV(seq_id, 0, d_k.data(), d_v.data(), 1);
+        cache.advanceSeqLen(seq_id, 1);
+    }
     cudaDeviceSynchronize();
 
-    cache.appendKV(seq_id, 0, d_k.data(), d_v.data(), 1);
-    cache.advanceSeqLen(seq_id, 1);
-  }
-  cudaDeviceSynchronize();
+    // Property: Sequential append should produce same result as batch append
+    RC_ASSERT(cache.getSeqLen(seq_id) == total_tokens);
 
-  // Property: Sequential append should produce same result as batch append
-  RC_ASSERT(cache.getSeqLen(seq_id) == total_tokens);
-
-  auto [k_cache, v_cache] = cache.getCache(seq_id, 0);
-  std::vector<half> k_retrieved(all_k.size());
-  std::vector<half> v_retrieved(all_v.size());
-  cudaMemcpy(k_retrieved.data(), k_cache, k_retrieved.size() * sizeof(half),
-             cudaMemcpyDeviceToHost);
-  cudaMemcpy(v_retrieved.data(), v_cache, v_retrieved.size() * sizeof(half),
-             cudaMemcpyDeviceToHost);
+    auto [k_cache, v_cache] = cache.getCache(seq_id, 0);
+    std::vector<half> k_retrieved(all_k.size());
+    std::vector<half> v_retrieved(all_v.size());
+    cudaMemcpy(k_retrieved.data(), k_cache, k_retrieved.size() * sizeof(half),
+               cudaMemcpyDeviceToHost);
+    cudaMemcpy(v_retrieved.data(), v_cache, v_retrieved.size() * sizeof(half),
+               cudaMemcpyDeviceToHost);
 
-  float k_error = computeRelativeError(all_k, k_retrieved);
-  float v_error = computeRelativeError(all_v, v_retrieved);
+    float k_error = computeRelativeError(all_k, k_retrieved);
+    float v_error = computeRelativeError(all_v, v_retrieved);
 
-  RC_ASSERT(k_error < 0.001f);
-  RC_ASSERT(v_error < 0.001f);
+    RC_ASSERT(k_error < 0.001f);
+    RC_ASSERT(v_error < 0.001f);
 }
diff --git a/tests/test_types.cpp b/tests/test_types.cpp
index 5b51633..96f962f 100644
--- a/tests/test_types.cpp
+++ b/tests/test_types.cpp
@@ -9,44 +9,44 @@ using namespace tiny_llm;
 class QuantizedWeightTest : public ::testing::Test {};
 
 TEST_F(QuantizedWeightTest, DefaultConstructorCreatesInvalidWeight) {
-  QuantizedWeight weight;
-  EXPECT_FALSE(weight.isValid());
+    QuantizedWeight weight;
+    EXPECT_FALSE(weight.isValid());
 }
 
 TEST_F(QuantizedWeightTest, ScaleDimensionsCalculation) {
-  QuantizedWeight weight;
-  weight.rows = 256;
-  weight.cols = 512;
-  weight.group_size = 128;
-
-  // Expected: scale rows = ceil(256 / 128) = 2
-  EXPECT_EQ(weight.scaleRows(), 2);
-  EXPECT_EQ(weight.scaleCols(), 512);
+    QuantizedWeight weight;
+    weight.rows = 256;
+    weight.cols = 512;
+    weight.group_size = 128;
+
+    // Expected: scale rows = ceil(256 / 128) = 2
+    EXPECT_EQ(weight.scaleRows(), 2);
+    EXPECT_EQ(weight.scaleCols(), 512);
 }
 
 TEST_F(QuantizedWeightTest, ScaleDimensionsWithNonDivisible) {
-  QuantizedWeight weight;
-  weight.rows = 100;
-  weight.cols = 300;
-  weight.group_size = 128;
-
-  // Expected: scale rows = ceil(100 / 128) = 1
-  EXPECT_EQ(weight.scaleRows(), 1);
-  EXPECT_EQ(weight.scaleCols(), 300);
+    QuantizedWeight weight;
+    weight.rows = 100;
+    weight.cols = 300;
+    weight.group_size = 128;
+
+    // Expected: scale rows = ceil(100 / 128) = 1
+    EXPECT_EQ(weight.scaleRows(), 1);
+    EXPECT_EQ(weight.scaleCols(), 300);
 }
 
 TEST_F(QuantizedWeightTest, MemorySizeCalculation) {
-  QuantizedWeight weight;
-  weight.rows = 256;
-  weight.cols = 512;
-  weight.group_size = 128;
+    QuantizedWeight weight;
+    weight.rows = 256;
+    weight.cols = 512;
+    weight.group_size = 128;
 
-  EXPECT_EQ(weight.weightElements(), 256 * 512);
-  EXPECT_EQ(weight.weightBytes(), 256 * 512 * sizeof(int8_t));
+    EXPECT_EQ(weight.weightElements(), 256 * 512);
+    EXPECT_EQ(weight.weightBytes(), 256 * 512 * sizeof(int8_t));
 
-  // scale elements = 2 * 512 = 1024
-  EXPECT_EQ(weight.scaleElements(), 2 * 512);
-  EXPECT_EQ(weight.scaleBytes(), 2 * 512 * sizeof(half));
+    // scale elements = 2 * 512 = 1024
+    EXPECT_EQ(weight.scaleElements(), 2 * 512);
+    EXPECT_EQ(weight.scaleBytes(), 2 * 512 * sizeof(half));
 }
 
 // Property-based tests for Weight-Scale Dimension Consistency
@@ -55,99 +55,96 @@ TEST_F(QuantizedWeightTest, MemorySizeCalculation) {
 
 RC_GTEST_PROP(QuantizedWeightProperty, ScaleDimensionsAreConsistent,
               (int rows, int cols, int group_size)) {
-  // Constrain inputs to reasonable ranges
-  rows = 1 + (std::abs(rows) % 4096);
-  cols = 1 + (std::abs(cols) % 4096);
-  group_size = 1 + (std::abs(group_size) % 256);
+    // Constrain inputs to reasonable ranges
+    rows = 1 + (std::abs(rows) % 4096);
+    cols = 1 + (std::abs(cols) % 4096);
+    group_size = 1 + (std::abs(group_size) % 256);
 
-  QuantizedWeight weight;
-  weight.rows = rows;
-  weight.cols = cols;
-  weight.group_size = group_size;
+    QuantizedWeight weight;
+    weight.rows = rows;
+    weight.cols = cols;
+    weight.group_size = group_size;
 
-  // Property: scale tensor must have shape [ceil(rows / group_size), cols]
-  int expected_scale_rows = (rows + group_size - 1) / group_size;
-  int expected_scale_cols = cols;
+    // Property: scale tensor must have shape [ceil(rows / group_size), cols]
+    int expected_scale_rows = (rows + group_size - 1) / group_size;
+    int expected_scale_cols = cols;
 
-  RC_ASSERT(weight.scaleRows() == expected_scale_rows);
-  RC_ASSERT(weight.scaleCols() == expected_scale_cols);
+    RC_ASSERT(weight.scaleRows() == expected_scale_rows);
+    RC_ASSERT(weight.scaleCols() == expected_scale_cols);
 
-  // Property: scale elements must cover all weight rows
-  RC_ASSERT(weight.scaleRows() * group_size >= rows);
+    // Property: scale elements must cover all weight rows
+    RC_ASSERT(weight.scaleRows() * group_size >= rows);
 
-  // Property: scale elements should not be more than necessary
-  RC_ASSERT((weight.scaleRows() - 1) * group_size < rows);
+    // Property: scale elements should not be more than necessary
+    RC_ASSERT((weight.scaleRows() - 1) * group_size < rows);
 }
 
-RC_GTEST_PROP(QuantizedWeightProperty, TotalBytesIsCorrect,
-              (int rows, int cols, int group_size)) {
-  rows = 1 + (std::abs(rows) % 2048);
-  cols = 1 + (std::abs(cols) % 2048);
-  group_size = 1 + (std::abs(group_size) % 256);
-
-  QuantizedWeight weight;
-  weight.rows = rows;
-  weight.cols = cols;
-  weight.group_size = group_size;
-
-  // Property: total bytes = weight bytes + scale bytes
-  size_t expected_total = weight.weightBytes() + weight.scaleBytes();
-  RC_ASSERT(weight.totalBytes() == expected_total);
-
-  // Property: weight bytes = rows * cols * sizeof(int8_t)
-  RC_ASSERT(weight.weightBytes() ==
-            static_cast<size_t>(rows) * cols * sizeof(int8_t));
+RC_GTEST_PROP(QuantizedWeightProperty, TotalBytesIsCorrect, (int rows, int cols, int group_size)) {
+    rows = 1 + (std::abs(rows) % 2048);
+    cols = 1 + (std::abs(cols) % 2048);
+    group_size = 1 + (std::abs(group_size) % 256);
+
+    QuantizedWeight weight;
+    weight.rows = rows;
+    weight.cols = cols;
+    weight.group_size = group_size;
+
+    // Property: total bytes = weight bytes + scale bytes
+    size_t expected_total = weight.weightBytes() + weight.scaleBytes();
+    RC_ASSERT(weight.totalBytes() == expected_total);
+
+    // Property: weight bytes = rows * cols * sizeof(int8_t)
+    RC_ASSERT(weight.weightBytes() == static_cast<size_t>(rows) * cols * sizeof(int8_t));
 }
 
-RC_GTEST_PROP(QuantizedWeightProperty, GroupSizeAffectsScaleSize,
-              (int rows, int cols)) {
-  rows = 64 + (std::abs(rows) % 1024);
-  cols = 128 + (std::abs(cols) % 2048);
+RC_GTEST_PROP(QuantizedWeightProperty, GroupSizeAffectsScaleSize, (int rows, int cols)) {
+    rows = 64 + (std::abs(rows) % 1024);
+    cols = 128 + (std::abs(cols) % 2048);
 
-  QuantizedWeight weight1, weight2;
-  weight1.rows = weight2.rows = rows;
-  weight1.cols = weight2.cols = cols;
-  weight1.group_size = 64;
-  weight2.group_size = 128;
+    QuantizedWeight weight1, weight2;
+    weight1.rows = weight2.rows = rows;
+    weight1.cols = weight2.cols = cols;
+    weight1.group_size = 64;
+    weight2.group_size = 128;
 
-  // Property: larger group size means fewer scale elements
-  RC_ASSERT(weight1.scaleElements() >= weight2.scaleElements());
+    // Property: larger group size means fewer scale elements
+    RC_ASSERT(weight1.scaleElements() >= weight2.scaleElements());
 
-  // Property: smaller group size means more memory for scales
-  RC_ASSERT(weight1.scaleBytes() >= weight2.scaleBytes());
+    // Property: smaller group size means more memory for scales
+    RC_ASSERT(weight1.scaleBytes() >= weight2.scaleBytes());
 }
 
 // Test ModelConfig defaults
 class ModelConfigTest : public ::testing::Test {};
 
 TEST_F(ModelConfigTest, DefaultValues) {
-  ModelConfig config;
-  EXPECT_EQ(config.vocab_size, 32000);
-  EXPECT_EQ(config.hidden_dim, 4096);
-  EXPECT_EQ(config.num_layers, 32);
-  EXPECT_EQ(config.num_heads, 32);
-  EXPECT_EQ(config.head_dim, 128);
-  EXPECT_GT(config.rms_norm_eps, 0.0f);
+    ModelConfig config;
+    EXPECT_EQ(config.vocab_size, 32000);
+    EXPECT_EQ(config.hidden_dim, 4096);
+    EXPECT_EQ(config.num_layers, 32);
+    EXPECT_EQ(config.num_heads, 32);
+    EXPECT_EQ(config.head_dim, 128);
+    EXPECT_GT(config.rms_norm_eps, 0.0f);
 }
 
 // Test GenerationConfig
 class GenerationConfigTest : public ::testing::Test {};
 
 TEST_F(GenerationConfigTest, DefaultValues) {
-  GenerationConfig config;
-  EXPECT_EQ(config.max_new_tokens, 256);
-  EXPECT_FLOAT_EQ(config.temperature, 1.0f);
-  EXPECT_EQ(config.top_k, 50);
-  EXPECT_FALSE(config.do_sample);
+    GenerationConfig config;
+    EXPECT_EQ(config.max_new_tokens, 256);
+    EXPECT_FLOAT_EQ(config.temperature, 1.0f);
+    EXPECT_EQ(config.top_k, 50);
+    EXPECT_FALSE(config.do_sample);
 }
 
 // Test KVCacheConfig
 class KVCacheConfigTest : public ::testing::Test {};
 
 TEST_F(KVCacheConfigTest, DefaultValues) {
-  KVCacheConfig config;
-  EXPECT_EQ(config.num_layers, 32);
-  EXPECT_EQ(config.num_heads, 32);
-  EXPECT_EQ(config.head_dim, 128);
-  EXPECT_EQ(config.max_seq_len, 2048);
+    KVCacheConfig config;
+    EXPECT_EQ(config.num_layers, 32);
+    EXPECT_EQ(config.num_heads, 32);
+    EXPECT_EQ(config.head_dim, 128);
+    EXPECT_EQ(config.max_seq_len, 2048);
 }
diff --git a/tests/test_w8a16_matmul.cu b/tests/test_w8a16_matmul.cu
index f8d10f3..a1b552b 100644
--- a/tests/test_w8a16_matmul.cu
+++ b/tests/test_w8a16_matmul.cu
@@ -14,215 +14,210 @@ using namespace tiny_llm::kernels;
 
 // Helper to check if CUDA device is available
 static bool hasCudaDevice() {
-  static bool checked = false;
-  static bool has_device = false;
-  if (!checked) {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    has_device = (err == cudaSuccess && device_count > 0);
-    checked = true;
-  }
-  return has_device;
+    static bool checked = false;
+    static bool has_device = false;
+    if (!checked) {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        has_device = (err == cudaSuccess && device_count > 0);
+        checked = true;
+    }
+    return has_device;
 }
 
 // Helper class for GPU test fixtures
 class W8A16MatMulTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    int device_count = 0;
-    cudaError_t err = cudaGetDeviceCount(&device_count);
-    if (err != cudaSuccess || device_count == 0) {
-      GTEST_SKIP() << "No CUDA device available";
-    }
-    cudaSetDevice(0);
-  }
-
-  void TearDown() override { cudaDeviceSynchronize(); }
-
-  // Generate random FP16 matrix
-  std::vector<half> randomFP16(int rows, int cols, float scale = 1.0f) {
-    std::vector<half> data(rows * cols);
-    std::mt19937 gen(42);
-    std::uniform_real_distribution<float> dist(-scale, scale);
-    for (auto &v : data) {
-      v = __float2half(dist(gen));
+  protected:
+    void SetUp() override {
+        int         device_count = 0;
+        cudaError_t err = cudaGetDeviceCount(&device_count);
+        if (err != cudaSuccess || device_count == 0) {
+            GTEST_SKIP() << "No CUDA device available";
+        }
+        cudaSetDevice(0);
     }
-    return data;
-  }
-
-  // Generate random INT8 weights
-  std::vector<int8_t> randomINT8(int rows, int cols) {
-    std::vector<int8_t> data(rows * cols);
-    std::mt19937 gen(123);
-    std::uniform_int_distribution<int> dist(-127, 127);
-    for (auto &v : data) {
-      v = static_cast<int8_t>(dist(gen));
+
+    void TearDown() override { cudaDeviceSynchronize(); }
+
+    // Generate random FP16 matrix
+    std::vector<half> randomFP16(int rows, int cols, float scale = 1.0f) {
+        std::vector<half>                     data(rows * cols);
+        std::mt19937                          gen(42);
+        std::uniform_real_distribution<float> dist(-scale, scale);
+        for (auto &v : data) {
+            v = __float2half(dist(gen));
+        }
+        return data;
     }
-    return data;
-  }
-
-  // Generate random scales
-  std::vector<half> randomScales(int num_groups, int cols) {
-    std::vector<half> data(num_groups * cols);
-    std::mt19937 gen(456);
-    std::uniform_real_distribution<float> dist(0.001f, 0.1f);
-    for (auto &v : data) {
-      v = __float2half(dist(gen));
+
+    // Generate random INT8 weights
+    std::vector<int8_t> randomINT8(int rows, int cols) {
+        std::vector<int8_t>                data(rows * cols);
+        std::mt19937                       gen(123);
+        std::uniform_int_distribution<int> dist(-127, 127);
+        for (auto &v : data) {
+            v = static_cast<int8_t>(dist(gen));
+        }
+        return data;
     }
-    return data;
-  }
-
-  // Compute relative error
-  float computeRelativeError(const std::vector<half> &a,
-                             const std::vector<half> &b) {
-    float max_diff = 0.0f;
-    float max_val = 0.0f;
-
-    for (size_t i = 0; i < a.size(); ++i) {
-      float va = __half2float(a[i]);
-      float vb = __half2float(b[i]);
-      max_diff = std::max(max_diff, std::abs(va - vb));
-      max_val = std::max(max_val, std::max(std::abs(va), std::abs(vb)));
+
+    // Generate random scales
+    std::vector<half> randomScales(int num_groups, int cols) {
+        std::vector<half>                     data(num_groups * cols);
+        std::mt19937                          gen(456);
+        std::uniform_real_distribution<float> dist(0.001f, 0.1f);
+        for (auto &v : data) {
+            v = __float2half(dist(gen));
+        }
+        return data;
     }
 
-    return max_val > 0 ? max_diff / max_val : 0.0f;
-  }
+    // Compute relative error
+    float computeRelativeError(const std::vector<half> &a, const std::vector<half> &b) {
+        float max_diff = 0.0f;
+        float max_val = 0.0f;
+
+        for (size_t i = 0; i < a.size(); ++i) {
+            float va = __half2float(a[i]);
+            float vb = __half2float(b[i]);
+            max_diff = std::max(max_diff, std::abs(va - vb));
+            max_val = std::max(max_val, std::max(std::abs(va), std::abs(vb)));
+        }
+
+        return max_val > 0 ? max_diff / max_val : 0.0f;
+    }
 };
 
 // Unit tests
 TEST_F(W8A16MatMulTest, SmallMatrixCorrectness) {
-  int M = 4, N = 8, K = 16;
-  int group_size = 8;
-  int num_groups = (K + group_size - 1) / group_size;
-
-  auto input = randomFP16(M, K);
-  auto weight = randomINT8(K, N);
-  auto scales = randomScales(num_groups, N);
-
-  // Allocate device memory
-  DeviceBuffer<half> d_input(M * K);
-  DeviceBuffer<int8_t> d_weight(K * N);
-  DeviceBuffer<half> d_scales(num_groups * N);
-  DeviceBuffer<half> d_output(M * N);
-  DeviceBuffer<half> d_weight_fp16(K * N);
-  DeviceBuffer<half> d_output_ref(M * N);
-
-  d_input.copyFromHost(input.data(), M * K);
-  d_weight.copyFromHost(weight.data(), K * N);
-  d_scales.copyFromHost(scales.data(), num_groups * N);
-
-  // Run W8A16 kernel
-  w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(),
-               d_output.data(), M, N, K, group_size);
-
-  // Dequantize and run FP16 reference
-  dequantize_weights(d_weight.data(), d_scales.data(), d_weight_fp16.data(), K,
-                     N, group_size);
-  fp16_matmul_reference(d_input.data(), d_weight_fp16.data(),
-                        d_output_ref.data(), M, N, K);
-
-  cudaDeviceSynchronize();
-
-  // Copy results back
-  std::vector<half> output(M * N);
-  std::vector<half> output_ref(M * N);
-  d_output.copyToHost(output.data(), M * N);
-  d_output_ref.copyToHost(output_ref.data(), M * N);
-  cudaDeviceSynchronize();
-
-  // Check relative error
-  float rel_error = computeRelativeError(output, output_ref);
-  EXPECT_LT(rel_error, 0.01f) << "Relative error too high: " << rel_error;
+    int M = 4, N = 8, K = 16;
+    int group_size = 8;
+    int num_groups = (K + group_size - 1) / group_size;
+
+    auto input = randomFP16(M, K);
+    auto weight = randomINT8(K, N);
+    auto scales = randomScales(num_groups, N);
+
+    // Allocate device memory
+    DeviceBuffer<half>   d_input(M * K);
+    DeviceBuffer<int8_t> d_weight(K * N);
+    DeviceBuffer<half>   d_scales(num_groups * N);
+    DeviceBuffer<half>   d_output(M * N);
+    DeviceBuffer<half>   d_weight_fp16(K * N);
+    DeviceBuffer<half>   d_output_ref(M * N);
+
+    d_input.copyFromHost(input.data(), M * K);
+    d_weight.copyFromHost(weight.data(), K * N);
+    d_scales.copyFromHost(scales.data(), num_groups * N);
+
+    // Run W8A16 kernel
+    w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(), d_output.data(), M, N, K,
+                 group_size);
+
+    // Dequantize and run FP16 reference
+    dequantize_weights(d_weight.data(), d_scales.data(), d_weight_fp16.data(), K, N, group_size);
+    fp16_matmul_reference(d_input.data(), d_weight_fp16.data(), d_output_ref.data(), M, N, K);
+
+    cudaDeviceSynchronize();
+
+    // Copy results back
+    std::vector<half> output(M * N);
+    std::vector<half> output_ref(M * N);
+    d_output.copyToHost(output.data(), M * N);
+    d_output_ref.copyToHost(output_ref.data(), M * N);
+    cudaDeviceSynchronize();
+
+    // Check relative error
+    float rel_error = computeRelativeError(output, output_ref);
+    EXPECT_LT(rel_error, 0.01f) << "Relative error too high: " << rel_error;
 }
 
 TEST_F(W8A16MatMulTest, EdgeCaseM1) {
-  int M = 1, N = 64, K = 128;
-  int group_size = 32;
-  int num_groups = (K + group_size - 1) / group_size;
-
-  auto input = randomFP16(M, K);
-  auto weight = randomINT8(K, N);
-  auto scales = randomScales(num_groups, N);
-
-  DeviceBuffer<half> d_input(M * K);
-  DeviceBuffer<int8_t> d_weight(K * N);
-  DeviceBuffer<half> d_scales(num_groups * N);
-  DeviceBuffer<half> d_output(M * N);
-
-  d_input.copyFromHost(input.data(), M * K);
-  d_weight.copyFromHost(weight.data(), K * N);
-  d_scales.copyFromHost(scales.data(), num_groups * N);
-
-  EXPECT_NO_THROW({
-    w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(),
-                 d_output.data(), M, N, K, group_size);
-    cudaDeviceSynchronize();
-  });
+    int M = 1, N = 64, K = 128;
+    int group_size = 32;
+    int num_groups = (K + group_size - 1) / group_size;
+
+    auto input = randomFP16(M, K);
+    auto weight = randomINT8(K, N);
+    auto scales = randomScales(num_groups, N);
+
+    DeviceBuffer<half>   d_input(M * K);
+    DeviceBuffer<int8_t> d_weight(K * N);
+    DeviceBuffer<half>   d_scales(num_groups * N);
+    DeviceBuffer<half>   d_output(M * N);
+
+    d_input.copyFromHost(input.data(), M * K);
+    d_weight.copyFromHost(weight.data(), K * N);
+    d_scales.copyFromHost(scales.data(), num_groups * N);
+
+    EXPECT_NO_THROW({
+        w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(), d_output.data(), M, N, K,
+                     group_size);
+        cudaDeviceSynchronize();
+    });
 }
 
 TEST_F(W8A16MatMulTest, EdgeCaseN1) {
-  int M = 64, N = 1, K = 128;
-  int group_size = 32;
-  int num_groups = (K + group_size - 1) / group_size;
-
-  auto input = randomFP16(M, K);
-  auto weight = randomINT8(K, N);
-  auto scales = randomScales(num_groups, N);
-
-  DeviceBuffer<half> d_input(M * K);
-  DeviceBuffer<int8_t> d_weight(K * N);
-  DeviceBuffer<half> d_scales(num_groups * N);
-  DeviceBuffer<half> d_output(M * N);
-
-  d_input.copyFromHost(input.data(), M * K);
-  d_weight.copyFromHost(weight.data(), K * N);
-  d_scales.copyFromHost(scales.data(), num_groups * N);
-
-  EXPECT_NO_THROW({
-    w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(),
-                 d_output.data(), M, N, K, group_size);
-    cudaDeviceSynchronize();
-  });
+    int M = 64, N = 1, K = 128;
+    int group_size = 32;
+    int num_groups = (K + group_size - 1) / group_size;
+
+    auto input = randomFP16(M, K);
+    auto weight = randomINT8(K, N);
+    auto scales = randomScales(num_groups, N);
+
+    DeviceBuffer<half>   d_input(M * K);
+    DeviceBuffer<int8_t> d_weight(K * N);
+    DeviceBuffer<half>   d_scales(num_groups * N);
+    DeviceBuffer<half>   d_output(M * N);
+
+    d_input.copyFromHost(input.data(), M * K);
+    d_weight.copyFromHost(weight.data(), K * N);
+    d_scales.copyFromHost(scales.data(), num_groups * N);
+
+    EXPECT_NO_THROW({
+        w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(), d_output.data(), M, N, K,
+                     group_size);
+        cudaDeviceSynchronize();
+    });
 }
 
 TEST_F(W8A16MatMulTest, NonAlignedDimensions) {
-  int M = 17, N = 33, K = 65;
-  int group_size = 32;
-  int num_groups = (K + group_size - 1) / group_size;
-
-  auto input = randomFP16(M, K);
-  auto weight = randomINT8(K, N);
-  auto scales = randomScales(num_groups, N);
-
-  DeviceBuffer<half> d_input(M * K);
-  DeviceBuffer<int8_t> d_weight(K * N);
-  DeviceBuffer<half> d_scales(num_groups * N);
-  DeviceBuffer<half> d_output(M * N);
-  DeviceBuffer<half> d_weight_fp16(K * N);
-  DeviceBuffer<half> d_output_ref(M * N);
-
-  d_input.copyFromHost(input.data(), M * K);
-  d_weight.copyFromHost(weight.data(), K * N);
-  d_scales.copyFromHost(scales.data(), num_groups * N);
-
-  w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(),
-               d_output.data(), M, N, K, group_size);
-
-  dequantize_weights(d_weight.data(), d_scales.data(), d_weight_fp16.data(), K,
-                     N, group_size);
-  fp16_matmul_reference(d_input.data(), d_weight_fp16.data(),
-                        d_output_ref.data(), M, N, K);
-
-  cudaDeviceSynchronize();
-
-  std::vector<half> output(M * N);
-  std::vector<half> output_ref(M * N);
-  d_output.copyToHost(output.data(), M * N);
-  d_output_ref.copyToHost(output_ref.data(), M * N);
-  cudaDeviceSynchronize();
-
-  float rel_error = computeRelativeError(output, output_ref);
-  EXPECT_LT(rel_error, 0.01f);
+    int M = 17, N = 33, K = 65;
+    int group_size = 32;
+    int num_groups = (K + group_size - 1) / group_size;
+
+    auto input = randomFP16(M, K);
+    auto weight = randomINT8(K, N);
+    auto scales = randomScales(num_groups, N);
+
+    DeviceBuffer<half>   d_input(M * K);
+    DeviceBuffer<int8_t> d_weight(K * N);
+    DeviceBuffer<half>   d_scales(num_groups * N);
+    DeviceBuffer<half>   d_output(M * N);
+    DeviceBuffer<half>   d_weight_fp16(K * N);
+    DeviceBuffer<half>   d_output_ref(M * N);
+
+    d_input.copyFromHost(input.data(), M * K);
+    d_weight.copyFromHost(weight.data(), K * N);
+    d_scales.copyFromHost(scales.data(), num_groups * N);
+
+    w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(), d_output.data(), M, N, K,
+                 group_size);
+
+    dequantize_weights(d_weight.data(), d_scales.data(), d_weight_fp16.data(), K, N, group_size);
+    fp16_matmul_reference(d_input.data(), d_weight_fp16.data(), d_output_ref.data(), M, N, K);
+
+    cudaDeviceSynchronize();
+
+    std::vector<half> output(M * N);
+    std::vector<half> output_ref(M * N);
+    d_output.copyToHost(output.data(), M * N);
+    d_output_ref.copyToHost(output_ref.data(), M * N);
+    cudaDeviceSynchronize();
+
+    float rel_error = computeRelativeError(output, output_ref);
+    EXPECT_LT(rel_error, 0.01f);
 }
 
 // Property-based tests
@@ -230,115 +225,115 @@ TEST_F(W8A16MatMulTest, NonAlignedDimensions) {
 // Accuracy Validates: Requirements 2.5, 2.6
 // NOTE: Property-based tests are disabled when no CUDA device is available
 
-class W8A16PropertyTest : public ::testing::Test {
-protected:
-  void SetUp() override {
-    if (!hasCudaDevice()) {
-      GTEST_SKIP() << "No CUDA device available";
+class W8A16PropertyTest : public W8A16MatMulTest {
+  protected:
+    void SetUp() override {
+        if (hasCudaDevice()) {
+            cudaSetDevice(0);
+        }
+    }
+
+    void TearDown() override {
+        if (hasCudaDevice()) {
+            cudaDeviceSynchronize();
+        }
     }
-    cudaSetDevice(0);
-  }
-  void TearDown() override { cudaDeviceSynchronize(); }
 };
 
 RC_GTEST_FIXTURE_PROP(W8A16PropertyTest, NumericalAccuracyProperty,
                       (int m_raw, int n_raw, int k_raw)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  // Constrain dimensions to reasonable ranges
-  int M = 1 + (std::abs(m_raw) % 128);
-  int N = 8 + (std::abs(n_raw) % 256);
-  int K = 32 + (std::abs(k_raw) % 512);
-  int group_size = 32;
-  int num_groups = (K + group_size - 1) / group_size;
-
-  // Generate random data
-  auto input = randomFP16(M, K, 0.5f);
-  auto weight = randomINT8(K, N);
-  auto scales = randomScales(num_groups, N);
-
-  // Allocate device memory
-  DeviceBuffer<half> d_input(M * K);
-  DeviceBuffer<int8_t> d_weight(K * N);
-  DeviceBuffer<half> d_scales(num_groups * N);
-  DeviceBuffer<half> d_output(M * N);
-  DeviceBuffer<half> d_weight_fp16(K * N);
-  DeviceBuffer<half> d_output_ref(M * N);
-
-  d_input.copyFromHost(input.data(), M * K);
-  d_weight.copyFromHost(weight.data(), K * N);
-  d_scales.copyFromHost(scales.data(), num_groups * N);
-
-  // Run W8A16 kernel
-  w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(),
-               d_output.data(), M, N, K, group_size);
-
-  // Dequantize and run FP16 reference
-  dequantize_weights(d_weight.data(), d_scales.data(), d_weight_fp16.data(), K,
-                     N, group_size);
-  fp16_matmul_reference(d_input.data(), d_weight_fp16.data(),
-                        d_output_ref.data(), M, N, K);
-
-  cudaDeviceSynchronize();
-
-  // Copy results back
-  std::vector<half> output(M * N);
-  std::vector<half> output_ref(M * N);
-  d_output.copyToHost(output.data(), M * N);
-  d_output_ref.copyToHost(output_ref.data(), M * N);
-  cudaDeviceSynchronize();
-
-  // Property: relative error should be < 1%
-  float rel_error = computeRelativeError(output, output_ref);
-  RC_ASSERT(rel_error < 0.01f);
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    // Constrain dimensions to reasonable ranges
+    int M = 1 + (std::abs(m_raw) % 128);
+    int N = 8 + (std::abs(n_raw) % 256);
+    int K = 32 + (std::abs(k_raw) % 512);
+    int group_size = 32;
+    int num_groups = (K + group_size - 1) / group_size;
+
+    // Generate random data
+    auto input = randomFP16(M, K, 0.5f);
+    auto weight = randomINT8(K, N);
+    auto scales = randomScales(num_groups, N);
+
+    // Allocate device memory
+    DeviceBuffer<half>   d_input(M * K);
+    DeviceBuffer<int8_t> d_weight(K * N);
+    DeviceBuffer<half>   d_scales(num_groups * N);
+    DeviceBuffer<half>   d_output(M * N);
+    DeviceBuffer<half>   d_weight_fp16(K * N);
+    DeviceBuffer<half>   d_output_ref(M * N);
+
+    d_input.copyFromHost(input.data(), M * K);
+    d_weight.copyFromHost(weight.data(), K * N);
+    d_scales.copyFromHost(scales.data(), num_groups * N);
+
+    // Run W8A16 kernel
+    w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(), d_output.data(), M, N, K,
+                 group_size);
+
+    // Dequantize and run FP16 reference
+    dequantize_weights(d_weight.data(), d_scales.data(), d_weight_fp16.data(), K, N, group_size);
+    fp16_matmul_reference(d_input.data(), d_weight_fp16.data(), d_output_ref.data(), M, N, K);
+
+    cudaDeviceSynchronize();
+
+    // Copy results back
+    std::vector<half> output(M * N);
+    std::vector<half> output_ref(M * N);
+    d_output.copyToHost(output.data(), M * N);
+    d_output_ref.copyToHost(output_ref.data(), M * N);
+    cudaDeviceSynchronize();
+
+    // Property: relative error should be < 1%
+    float rel_error = computeRelativeError(output, output_ref);
+    RC_ASSERT(rel_error < 0.01f);
 }
 
 RC_GTEST_FIXTURE_PROP(W8A16PropertyTest, DifferentGroupSizes,
                       (int m_raw, int n_raw, int k_raw, int gs_raw)) {
-  if (!hasCudaDevice()) {
-    RC_SKIP("No CUDA device available");
-  }
-  int M = 1 + (std::abs(m_raw) % 64);
-  int N = 8 + (std::abs(n_raw) % 128);
-  int K = 64 + (std::abs(k_raw) % 256);
-
-  // Test different group sizes: 32, 64, 128
-  int group_sizes[] = {32, 64, 128};
-  int group_size = group_sizes[std::abs(gs_raw) % 3];
-  int num_groups = (K + group_size - 1) / group_size;
-
-  auto input = randomFP16(M, K, 0.5f);
-  auto weight = randomINT8(K, N);
-  auto scales = randomScales(num_groups, N);
-
-  DeviceBuffer<half> d_input(M * K);
-  DeviceBuffer<int8_t> d_weight(K * N);
-  DeviceBuffer<half> d_scales(num_groups * N);
-  DeviceBuffer<half> d_output(M * N);
-  DeviceBuffer<half> d_weight_fp16(K * N);
-  DeviceBuffer<half> d_output_ref(M * N);
-
-  d_input.copyFromHost(input.data(), M * K);
-  d_weight.copyFromHost(weight.data(), K * N);
-  d_scales.copyFromHost(scales.data(), num_groups * N);
-
-  w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(),
-               d_output.data(), M, N, K, group_size);
-
-  dequantize_weights(d_weight.data(), d_scales.data(), d_weight_fp16.data(), K,
-                     N, group_size);
-  fp16_matmul_reference(d_input.data(), d_weight_fp16.data(),
-                        d_output_ref.data(), M, N, K);
-
-  cudaDeviceSynchronize();
-
-  std::vector<half> output(M * N);
-  std::vector<half> output_ref(M * N);
-  d_output.copyToHost(output.data(), M * N);
-  d_output_ref.copyToHost(output_ref.data(), M * N);
-  cudaDeviceSynchronize();
-
-  float rel_error = computeRelativeError(output, output_ref);
-  RC_ASSERT(rel_error < 0.01f);
+    if (!hasCudaDevice()) {
+        RC_SUCCEED("No CUDA device available");
+    }
+    int M = 1 + (std::abs(m_raw) % 64);
+    int N = 8 + (std::abs(n_raw) % 128);
+    int K = 64 + (std::abs(k_raw) % 256);
+
+    // Test different group sizes: 32, 64, 128
+    int group_sizes[] = {32, 64, 128};
+    int group_size = group_sizes[std::abs(gs_raw) % 3];
+    int num_groups = (K + group_size - 1) / group_size;
+
+    auto input = randomFP16(M, K, 0.5f);
+    auto weight = randomINT8(K, N);
+    auto scales = randomScales(num_groups, N);
+
+    DeviceBuffer<half>   d_input(M * K);
+    DeviceBuffer<int8_t> d_weight(K * N);
+    DeviceBuffer<half>   d_scales(num_groups * N);
+    DeviceBuffer<half>   d_output(M * N);
+    DeviceBuffer<half>   d_weight_fp16(K * N);
+    DeviceBuffer<half>   d_output_ref(M * N);
+
+    d_input.copyFromHost(input.data(), M * K);
+    d_weight.copyFromHost(weight.data(), K * N);
+    d_scales.copyFromHost(scales.data(), num_groups * N);
+
+    w8a16_matmul(d_input.data(), d_weight.data(), d_scales.data(), d_output.data(), M, N, K,
+                 group_size);
+
+    dequantize_weights(d_weight.data(), d_scales.data(), d_weight_fp16.data(), K, N, group_size);
+    fp16_matmul_reference(d_input.data(), d_weight_fp16.data(), d_output_ref.data(), M, N, K);
+
+    cudaDeviceSynchronize();
+
+    std::vector<half> output(M * N);
+    std::vector<half> output_ref(M * N);
+    d_output.copyToHost(output.data(), M * N);
+    d_output_ref.copyToHost(output_ref.data(), M * N);
+    cudaDeviceSynchronize();
+
+    float rel_error = computeRelativeError(output, output_ref);
+    RC_ASSERT(rel_error < 0.01f);
 }

From bf816379538213583e8a43143ec7f72609b3e77b Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 02:52:10 +0800
Subject: [PATCH 5/6] refactor(website): simplify and modernize website assets

- Consolidate CSS into streamlined custom.scss and new home.scss
- Remove outdated changelog entries (moved to OpenSpec)
- Simplify footer and head includes
- Update Gemfile with locked dependencies
- Streamline index page and manifest
---
 website/404.html                              |  29 +-
 website/CONTRIBUTING.md                       |  69 +-
 website/Gemfile                               |   9 +-
 website/Gemfile.lock                          | 252 ++++++
 website/_config.yml                           | 146 +---
 website/_includes/footer_custom.html          | 317 ++------
 website/_includes/head_custom.html            |  95 ++-
 website/_sass/custom.scss                     | 649 ---------------
 website/assets/css/custom.css                 | 288 -------
 website/assets/css/custom.scss                | 747 +++++-------------
 website/assets/css/home.scss                  | 588 ++++++++++++++
 website/assets/js/main.js                     | 145 ++--
 .../changelog/en/docs-ci-standardization.md   | 150 ----
 website/changelog/en/pages-enhancement.md     | 123 ---
 .../changelog/en/project-infrastructure.md    |  85 --
 website/changelog/index.md                    |  43 +-
 website/changelog/index.zh.md                 |  43 +-
 .../changelog/zh/docs-ci-standardization.md   | 150 ----
 website/changelog/zh/pages-enhancement.md     | 123 ---
 .../changelog/zh/project-infrastructure.md    |  85 --
 website/docs/en/ARCHITECTURE.md               |  13 -
 website/docs/index.md                         |   4 +-
 website/docs/zh/ARCHITECTURE.md               |  13 -
 website/index.md                              |  98 +--
 website/manifest.json                         |  32 +-
 website/sw.js                                 | 178 +----
 26 files changed, 1385 insertions(+), 3089 deletions(-)
 create mode 100644 website/Gemfile.lock
 delete mode 100644 website/_sass/custom.scss
 delete mode 100644 website/assets/css/custom.css
 create mode 100644 website/assets/css/home.scss
 delete mode 100644 website/changelog/en/docs-ci-standardization.md
 delete mode 100644 website/changelog/en/pages-enhancement.md
 delete mode 100644 website/changelog/en/project-infrastructure.md
 delete mode 100644 website/changelog/zh/docs-ci-standardization.md
 delete mode 100644 website/changelog/zh/pages-enhancement.md
 delete mode 100644 website/changelog/zh/project-infrastructure.md

diff --git a/website/404.html b/website/404.html
index acf7956..c8bf330 100644
--- a/website/404.html
+++ b/website/404.html
@@ -13,18 +13,18 @@
   <p>Sorry, the page you're looking for doesn't exist or has been moved.</p>
 
   <div class="error-actions">
-    <a href="/" class="btn btn-primary">Return Home</a>
-    <a href="/docs/en/" class="btn btn-secondary">Documentation</a>
+    <a href="{{ site.baseurl }}/" class="btn btn-primary">Return Home</a>
+    <a href="{{ site.baseurl }}/docs/en/" class="btn btn-secondary">Documentation</a>
   </div>
 
   <div class="error-suggestions">
     <h3>You might be looking for:</h3>
     <ul>
-      <li><a href="/">Tiny-LLM Home</a></li>
-      <li><a href="/docs/en/">English Documentation</a></li>
-      <li><a href="/docs/zh/">中文文档</a></li>
-      <li><a href="/changelog/">Changelog</a></li>
-      <li><a href="https://github.com/LessUp/tiny-llm">GitHub Repository</a></li>
+      <li><a href="{{ site.baseurl }}/">Tiny-LLM Home</a></li>
+      <li><a href="{{ site.baseurl }}/docs/en/">English Documentation</a></li>
+      <li><a href="{{ site.baseurl }}/docs/zh/">中文文档</a></li>
+      <li><a href="{{ site.baseurl }}/changelog/">Changelog</a></li>
+      <li><a href="{{ site.repo_url }}">GitHub Repository</a></li>
     </ul>
   </div>
 </div>
@@ -37,13 +37,13 @@ <h3>You might be looking for:</h3>
 .error-code {
   font-size: 8rem;
   font-weight: 800;
-  color: var(--color-brand-primary);
+  color: #58a6ff;
   line-height: 1;
   margin-bottom: 1rem;
 }
 .error-message {
   font-size: 1.5rem;
-  color: var(--color-text-secondary);
+  color: var(--text-secondary-color, #8b949e);
   margin-bottom: 1.5rem;
 }
 .error-actions {
@@ -56,13 +56,16 @@ <h3>You might be looking for:</h3>
 .error-suggestions {
   margin-top: 3rem;
   padding: 1.5rem;
-  background: var(--color-bg-secondary);
-  border-radius: var(--radius-lg);
+  background: var(--surface-color, #161b22);
+  border-radius: 12px;
   text-align: left;
+  max-width: 400px;
+  margin-left: auto;
+  margin-right: auto;
 }
 .error-suggestions h3 {
   margin-top: 0;
-  color: var(--color-text-primary);
+  color: var(--text-color, #f0f6fc);
 }
 .error-suggestions ul {
   list-style: none;
@@ -72,7 +75,7 @@ <h3>You might be looking for:</h3>
   margin: 0.5rem 0;
 }
 .error-suggestions a {
-  color: var(--color-text-link);
+  color: #58a6ff;
   text-decoration: none;
 }
 .error-suggestions a:hover {
diff --git a/website/CONTRIBUTING.md b/website/CONTRIBUTING.md
index 7557879..3c0b79e 100644
--- a/website/CONTRIBUTING.md
+++ b/website/CONTRIBUTING.md
@@ -7,72 +7,47 @@ nav_order: 50
 
 # Contributing to Tiny-LLM
 
-Thank you for your interest in contributing to Tiny-LLM! We welcome contributions via Issues and Pull Requests.
+Tiny-LLM is in a final hardening phase. Contributions are welcome, but the repository now favors **focused, OpenSpec-driven improvements** over broad feature expansion.
 
 ---
 
-## Development Workflow
+## Required workflow
 
-This project follows **Spec-Driven Development (SDD)**. Before writing code, you must first update or create the relevant specification documents.
+1. Use `/opsx:explore` when the scope or requirements are still fuzzy.
+2. Use `/opsx:propose <change-name>` for non-trivial work so the change is captured in `openspec/`.
+3. Use `/opsx:apply <change-name>` to implement task-by-task.
+4. Run a review pass before concluding major workstreams.
+5. Use `/opsx:archive <change-name>` only after specs, code, and docs are aligned.
 
-1. **Update/Create Specs**: Update or create product requirements, RFCs, or API definitions in `/specs`
-2. Fork this repository
-3. Create a feature branch: `git checkout -b feature/your-feature`
-4. Make your changes and ensure tests pass
-5. Commit your changes: `git commit -m "feat: add your feature"`
-6. Push to the branch: `git push origin feature/your-feature`
-7. Create a Pull Request
-
-> Detailed AI assistant workflow: see [AGENTS.md](https://github.com/LessUp/tiny-llm/blob/main/AGENTS.md)
+> Repository-specific workflow and architecture constraints live in [AGENTS.md](https://github.com/LessUp/tiny-llm/blob/master/AGENTS.md).
 
 ---
 
-## Build & Test
+## Build and validate
 
 ```bash
-# Clone repository
-git clone https://github.com/LessUp/tiny-llm.git
-cd tiny-llm
-
-# Build
-mkdir build && cd build
-cmake .. -DCMAKE_BUILD_TYPE=Release
-make -j$(nproc)
-
-# Run tests
-ctest --output-on-failure
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
+cmake --build build -j$(nproc)
+ctest --test-dir build --output-on-failure --timeout 300
 ```
 
 ---
 
-## Requirements
+## Contribution principles
 
-- **NVIDIA GPU**: Compute Capability 7.0+ (Volta or newer)
-- **CUDA Toolkit**: 11.0 or higher
-- **CMake**: 3.18 or higher
-- **C++ Compiler**: GCC 9+ or Clang 10+
+- Keep branches short-lived and avoid local/cloud drift.
+- Prefer deleting or merging duplicated docs over preserving parallel guidance.
+- Keep public claims aligned with the actual implementation and validated documentation.
+- Treat CI as validation, not as a system that rewrites tracked files for contributors.
 
 ---
 
-## Code Standards
+## Where to look next
 
-- **C++17** for all C++ code
-- **CUDA 11.0+** for GPU kernels
-- **CMake 3.18+** for build configuration
-- Error handling via `Result<T>` monad (no exceptions for control flow)
+- [Repository guide](https://github.com/LessUp/tiny-llm/blob/master/AGENTS.md)
+- [Current specs](https://github.com/LessUp/tiny-llm/tree/master/openspec/specs)
+- [Open changes](https://github.com/LessUp/tiny-llm/tree/master/openspec/changes)
 
 ---
 
-## Getting Help
-
-- **Issues**: [Report bugs or request features](https://github.com/LessUp/tiny-llm/issues)
-- **Discussions**: [Ask questions](https://github.com/LessUp/tiny-llm/discussions)
-- **Documentation**: [Read the docs](/docs/en/)
-
----
-
-## License
-
-By contributing, you agree that your contributions will be licensed under the MIT License.
-
-[← Home](/) | [Documentation](/docs/en/)
+[← Home](/) | [Docs](/docs/en/) | [GitHub](https://github.com/LessUp/tiny-llm)
diff --git a/website/Gemfile b/website/Gemfile
index 3c3e281..056108d 100644
--- a/website/Gemfile
+++ b/website/Gemfile
@@ -1,22 +1,17 @@
-# ═══════════════════════════════════════════════════════════════
-# Tiny-LLM Jekyll Dependencies - Production Ready
-# ═══════════════════════════════════════════════════════════════
-
 source "https://rubygems.org"
 
 # Jekyll Core
 gem "jekyll", "~> 4.3.0"
+gem "base64", "~> 0.3"
+gem "csv", "~> 3.3"
 
 # Theme
 gem "just-the-docs", "~> 0.7.0"
 
 # Plugins
 group :jekyll_plugins do
-  gem "jekyll-remote-theme"
   gem "jekyll-seo-tag"
   gem "jekyll-sitemap"
-  gem "jekyll-github-metadata"
-  gem "jekyll-include-cache"
 end
 
 # Windows and JRuby specific dependencies
diff --git a/website/Gemfile.lock b/website/Gemfile.lock
new file mode 100644
index 0000000..ed648f2
--- /dev/null
+++ b/website/Gemfile.lock
@@ -0,0 +1,252 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    colorator (1.1.0)
+    concurrent-ruby (1.3.6)
+    csv (3.3.5)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.17.4)
+    ffi (1.17.4-aarch64-linux-gnu)
+    ffi (1.17.4-aarch64-linux-musl)
+    ffi (1.17.4-arm-linux-gnu)
+    ffi (1.17.4-arm-linux-musl)
+    ffi (1.17.4-arm64-darwin)
+    ffi (1.17.4-x86-linux-gnu)
+    ffi (1.17.4-x86-linux-musl)
+    ffi (1.17.4-x86_64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
+    ffi (1.17.4-x86_64-linux-musl)
+    forwardable-extended (2.6.0)
+    google-protobuf (4.34.1)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-aarch64-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-aarch64-linux-musl)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-arm64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86-linux-musl)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86_64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86_64-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86_64-linux-musl)
+      bigdecimal
+      rake (~> 13.3)
+    http_parser.rb (0.8.1)
+    i18n (1.14.8)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.3.4)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.1.0)
+      sass-embedded (~> 1.75)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    just-the-docs (0.7.0)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.10.0)
+      logger
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (7.0.5)
+    rake (13.4.2)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    rexml (3.4.4)
+    rouge (4.7.0)
+    safe_yaml (1.0.5)
+    sass-embedded (1.99.0)
+      google-protobuf (~> 4.31)
+      rake (>= 13)
+    sass-embedded (1.99.0-aarch64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-aarch64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-aarch64-linux-musl)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-arm-linux-androideabi)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-arm-linux-gnueabihf)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-arm-linux-musleabihf)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-arm64-darwin)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-riscv64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-riscv64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-riscv64-linux-musl)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-x86_64-darwin)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-x86_64-linux-android)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-x86_64-linux-gnu)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-x86_64-linux-musl)
+      google-protobuf (~> 4.31)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.6.0)
+    webrick (1.9.2)
+
+PLATFORMS
+  aarch64-linux-android
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-androideabi
+  arm-linux-gnu
+  arm-linux-gnueabihf
+  arm-linux-musl
+  arm-linux-musleabihf
+  arm64-darwin
+  riscv64-linux-android
+  riscv64-linux-gnu
+  riscv64-linux-musl
+  ruby
+  x86-linux-gnu
+  x86-linux-musl
+  x86_64-darwin
+  x86_64-linux-android
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  base64 (~> 0.3)
+  csv (~> 3.3)
+  http_parser.rb (~> 0.6.0)
+  jekyll (~> 4.3.0)
+  jekyll-seo-tag
+  jekyll-sitemap
+  just-the-docs (~> 0.7.0)
+  tzinfo (>= 1, < 3)
+  tzinfo-data
+  wdm (~> 0.1.1)
+  webrick (~> 1.8)
+
+CHECKSUMS
+  addressable (2.9.0) sha256=7fdf6ac3660f7f4e867a0838be3f6cf722ace541dd97767fa42bc6cfa980c7af
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  colorator (1.1.0) sha256=e2f85daf57af47d740db2a32191d1bdfb0f6503a0dfbc8327d0c9154d5ddfc38
+  concurrent-ruby (1.3.6) sha256=6b56837e1e7e5292f9864f34b69c5a2cbc75c0cf5338f1ce9903d10fa762d5ab
+  csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f
+  em-websocket (0.5.3) sha256=f56a92bde4e6cb879256d58ee31f124181f68f8887bd14d53d5d9a292758c6a8
+  eventmachine (1.2.7) sha256=994016e42aa041477ba9cff45cbe50de2047f25dd418eba003e84f0d16560972
+  ffi (1.17.4) sha256=bcd1642e06f0d16fc9e09ac6d49c3a7298b9789bcb58127302f934e437d60acf
+  ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
+  ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39
+  ffi (1.17.4-arm-linux-gnu) sha256=d6dbddf7cb77bf955411af5f187a65b8cd378cb003c15c05697f5feee1cb1564
+  ffi (1.17.4-arm-linux-musl) sha256=9d4838ded0465bef6e2426935f6bcc93134b6616785a84ffd2a3d82bc3cf6f95
+  ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b
+  ffi (1.17.4-x86-linux-gnu) sha256=38e150df5f4ca555e25beca4090823ae09657bceded154e3c52f8631c1ed72cf
+  ffi (1.17.4-x86-linux-musl) sha256=fbeec0fc7c795bcf86f623bb18d31ea1820f7bd580e1703a3d3740d527437809
+  ffi (1.17.4-x86_64-darwin) sha256=aa70390523cf3235096cf64962b709b4cfbd5c082a2cb2ae714eb0fe2ccda496
+  ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d
+  ffi (1.17.4-x86_64-linux-musl) sha256=3fdf9888483de005f8ef8d1cf2d3b20d86626af206cbf780f6a6a12439a9c49e
+  forwardable-extended (2.6.0) sha256=1bec948c469bbddfadeb3bd90eb8c85f6e627a412a3e852acfd7eaedbac3ec97
+  google-protobuf (4.34.1) sha256=347181542b8d659c60f028fa3791c9cccce651a91ad27782dbc5c5e374796cdc
+  google-protobuf (4.34.1-aarch64-linux-gnu) sha256=f9c07607dc139c895f2792a7740fcd01cd94d4d7b0e0a939045b50d7999f0b1d
+  google-protobuf (4.34.1-aarch64-linux-musl) sha256=db58e5a4a492b43c6614486aea31b7fb86955b175d1d48f28ebf388f058d78a9
+  google-protobuf (4.34.1-arm64-darwin) sha256=2745061f973119e6e7f3c81a0c77025d291a3caa6585a2cd24a25bbc7bedb267
+  google-protobuf (4.34.1-x86-linux-gnu) sha256=b6da7891fe96b13038e5435d8ac8b8a84d78a468147a48a377fe8da40aba1c88
+  google-protobuf (4.34.1-x86-linux-musl) sha256=ea0f453e78f4c30d0d9dbaa8cf9b33d2a1ea04ab2cad2c2a07e479411c05f1a9
+  google-protobuf (4.34.1-x86_64-darwin) sha256=4dc498376e218871613589c4d872400d42ad9ae0c700bdb2606fe1c77a593075
+  google-protobuf (4.34.1-x86_64-linux-gnu) sha256=87088c9fd8e47b5b40ca498fc1195add6149e941ff7e81c532a5b0b8876d4cc9
+  google-protobuf (4.34.1-x86_64-linux-musl) sha256=8c0e91436fbe504ffc64f0bd621f2e69adbcce8ed2c58439d7a21117069cfdd7
+  http_parser.rb (0.8.1) sha256=9ae8df145b39aa5398b2f90090d651c67bd8e2ebfe4507c966579f641e11097a
+  i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
+  jekyll (4.3.4) sha256=c488282c2819c392d34d3a3784eacde2cde4b61c8e3c9c9295f6c01fb1754404
+  jekyll-include-cache (0.2.1) sha256=c7d4b9e551732a27442cb2ce853ba36a2f69c66603694b8c1184c99ab1a1a205
+  jekyll-sass-converter (3.1.0) sha256=83925d84f1d134410c11d0c6643b0093e82e3a3cf127e90757a85294a3862443
+  jekyll-seo-tag (2.8.0) sha256=3f2ed1916d56f14ebfa38e24acde9b7c946df70cb183af2cb5f0598f21ae6818
+  jekyll-sitemap (1.4.0) sha256=0de08c5debc185ea5a8f980e1025c7cd3f8e0c35c8b6ef592f15c46235cf4218
+  jekyll-watch (2.2.1) sha256=bc44ed43f5e0a552836245a54dbff3ea7421ecc2856707e8a1ee203a8387a7e1
+  just-the-docs (0.7.0) sha256=0842268b04a13d8ac632d5546f9e30ee212611ffeeae4ea0a55f77e5664ca888
+  kramdown (2.5.2) sha256=1ba542204c66b6f9111ff00dcc26075b95b220b07f2905d8261740c82f7f02fa
+  kramdown-parser-gfm (1.1.0) sha256=fb39745516427d2988543bf01fc4cf0ab1149476382393e0e9c48592f6581729
+  liquid (4.0.4) sha256=4fcfebb1a045e47918388dbb7a0925e7c3893e58d2bd6c3b3c73ec17a2d8fdb3
+  listen (3.10.0) sha256=c6e182db62143aeccc2e1960033bebe7445309c7272061979bb098d03760c9d2
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  mercenary (0.4.0) sha256=b25a1e4a59adca88665e08e24acf0af30da5b5d859f7d8f38fba52c28f405138
+  pathutil (0.16.2) sha256=e43b74365631cab4f6d5e4228f812927efc9cb2c71e62976edcb252ee948d589
+  public_suffix (7.0.5) sha256=1a8bb08f1bbea19228d3bed6e5ed908d1cb4f7c2726d18bd9cadf60bc676f623
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  rb-fsevent (0.11.2) sha256=43900b972e7301d6570f64b850a5aa67833ee7d87b458ee92805d56b7318aefe
+  rb-inotify (0.11.1) sha256=a0a700441239b0ff18eb65e3866236cd78613d6b9f78fea1f9ac47a85e47be6e
+  rexml (3.4.4) sha256=19e0a2c3425dfbf2d4fc1189747bdb2f849b6c5e74180401b15734bc97b5d142
+  rouge (4.7.0) sha256=dba5896715c0325c362e895460a6d350803dbf6427454f49a47500f3193ea739
+  safe_yaml (1.0.5) sha256=a6ac2d64b7eb027bdeeca1851fe7e7af0d668e133e8a88066a0c6f7087d9f848
+  sass-embedded (1.99.0) sha256=61942229dc7da4f335688196d43c1d3d5314060667a43ccf48f4b4c41b5578e1
+  sass-embedded (1.99.0-aarch64-linux-android) sha256=3b077c8436424b45eb04edaa46514fc92cc333f17b3fcca45857d124d453cdf1
+  sass-embedded (1.99.0-aarch64-linux-gnu) sha256=a46615b0295ca7bd979b9ce79f6b9f1d26881736400188bd6fd5c4b7c9b46473
+  sass-embedded (1.99.0-aarch64-linux-musl) sha256=eaa6d56968909d1d54073c46e21c13fd5bbcb5af609d7e4fbe6b196426ca8e49
+  sass-embedded (1.99.0-arm-linux-androideabi) sha256=9089a3aca8f16f855a2fc848c0762b09aef23251f91ec9714fea31c28c9094df
+  sass-embedded (1.99.0-arm-linux-gnueabihf) sha256=f5f0748934660cda6948917af6dc974caf4d36ea6121e450982153b7d9c49b55
+  sass-embedded (1.99.0-arm-linux-musleabihf) sha256=29a4056e76bc136025ba5d03e82d86ecdabfb6c07a473a4fdedcd72fb28dbbc4
+  sass-embedded (1.99.0-arm64-darwin) sha256=20773f2fb0e8f4d0194eb1874dab4c0ef60262ff6dafe29361e217beb2208629
+  sass-embedded (1.99.0-riscv64-linux-android) sha256=7ac1145c066670d5918a7afae8445338c45b4d8e34ad2968bda7099665ba8d15
+  sass-embedded (1.99.0-riscv64-linux-gnu) sha256=b8c421eba2e41fa3c94bffc971611d803aae336586a3baf2933c99e1c7548f88
+  sass-embedded (1.99.0-riscv64-linux-musl) sha256=63b924eb97548bd1f31193c36fab89bb100cd1a9bd144789a9a596fc98244a09
+  sass-embedded (1.99.0-x86_64-darwin) sha256=371774c83b6dce8a2cb7b5ce5a0f918ff2735bf200b00e3bc7067366654fff13
+  sass-embedded (1.99.0-x86_64-linux-android) sha256=39c51b80c292fdb5157fee9166793374104c4e6639d77dfefc36c339aa5dce12
+  sass-embedded (1.99.0-x86_64-linux-gnu) sha256=a4e2ae5e9951815cb8b3ab408cee8b800852491988a57de735f18d259c70d7c4
+  sass-embedded (1.99.0-x86_64-linux-musl) sha256=94be72a6f856c610e67b12303dc76a58412e64b24ce97bdf4912199b8145c8dd
+  terminal-table (3.0.2) sha256=f951b6af5f3e00203fb290a669e0a85c5dd5b051b3b023392ccfd67ba5abae91
+  unicode-display_width (2.6.0) sha256=12279874bba6d5e4d2728cef814b19197dbb10d7a7837a869bab65da943b7f5a
+  webrick (1.9.2) sha256=beb4a15fc474defed24a3bda4ffd88a490d517c9e4e6118c3edce59e45864131
+
+BUNDLED WITH
+  4.0.10
diff --git a/website/_config.yml b/website/_config.yml
index e4385aa..c47e1da 100644
--- a/website/_config.yml
+++ b/website/_config.yml
@@ -1,26 +1,20 @@
-# ═══════════════════════════════════════════════════════════════
-# Tiny-LLM Documentation - Modern Jekyll Configuration
-# Theme: Just the Docs (Custom Enhanced)
-# Features: PWA, Dark Mode, Search, Modern UI
-# ═══════════════════════════════════════════════════════════════
+# Tiny-LLM Documentation Site Configuration
+# Jekyll with Just the Docs Theme
 
+# Site Settings
 title: Tiny-LLM
 description: High-Performance CUDA Inference Engine for LLMs
-tagline: Lightweight, efficient LLM inference with W8A16 quantization and KV Cache optimization
-author: LessUp Team
+tagline: Lightweight LLM inference with W8A16 quantization and KV Cache optimization
+author: LessUp
 url: "https://lessup.github.io"
 baseurl: "/tiny-llm"
 lang: en
 
-# ═══════════════════════════════════════════════════════════════
-# THEME CONFIGURATION
-# ═══════════════════════════════════════════════════════════════
-remote_theme: just-the-docs/just-the-docs@v0.7.0
-
-# Theme Color Scheme
+# Theme Configuration
+theme: just-the-docs
 color_scheme: dark
 
-# Enable search
+# Search Configuration
 search_enabled: true
 search:
   heading_level: 3
@@ -31,14 +25,14 @@ search:
   rel_url: true
   button: false
 
-# Enable copy code button
+# Code Blocks
 enable_copy_code_button: true
 
-# Mermaid diagrams
+# Mermaid Diagrams
 mermaid:
   version: "10.6.1"
 
-# Aux links (top right navigation)
+# Navigation
 aux_links:
   "GitHub":
     - "https://github.com/LessUp/tiny-llm"
@@ -46,10 +40,18 @@ aux_links:
     - "https://github.com/LessUp/tiny-llm/releases"
 aux_links_new_tab: true
 
-# Footer content
-footer_content: "Copyright &copy; 2025 LessUp. Distributed under MIT License."
+nav_external_links:
+  - title: GitHub
+    url: https://github.com/LessUp/tiny-llm
+    hide_icon: false
+  - title: Releases
+    url: https://github.com/LessUp/tiny-llm/releases
+    hide_icon: false
 
-# Back to top link
+nav_sort: case_insensitive
+
+# Footer
+footer_content: "Copyright &copy; 2025 LessUp. Distributed under MIT License."
 back_to_top: true
 back_to_top_text: "Back to top"
 
@@ -78,33 +80,12 @@ callouts:
     title: Warning
     color: red
 
-# ═══════════════════════════════════════════════════════════════
-# PLUGINS
-# ═══════════════════════════════════════════════════════════════
+# Plugins
 plugins:
-  - jekyll-remote-theme
   - jekyll-seo-tag
   - jekyll-sitemap
-  - jekyll-github-metadata
-  - jekyll-include-cache
 
-# ═══════════════════════════════════════════════════════════════
-# NAVIGATION STRUCTURE
-# ═══════════════════════════════════════════════════════════════
-nav_external_links:
-  - title: GitHub
-    url: https://github.com/LessUp/tiny-llm
-    hide_icon: false
-  - title: Releases
-    url: https://github.com/LessUp/tiny-llm/releases
-    hide_icon: false
-
-# Navigation order and structure
-nav_sort: case_insensitive
-
-# ═══════════════════════════════════════════════════════════════
-# MARKDOWN & CODE HIGHLIGHTING
-# ═══════════════════════════════════════════════════════════════
+# Markdown Configuration
 markdown: kramdown
 kramdown:
   input: GFM
@@ -117,84 +98,37 @@ kramdown:
     span:
       line_numbers: false
 
-# ═══════════════════════════════════════════════════════════════
-# SEO & SOCIAL
-# ═══════════════════════════════════════════════════════════════
+# SEO & Social
+logo: "/assets/images/logo.svg"
 twitter:
+  card: summary
   username: lessup
-  card: summary_large_image
 
 social:
   name: Tiny-LLM
   links:
     - https://github.com/LessUp/tiny-llm
 
-logo: "/assets/images/logo.svg"
-favicon_ico: "/assets/icons/icon-192x192.svg"
+# Custom Variables
+version: "2.0.1"
+release_url: https://github.com/LessUp/tiny-llm/releases/latest
+repo_url: https://github.com/LessUp/tiny-llm
+docs_url: https://lessup.github.io/tiny-llm/docs
 
-# ═══════════════════════════════════════════════════════════════
-# PWA CONFIGURATION
-# ═══════════════════════════════════════════════════════════════
-pwa:
-  enabled: true
-  name: Tiny-LLM Docs
-  short_name: TinyLLM
-  description: High-Performance CUDA Inference Engine Documentation
-  theme_color: "#0d1117"
-  background_color: "#0d1117"
-  display: standalone
-  orientation: portrait
-  scope: "/tiny-llm/"
-  start_url: "/tiny-llm/"
-
-# ═══════════════════════════════════════════════════════════════
-# DEFAULTS (FRONTMATTER)
-# ═══════════════════════════════════════════════════════════════
-defaults:
-  - scope:
-      path: ""
-    values:
-      layout: "default"
-      nav_exclude: false
-  - scope:
-      path: "docs"
-    values:
-      layout: "page"
-  - scope:
-      path: "docs/en"
-    values:
-      lang: en
-      layout: "page"
-  - scope:
-      path: "docs/zh"
-    values:
-      lang: zh
-      layout: "page"
-  - scope:
-      path: "changelog"
-    values:
-      layout: "page"
-      nav_order: 99
-
-# ═══════════════════════════════════════════════════════════════
-# EXCLUDE & INCLUDE
-# ═══════════════════════════════════════════════════════════════
+# Sass Configuration
+sass:
+  sass_dir: _sass
+  style: compressed
+
+# Build Settings
 exclude:
   - .git
   - .github
-  - .kiro
-  - .vscode
   - Gemfile
   - Gemfile.lock
   - "*.cpp"
   - "*.cu"
   - "*.cuh"
   - "*.h"
-
-# ═══════════════════════════════════════════════════════════════
-# CUSTOM VARIABLES
-# ═══════════════════════════════════════════════════════════════
-version: "2.1.0"
-release_url: https://github.com/LessUp/tiny-llm/releases/latest
-repo_url: https://github.com/LessUp/tiny-llm
-docs_url: https://lessup.github.io/tiny-llm/docs
+  - README.md
+  - CONTRIBUTING.md
diff --git a/website/_includes/footer_custom.html b/website/_includes/footer_custom.html
index 8684e9c..75b1879 100644
--- a/website/_includes/footer_custom.html
+++ b/website/_includes/footer_custom.html
@@ -1,189 +1,80 @@
-<!-- ═══════════════════════════════════════════════════════════════
-     Tiny-LLM Custom Footer - Theme Toggle & Updates
-     ═══════════════════════════════════════════════════════════════ -->
-
 <!-- Theme Toggle Button -->
 <div class="theme-toggle">
-  <button id="theme-toggle-btn" aria-label="Toggle dark/light theme">
+  <button id="theme-toggle-btn" aria-label="Toggle between dark and light theme">
     <span class="theme-icon-light" style="display: none;">☀️</span>
     <span class="theme-icon-dark">🌙</span>
   </button>
 </div>
 
-<!-- Quick Links Section -->
-<div class="footer-links">
-  <h4>Quick Links</h4>
-  <div class="footer-grid">
-    <div>
-      <h5>Documentation</h5>
-      <ul>
-        <li><a href="{{ site.baseurl }}/docs/en/QUICKSTART">Quick Start</a></li>
-        <li><a href="{{ site.baseurl }}/docs/en/ARCHITECTURE">Architecture</a></li>
-        <li><a href="{{ site.baseurl }}/docs/en/API">API Reference</a></li>
-      </ul>
-    </div>
-    <div>
-      <h5>Resources</h5>
-      <ul>
-        <li><a href="{{ site.baseurl }}/changelog/">Changelog</a></li>
-        <li><a href="https://github.com/LessUp/tiny-llm/releases">Releases</a></li>
-        <li><a href="{{ site.baseurl }}/docs/en/TROUBLESHOOTING">Troubleshooting</a></li>
-      </ul>
-    </div>
-    <div>
-      <h5>Community</h5>
-      <ul>
-        <li><a href="https://github.com/LessUp/tiny-llm">GitHub</a></li>
-        <li><a href="{{ site.baseurl }}/CONTRIBUTING">Contributing</a></li>
-        <li><a href="{{ site.baseurl }}/docs/en/DEVELOPER">Developer Guide</a></li>
-      </ul>
-    </div>
-  </div>
-</div>
-
-<!-- PWA Update Notification -->
-<div id="update-notification" class="update-notification" style="display: none;">
-  <div class="update-content">
-    <span>📦 New version available!</span>
-    <button id="update-app-btn">Update Now</button>
-    <button id="dismiss-update-btn">Later</button>
-  </div>
-</div>
-
-<!-- Theme Toggle Script -->
 <script>
-  (function() {
-    const toggleBtn = document.getElementById('theme-toggle-btn');
-    const lightIcon = document.querySelector('.theme-icon-light');
-    const darkIcon = document.querySelector('.theme-icon-dark');
-    
-    // Check current theme
-    function updateIcons() {
-      const currentTheme = document.documentElement.getAttribute('data-theme') || 'dark';
-      if (currentTheme === 'dark') {
-        lightIcon.style.display = 'none';
-        darkIcon.style.display = 'block';
-      } else {
-        lightIcon.style.display = 'block';
-        darkIcon.style.display = 'none';
-      }
+(function() {
+  var toggleBtn = document.getElementById('theme-toggle-btn');
+  var lightIcon = document.querySelector('.theme-icon-light');
+  var darkIcon = document.querySelector('.theme-icon-dark');
+  
+  // Get current theme from classList
+  function getCurrentTheme() {
+    if (document.documentElement.classList.contains('light-theme')) {
+      return 'light';
     }
+    return 'dark';
+  }
+  
+  // Update icons based on current theme
+  function updateIcons() {
+    var theme = getCurrentTheme();
+    if (theme === 'dark') {
+      lightIcon.style.display = 'none';
+      darkIcon.style.display = 'block';
+    } else {
+      lightIcon.style.display = 'block';
+      darkIcon.style.display = 'none';
+    }
+  }
+  
+  // Initial icon state
+  updateIcons();
+  
+  // Toggle handler
+  toggleBtn.addEventListener('click', function() {
+    var currentTheme = getCurrentTheme();
+    var newTheme = currentTheme === 'dark' ? 'light' : 'dark';
     
-    // Initial icon state
-    updateIcons();
-    
-    // Toggle handler
-    toggleBtn.addEventListener('click', function() {
-      const currentTheme = document.documentElement.getAttribute('data-theme') || 'dark';
-      const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
-      
-      document.documentElement.setAttribute('data-theme', newTheme);
-      localStorage.setItem('theme', newTheme);
-      
-      updateIcons();
-    });
+    // Toggle classes on html element
+    if (newTheme === 'light') {
+      document.documentElement.classList.remove('dark-theme');
+      document.documentElement.classList.add('light-theme');
+    } else {
+      document.documentElement.classList.remove('light-theme');
+      document.documentElement.classList.add('dark-theme');
+    }
     
-    // Listen for system theme changes
-    window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function(e) {
-      if (!localStorage.getItem('theme')) {
-        const newTheme = e.matches ? 'dark' : 'light';
-        document.documentElement.setAttribute('data-theme', newTheme);
-        updateIcons();
-      }
-    });
+    // Save preference
+    localStorage.setItem('theme', newTheme);
     
-    // PWA Update handling
-    if ('serviceWorker' in navigator) {
-      let refreshing = false;
-      
-      navigator.serviceWorker.addEventListener('message', function(event) {
-        if (event.data.type === 'UPDATE_AVAILABLE') {
-          showUpdateNotification();
-        }
-      });
-      
-      // Check for updates periodically
-      setInterval(function() {
-        navigator.serviceWorker.ready.then(function(registration) {
-          registration.update();
-        });
-      }, 60000); // Check every minute
-      
-      function showUpdateNotification() {
-        const notification = document.getElementById('update-notification');
-        notification.style.display = 'block';
-        
-        document.getElementById('update-app-btn').addEventListener('click', function() {
-          if (confirm('Update to latest version? The page will reload.')) {
-            navigator.serviceWorker.ready.then(function(registration) {
-              registration.waiting?.postMessage({ type: 'SKIP_WAITING' });
-            });
-          }
-        });
-        
-        document.getElementById('dismiss-update-btn').addEventListener('click', function() {
-          notification.style.display = 'none';
-        });
+    // Update icons
+    updateIcons();
+  });
+  
+  // Listen for system theme changes
+  window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function(e) {
+    // Only apply if no saved preference
+    if (!localStorage.getItem('theme')) {
+      if (e.matches) {
+        document.documentElement.classList.remove('light-theme');
+        document.documentElement.classList.add('dark-theme');
+      } else {
+        document.documentElement.classList.remove('dark-theme');
+        document.documentElement.classList.add('light-theme');
       }
-      
-      navigator.serviceWorker.addEventListener('controllerchange', function() {
-        if (!refreshing) {
-          refreshing = true;
-          window.location.reload();
-        }
-      });
+      updateIcons();
     }
-  })();
+  });
+})();
 </script>
 
 <style>
-.footer-links {
-  margin-top: 2rem;
-  padding-top: 2rem;
-  border-top: 1px solid var(--color-border-primary);
-}
-
-.footer-links h4 {
-  margin-bottom: 1rem;
-  color: var(--color-text-primary);
-  font-size: 1.1rem;
-}
-
-.footer-grid {
-  display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
-  gap: 1.5rem;
-}
-
-.footer-grid h5 {
-  font-size: 0.9rem;
-  color: var(--color-text-secondary);
-  margin-bottom: 0.5rem;
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
-}
-
-.footer-grid ul {
-  list-style: none;
-  padding: 0;
-  margin: 0;
-}
-
-.footer-grid li {
-  margin: 0.3rem 0;
-}
-
-.footer-grid a {
-  color: var(--color-text-tertiary);
-  font-size: 0.875rem;
-  text-decoration: none;
-  transition: color 0.2s;
-}
-
-.footer-grid a:hover {
-  color: var(--color-text-link);
-}
-
+/* Theme Toggle Button Styles */
 .theme-toggle {
   position: fixed;
   bottom: 2rem;
@@ -192,15 +83,15 @@ <h5>Community</h5>
 }
 
 .theme-toggle button {
-  width: 50px;
-  height: 50px;
+  width: 48px;
+  height: 48px;
   border-radius: 50%;
-  background: var(--color-bg-elevated);
-  border: 1px solid var(--color-border-primary);
+  background: var(--surface-color, #21262d);
+  border: 1px solid var(--border-color, #30363d);
   box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
   cursor: pointer;
-  font-size: 1.5rem;
-  transition: all 0.3s ease;
+  font-size: 1.25rem;
+  transition: all 0.2s ease;
   display: flex;
   align-items: center;
   justify-content: center;
@@ -211,85 +102,17 @@ <h5>Community</h5>
   box-shadow: 0 0 20px rgba(88, 166, 255, 0.4);
 }
 
-.update-notification {
-  position: fixed;
-  bottom: 6rem;
-  right: 2rem;
-  background: var(--color-bg-elevated);
-  border: 1px solid var(--color-brand-primary);
-  border-radius: 8px;
-  padding: 1rem 1.5rem;
-  box-shadow: 0 4px 20px rgba(0, 0, 0, 0.4);
-  z-index: 1001;
-  animation: slideIn 0.3s ease;
-}
-
-.update-content {
-  display: flex;
-  align-items: center;
-  gap: 1rem;
-  font-size: 0.9rem;
-}
-
-.update-content button {
-  padding: 0.4rem 1rem;
-  border-radius: 4px;
-  border: none;
-  cursor: pointer;
-  font-size: 0.85rem;
-  transition: all 0.2s;
-}
-
-#update-app-btn {
-  background: var(--color-brand-primary);
-  color: white;
-}
-
-#update-app-btn:hover {
-  background: var(--color-text-link-hover);
-}
-
-#dismiss-update-btn {
-  background: transparent;
-  color: var(--color-text-secondary);
-  border: 1px solid var(--color-border-primary);
-}
-
-#dismiss-update-btn:hover {
-  background: var(--color-bg-tertiary);
-}
-
-@keyframes slideIn {
-  from {
-    opacity: 0;
-    transform: translateY(20px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
+/* Mobile breakpoint */
 @media (max-width: 600px) {
-  .footer-grid {
-    grid-template-columns: 1fr;
-  }
-  
   .theme-toggle {
     bottom: 1rem;
     right: 1rem;
   }
   
   .theme-toggle button {
-    width: 44px;
-    height: 44px;
-    font-size: 1.25rem;
-  }
-  
-  .update-notification {
-    left: 1rem;
-    right: 1rem;
-    bottom: 5rem;
+    width: 40px;
+    height: 40px;
+    font-size: 1rem;
   }
 }
 </style>
diff --git a/website/_includes/head_custom.html b/website/_includes/head_custom.html
index 6e89269..2bcad25 100644
--- a/website/_includes/head_custom.html
+++ b/website/_includes/head_custom.html
@@ -1,67 +1,66 @@
-<!-- ═══════════════════════════════════════════════════════════════
-     Tiny-LLM Custom Head - Advanced Features
-     Features: PWA, Theme Toggle, Custom Fonts, Analytics
-     ═══════════════════════════════════════════════════════════════ -->
+<!-- Tiny-LLM Custom Head -->
 
-<!-- Open Graph / Facebook -->
+<!-- Open Graph / Social Meta -->
 <meta property="og:type" content="website">
-<meta property="og:url" content="{{ site.url }}{{ site.baseurl }}/">
+<meta property="og:url" content="{{ site.url }}{{ site.baseurl }}{{ page.url }}">
 <meta property="og:title" content="{{ page.title | default: site.title | escape }}">
 <meta property="og:description" content="{{ page.description | default: site.description | escape }}">
-<meta property="og:image" content="{{ site.url }}{{ site.baseurl }}/assets/images/og-image.png">
+<meta property="og:image" content="{{ site.url }}{{ site.baseurl }}/assets/images/logo.svg">
 
-<!-- Twitter -->
-<meta property="twitter:card" content="summary_large_image">
-<meta property="twitter:url" content="{{ site.url }}{{ site.baseurl }}/">
-<meta property="twitter:title" content="{{ page.title | default: site.title | escape }}">
-<meta property="twitter:description" content="{{ page.description | default: site.description | escape }}">
-<meta property="twitter:image" content="{{ site.url }}{{ site.baseurl }}/assets/images/twitter-card.png">
+<!-- Twitter Card -->
+<meta name="twitter:card" content="summary">
+<meta name="twitter:title" content="{{ page.title | default: site.title | escape }}">
+<meta name="twitter:description" content="{{ page.description | default: site.description | escape }}">
+<meta name="twitter:image" content="{{ site.url }}{{ site.baseurl }}/assets/images/logo.svg">
 
-<!-- Apple Touch Icons -->
+<!-- PWA -->
 <meta name="apple-mobile-web-app-capable" content="yes">
 <meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
 <meta name="apple-mobile-web-app-title" content="Tiny-LLM">
-
-<!-- Microsoft Tiles -->
 <meta name="msapplication-TileColor" content="#0d1117">
 
-<!-- Preconnect for Performance -->
+<!-- Fonts - Use system fonts with Inter as fallback -->
 <link rel="preconnect" href="https://fonts.googleapis.com">
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">
 
-<!-- Theme Toggle Script (Inline for Performance) -->
+<!-- Theme Toggle Support (compatible with Just the Docs) -->
 <script>
-  (function() {
-    const savedTheme = localStorage.getItem('theme');
-    const systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-    const initialTheme = savedTheme || (systemDark ? 'dark' : 'light');
-    document.documentElement.setAttribute('data-theme', initialTheme);
-  })();
+(function() {
+  // Migrate old theme storage format if needed
+  var oldTheme = localStorage.getItem('theme');
+  if (oldTheme && !localStorage.getItem('themeFormat')) {
+    // Already in correct format, just mark as migrated
+    localStorage.setItem('themeFormat', 'v2');
+  }
+  
+  // Check for saved theme preference or prefer-color-scheme
+  var savedTheme = localStorage.getItem('theme');
+  var systemDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+  
+  // Clear any existing theme classes first
+  document.documentElement.classList.remove('dark-theme', 'light-theme');
+  
+  if (savedTheme === 'light' || savedTheme === 'dark') {
+    // Use saved preference
+    document.documentElement.classList.add(savedTheme + '-theme');
+  } else if (systemDark) {
+    document.documentElement.classList.add('dark-theme');
+  } else {
+    document.documentElement.classList.add('light-theme');
+  }
+  
+  // Store the effective theme
+  var effectiveTheme = document.documentElement.classList.contains('light-theme') ? 'light' : 'dark';
+  localStorage.setItem('theme', effectiveTheme);
+})();
 </script>
 
-<!-- Structured Data: SoftwareApplication -->
-<script type="application/ld+json">
-{
-  "@context": "https://schema.org",
-  "@type": "SoftwareApplication",
-  "name": "Tiny-LLM",
-  "description": "High-Performance CUDA Inference Engine for LLMs with W8A16 Quantization",
-  "applicationCategory": "DeveloperApplication",
-  "operatingSystem": "Linux",
-  "programmingLanguage": ["C++", "CUDA"],
-  "softwareVersion": "{{ site.version }}",
-  "license": "https://github.com/LessUp/tiny-llm/blob/master/LICENSE",
-  "codeRepository": "https://github.com/LessUp/tiny-llm",
-  "downloadUrl": "https://github.com/LessUp/tiny-llm/releases",
-  "author": {
-    "@type": "Organization",
-    "name": "LessUp"
-  },
-  "offers": {
-    "@type": "Offer",
-    "price": "0",
-    "priceCurrency": "USD"
-  }
+<!-- Service Worker Registration -->
+<script>
+if ('serviceWorker' in navigator) {
+  window.addEventListener('load', function() {
+    navigator.serviceWorker.register('{{ site.baseurl }}/sw.js');
+  });
 }
 </script>
diff --git a/website/_sass/custom.scss b/website/_sass/custom.scss
deleted file mode 100644
index 1312b13..0000000
--- a/website/_sass/custom.scss
+++ /dev/null
@@ -1,649 +0,0 @@
-// ═══════════════════════════════════════════════════════════════
-// Tiny-LLM Custom SCSS - Modern Design System
-// Based on Just the Docs theme with enhanced styling
-// ═══════════════════════════════════════════════════════════════
-
-// ─── Design Tokens ───────────────────────────────────────────
-// Colors
-$color-brand-primary: #58a6ff;
-$color-brand-secondary: #7ee787;
-$color-brand-accent: #f78166;
-
-// Dark mode colors
-$color-dark-bg: #0d1117;
-$color-dark-surface: #161b22;
-$color-dark-border: #30363d;
-$color-dark-text: #c9d1d9;
-$color-dark-text-secondary: #8b949e;
-$color-dark-code-bg: #1a1f26;
-
-// Light mode colors
-$color-light-bg: #ffffff;
-$color-light-surface: #f6f8fa;
-$color-light-border: #d0d7de;
-$color-light-text: #1f2328;
-$color-light-text-secondary: #656d76;
-$color-light-code-bg: #f6f8fa;
-
-// Typography
-$font-family-base: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
-$font-family-mono: 'JetBrains Mono', 'SF Mono', 'Cascadia Code', Consolas, monospace;
-
-// Spacing
-$spacing-xs: 0.25rem;
-$spacing-sm: 0.5rem;
-$spacing-md: 1rem;
-$spacing-lg: 1.5rem;
-$spacing-xl: 2rem;
-$spacing-2xl: 3rem;
-$spacing-3xl: 4rem;
-
-// Border radius
-$radius-sm: 0.375rem;
-$radius-md: 0.5rem;
-$radius-lg: 0.75rem;
-$radius-xl: 1rem;
-$radius-full: 9999px;
-
-// Transitions
-$transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
-$transition-base: 200ms cubic-bezier(0.4, 0, 0.2, 1);
-$transition-slow: 300ms cubic-bezier(0.4, 0, 0.2, 1);
-
-// Shadows
-$shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
-$shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
-$shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
-$shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04);
-$shadow-glow: 0 0 20px rgba(88, 166, 255, 0.3);
-
-// ─── Dark Mode (Default) ─────────────────────────────────────
-:root,
-[data-theme="dark"] {
-  --color-bg-primary: #{$color-dark-bg};
-  --color-bg-secondary: #{$color-dark-surface};
-  --color-bg-tertiary: #1c2128;
-  --color-border-primary: #{$color-dark-border};
-  --color-border-secondary: #21262d;
-  --color-text-primary: #{$color-dark-text};
-  --color-text-secondary: #{$color-dark-text-secondary};
-  --color-text-tertiary: #484f58;
-  --color-text-link: #{$color-brand-primary};
-  --color-text-link-hover: #{$color-brand-secondary};
-  --color-brand-primary: #{$color-brand-primary};
-  --color-brand-secondary: #{$color-brand-secondary};
-  --color-brand-accent: #{$color-brand-accent};
-  --color-code-bg: #{$color-dark-code-bg};
-  --color-code-border: #{$color-dark-border};
-
-  --font-family-base: #{$font-family-base};
-  --font-family-mono: #{$font-family-mono};
-
-  --radius-sm: #{$radius-sm};
-  --radius-md: #{$radius-md};
-  --radius-lg: #{$radius-lg};
-  --radius-xl: #{$radius-xl};
-  --radius-full: #{$radius-full};
-
-  --shadow-sm: #{$shadow-sm};
-  --shadow-md: #{$shadow-md};
-  --shadow-lg: #{$shadow-lg};
-  --shadow-xl: #{$shadow-xl};
-  --shadow-glow: #{$shadow-glow};
-
-  --transition-fast: #{$transition-fast};
-  --transition-base: #{$transition-base};
-  --transition-slow: #{$transition-slow};
-
-  --font-size-xs: 0.75rem;
-  --font-size-sm: 0.875rem;
-  --font-size-base: 1rem;
-  --font-size-lg: 1.125rem;
-  --font-size-xl: 1.25rem;
-  --font-size-2xl: 1.5rem;
-  --font-size-3xl: 1.875rem;
-  --font-size-4xl: 2.25rem;
-}
-
-// ─── Light Mode ──────────────────────────────────────────────
-[data-theme="light"] {
-  --color-bg-primary: #{$color-light-bg};
-  --color-bg-secondary: #{$color-light-surface};
-  --color-bg-tertiary: #eaeef2;
-  --color-border-primary: #{$color-light-border};
-  --color-border-secondary: #d8dee4;
-  --color-text-primary: #{$color-light-text};
-  --color-text-secondary: #{$color-light-text-secondary};
-  --color-text-tertiary: #8b949e;
-  --color-text-link: #0969da;
-  --color-text-link-hover: #0550ae;
-  --color-code-bg: #{$color-light-code-bg};
-  --color-code-border: #{$color-light-border};
-}
-
-// ─── Base Styles ─────────────────────────────────────────────
-* {
-  box-sizing: border-box;
-}
-
-html {
-  scroll-behavior: smooth;
-  font-size: 16px;
-}
-
-body {
-  font-family: var(--font-family-base);
-  background: var(--color-bg-primary);
-  color: var(--color-text-primary);
-  line-height: 1.6;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-}
-
-// ─── Typography ──────────────────────────────────────────────
-h1, h2, h3, h4, h5, h6 {
-  font-weight: 700;
-  line-height: 1.25;
-  margin-top: $spacing-2xl;
-  margin-bottom: $spacing-md;
-}
-
-h1 {
-  font-size: var(--font-size-4xl);
-  letter-spacing: -0.02em;
-}
-
-h2 {
-  font-size: var(--font-size-3xl);
-  letter-spacing: -0.01em;
-}
-
-h3 {
-  font-size: var(--font-size-2xl);
-}
-
-h4 {
-  font-size: var(--font-size-xl);
-}
-
-p {
-  margin-bottom: $spacing-md;
-  color: var(--color-text-secondary);
-}
-
-a {
-  color: var(--color-text-link);
-  text-decoration: none;
-  transition: color var(--transition-fast);
-
-  &:hover {
-    color: var(--color-text-link-hover);
-    text-decoration: underline;
-  }
-}
-
-code {
-  font-family: var(--font-family-mono);
-  font-size: 0.9em;
-  padding: 0.2em 0.4em;
-  background: var(--color-code-bg);
-  border: 1px solid var(--color-code-border);
-  border-radius: var(--radius-sm);
-}
-
-pre {
-  padding: $spacing-lg;
-  background: var(--color-code-bg);
-  border: 1px solid var(--color-code-border);
-  border-radius: var(--radius-lg);
-  overflow-x: auto;
-  line-height: 1.6;
-
-  code {
-    padding: 0;
-    background: transparent;
-    border: none;
-  }
-}
-
-// ─── Layout ──────────────────────────────────────────────────
-.page-wrap {
-  display: flex;
-  min-height: 100vh;
-}
-
-// ─── Sidebar ─────────────────────────────────────────────────
-.side-bar {
-  width: 260px;
-  background: var(--color-bg-secondary);
-  border-right: 1px solid var(--color-border-primary);
-  padding: $spacing-lg;
-  position: sticky;
-  top: 0;
-  height: 100vh;
-  overflow-y: auto;
-}
-
-.site-header {
-  margin-bottom: $spacing-xl;
-}
-
-.site-logo {
-  display: flex;
-  align-items: center;
-  gap: $spacing-sm;
-  text-decoration: none !important;
-
-  &:hover {
-    text-decoration: none;
-  }
-}
-
-.site-logo-img {
-  width: 32px;
-  height: 32px;
-  border-radius: var(--radius-md);
-}
-
-.site-title-text {
-  font-weight: 700;
-  font-size: var(--font-size-lg);
-  color: var(--color-text-primary);
-}
-
-.menu-toggle {
-  display: none;
-  flex-direction: column;
-  gap: 4px;
-  background: transparent;
-  border: none;
-  cursor: pointer;
-  padding: $spacing-sm;
-
-  span {
-    display: block;
-    width: 20px;
-    height: 2px;
-    background: var(--color-text-primary);
-    transition: all var(--transition-fast);
-  }
-}
-
-.site-nav {
-  margin-bottom: $spacing-xl;
-
-  ul {
-    list-style: none;
-    padding: 0;
-    margin: 0;
-
-    li {
-      margin: $spacing-xs 0;
-
-      a {
-        display: block;
-        padding: $spacing-sm $spacing-md;
-        color: var(--color-text-secondary);
-        border-radius: var(--radius-md);
-        transition: all var(--transition-fast);
-
-        &:hover {
-          background: var(--color-bg-tertiary);
-          color: var(--color-text-primary);
-          text-decoration: none;
-        }
-
-        &.active {
-          background: var(--color-brand-primary);
-          color: white;
-          font-weight: 500;
-        }
-      }
-    }
-  }
-}
-
-.site-footer {
-  padding-top: $spacing-md;
-  border-top: 1px solid var(--color-border-primary);
-
-  .footer-text {
-    font-size: var(--font-size-sm);
-    color: var(--color-text-tertiary);
-    margin: 0;
-  }
-}
-
-// ─── Main Content ────────────────────────────────────────────
-.main-content {
-  flex: 1;
-  display: flex;
-  flex-direction: column;
-}
-
-.main-header {
-  background: var(--color-bg-secondary);
-  border-bottom: 1px solid var(--color-border-primary);
-  padding: $spacing-md $spacing-xl;
-  position: sticky;
-  top: 0;
-  z-index: 100;
-}
-
-.main-header-content {
-  display: flex;
-  align-items: center;
-  gap: $spacing-md;
-}
-
-.nav-toggle {
-  display: none;
-  flex-direction: column;
-  gap: 4px;
-  background: transparent;
-  border: none;
-  cursor: pointer;
-  padding: $spacing-sm;
-
-  span {
-    display: block;
-    width: 20px;
-    height: 2px;
-    background: var(--color-text-primary);
-  }
-}
-
-.search {
-  flex: 1;
-  max-width: 400px;
-}
-
-.search-input-wrap {
-  position: relative;
-}
-
-.search-input {
-  width: 100%;
-  padding: $spacing-sm $spacing-md;
-  background: var(--color-bg-tertiary);
-  border: 1px solid var(--color-border-primary);
-  border-radius: var(--radius-md);
-  color: var(--color-text-primary);
-  font-size: var(--font-size-sm);
-  transition: all var(--transition-fast);
-
-  &:focus {
-    outline: none;
-    border-color: var(--color-brand-primary);
-    box-shadow: 0 0 0 3px rgba(88, 166, 255, 0.15);
-  }
-
-  &::placeholder {
-    color: var(--color-text-tertiary);
-  }
-}
-
-.header-actions {
-  display: flex;
-  gap: $spacing-sm;
-}
-
-.btn {
-  display: inline-flex;
-  align-items: center;
-  gap: $spacing-sm;
-  padding: $spacing-sm $spacing-md;
-  font-weight: 500;
-  border-radius: var(--radius-md);
-  transition: all var(--transition-fast);
-  cursor: pointer;
-  border: 1px solid transparent;
-
-  &.btn-sm {
-    padding: $spacing-xs $spacing-sm;
-    font-size: var(--font-size-sm);
-  }
-
-  &.btn-primary {
-    background: var(--color-brand-primary);
-    color: white !important;
-    border-color: var(--color-brand-primary);
-
-    &:hover {
-      background: var(--color-brand-secondary);
-      border-color: var(--color-brand-secondary);
-      text-decoration: none;
-    }
-  }
-
-  &.btn-secondary {
-    background: var(--color-bg-tertiary);
-    color: var(--color-text-primary) !important;
-    border-color: var(--color-border-primary);
-
-    &:hover {
-      background: var(--color-bg-secondary);
-      text-decoration: none;
-    }
-  }
-
-  &.btn-outline {
-    background: transparent;
-    color: var(--color-text-secondary) !important;
-    border-color: var(--color-border-primary);
-
-    &:hover {
-      border-color: var(--color-brand-primary);
-      color: var(--color-text-link) !important;
-      text-decoration: none;
-    }
-  }
-}
-
-.main-content-wrap {
-  flex: 1;
-  padding: $spacing-2xl $spacing-3xl;
-  max-width: 900px;
-}
-
-.main-footer {
-  background: var(--color-bg-secondary);
-  border-top: 1px solid var(--color-border-primary);
-  padding: $spacing-xl $spacing-2xl;
-
-  .main-footer-content {
-    max-width: 900px;
-    margin: 0 auto;
-
-    p {
-      font-size: var(--font-size-sm);
-      color: var(--color-text-tertiary);
-      margin: 0;
-    }
-  }
-}
-
-// ─── Back to Top Button ──────────────────────────────────────
-.back-to-top {
-  position: fixed;
-  bottom: $spacing-xl;
-  right: $spacing-xl;
-  width: 44px;
-  height: 44px;
-  background: var(--color-brand-primary);
-  color: white;
-  border: none;
-  border-radius: var(--radius-full);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  cursor: pointer;
-  opacity: 0;
-  visibility: hidden;
-  transition: all var(--transition-base);
-  box-shadow: var(--shadow-lg);
-
-  &:hover {
-    background: var(--color-brand-secondary);
-    transform: translateY(-2px);
-    box-shadow: var(--shadow-glow);
-  }
-
-  &.visible {
-    opacity: 1;
-    visibility: visible;
-  }
-}
-
-// ─── Callouts / Alerts ───────────────────────────────────────
-.callout {
-  padding: $spacing-md $spacing-lg;
-  border-left: 4px solid var(--color-border-primary);
-  border-radius: var(--radius-md);
-  margin: $spacing-lg 0;
-
-  &.callout-note {
-    border-color: #a371f7;
-    background: rgba(163, 113, 247, 0.1);
-  }
-
-  &.callout-important {
-    border-color: #58a6ff;
-    background: rgba(88, 166, 255, 0.1);
-  }
-
-  &.callout-warning {
-    border-color: #f78166;
-    background: rgba(247, 129, 102, 0.1);
-  }
-
-  &.callout-tip {
-    border-color: #7ee787;
-    background: rgba(126, 231, 135, 0.1);
-  }
-
-  p:last-child {
-    margin-bottom: 0;
-  }
-}
-
-// ─── Tables ──────────────────────────────────────────────────
-table {
-  width: 100%;
-  border-collapse: collapse;
-  margin: $spacing-lg 0;
-  font-size: var(--font-size-sm);
-
-  th, td {
-    padding: $spacing-sm $spacing-md;
-    border: 1px solid var(--color-border-primary);
-  }
-
-  th {
-    background: var(--color-bg-secondary);
-    font-weight: 600;
-    text-align: left;
-  }
-
-  tr:nth-child(even) {
-    background: var(--color-bg-secondary);
-  }
-}
-
-// ─── Lists ───────────────────────────────────────────────────
-ul, ol {
-  padding-left: $spacing-xl;
-  margin: $spacing-md 0;
-
-  li {
-    margin: $spacing-xs 0;
-  }
-}
-
-// ─── Code Blocks with Line Numbers ──────────────────────────
-.highlight {
-  position: relative;
-
-  .lineno {
-    color: var(--color-text-tertiary);
-    user-select: none;
-    padding-right: $spacing-md;
-    border-right: 1px solid var(--color-border-primary);
-  }
-}
-
-// ─── Responsive Design ──────────────────────────────────────
-@media (max-width: 1024px) {
-  .main-content-wrap {
-    padding: $spacing-xl $spacing-2xl;
-  }
-}
-
-@media (max-width: 768px) {
-  .side-bar {
-    position: fixed;
-    left: -100%;
-    top: 0;
-    z-index: 200;
-    transition: left var(--transition-base);
-    box-shadow: var(--shadow-xl);
-
-    &.open {
-      left: 0;
-    }
-  }
-
-  .menu-toggle {
-    display: flex;
-  }
-
-  .nav-toggle {
-    display: flex;
-  }
-
-  .main-content-wrap {
-    padding: $spacing-lg;
-  }
-
-  h1 {
-    font-size: var(--font-size-3xl);
-  }
-
-  h2 {
-    font-size: var(--font-size-2xl);
-  }
-
-  .search {
-    max-width: 200px;
-  }
-}
-
-@media (max-width: 480px) {
-  .header-actions {
-    display: none;
-  }
-
-  .search {
-    display: none;
-  }
-}
-
-// ─── Print Styles ────────────────────────────────────────────
-@media print {
-  .side-bar,
-  .main-header,
-  .back-to-top,
-  .search {
-    display: none !important;
-  }
-
-  .main-content-wrap {
-    max-width: 100%;
-    padding: 0;
-  }
-
-  body {
-    background: white;
-    color: black;
-  }
-}
diff --git a/website/assets/css/custom.css b/website/assets/css/custom.css
deleted file mode 100644
index 6ed59db..0000000
--- a/website/assets/css/custom.css
+++ /dev/null
@@ -1,288 +0,0 @@
-/* ═══════════════════════════════════════════════════════════════
-   Tiny-LLM Custom CSS - Modern Design System
-   ═══════════════════════════════════════════════════════════════ */
-
-/* ─── CSS Variables ─────────────────────────────────────────── */
-:root {
-  /* Colors - Dark Mode (Default) */
-  --color-bg-primary: #0d1117;
-  --color-bg-secondary: #161b22;
-  --color-bg-tertiary: #1c2128;
-  --color-border-primary: #30363d;
-  --color-border-secondary: #21262d;
-  --color-text-primary: #c9d1d9;
-  --color-text-secondary: #8b949e;
-  --color-text-tertiary: #484f58;
-  --color-text-link: #58a6ff;
-  --color-text-link-hover: #7ee787;
-  --color-brand-primary: #58a6ff;
-  --color-brand-secondary: #7ee787;
-  --color-brand-accent: #f78166;
-  --color-code-bg: #1a1f26;
-  --color-code-border: #30363d;
-
-  /* Typography */
-  --font-family-base: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
-  --font-family-mono: 'JetBrains Mono', 'SF Mono', 'Cascadia Code', Consolas, monospace;
-
-  /* Spacing */
-  --spacing-xs: 0.25rem;
-  --spacing-sm: 0.5rem;
-  --spacing-md: 1rem;
-  --spacing-lg: 1.5rem;
-  --spacing-xl: 2rem;
-  --spacing-2xl: 3rem;
-  --spacing-3xl: 4rem;
-
-  /* Border Radius */
-  --radius-sm: 0.375rem;
-  --radius-md: 0.5rem;
-  --radius-lg: 0.75rem;
-  --radius-xl: 1rem;
-  --radius-full: 9999px;
-
-  /* Shadows */
-  --shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);
-  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
-  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
-  --shadow-xl: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
-  --shadow-glow: 0 0 20px rgba(88, 166, 255, 0.3);
-
-  /* Transitions */
-  --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
-  --transition-base: 200ms cubic-bezier(0.4, 0, 0.2, 1);
-  --transition-slow: 300ms cubic-bezier(0.4, 0, 0.2, 1);
-
-  /* Font Sizes */
-  --font-size-xs: 0.75rem;
-  --font-size-sm: 0.875rem;
-  --font-size-base: 1rem;
-  --font-size-lg: 1.125rem;
-  --font-size-xl: 1.25rem;
-  --font-size-2xl: 1.5rem;
-  --font-size-3xl: 1.875rem;
-  --font-size-4xl: 2.25rem;
-}
-
-/* Light Mode */
-[data-theme="light"] {
-  --color-bg-primary: #ffffff;
-  --color-bg-secondary: #f6f8fa;
-  --color-bg-tertiary: #eaeef2;
-  --color-border-primary: #d0d7de;
-  --color-border-secondary: #d8dee4;
-  --color-text-primary: #1f2328;
-  --color-text-secondary: #656d76;
-  --color-text-tertiary: #8b949e;
-  --color-text-link: #0969da;
-  --color-text-link-hover: #0550ae;
-  --color-code-bg: #f6f8fa;
-  --color-code-border: #d0d7de;
-}
-
-/* ─── Base Styles ───────────────────────────────────────────── */
-* {
-  box-sizing: border-box;
-}
-
-html {
-  scroll-behavior: smooth;
-}
-
-body {
-  font-family: var(--font-family-base);
-  background: var(--color-bg-primary);
-  color: var(--color-text-primary);
-  line-height: 1.6;
-  -webkit-font-smoothing: antialiased;
-}
-
-/* ─── Typography ────────────────────────────────────────────── */
-h1, h2, h3, h4, h5, h6 {
-  font-weight: 700;
-  line-height: 1.25;
-  margin-top: var(--spacing-2xl);
-  margin-bottom: var(--spacing-md);
-}
-
-h1 { font-size: var(--font-size-4xl); letter-spacing: -0.02em; }
-h2 { font-size: var(--font-size-3xl); letter-spacing: -0.01em; }
-h3 { font-size: var(--font-size-2xl); }
-h4 { font-size: var(--font-size-xl); }
-
-p {
-  margin-bottom: var(--spacing-md);
-  color: var(--color-text-secondary);
-}
-
-a {
-  color: var(--color-text-link);
-  text-decoration: none;
-  transition: color var(--transition-fast);
-}
-
-a:hover {
-  color: var(--color-text-link-hover);
-  text-decoration: underline;
-}
-
-code {
-  font-family: var(--font-family-mono);
-  font-size: 0.9em;
-  padding: 0.2em 0.4em;
-  background: var(--color-code-bg);
-  border: 1px solid var(--color-code-border);
-  border-radius: var(--radius-sm);
-}
-
-pre {
-  padding: var(--spacing-lg);
-  background: var(--color-code-bg);
-  border: 1px solid var(--color-code-border);
-  border-radius: var(--radius-lg);
-  overflow-x: auto;
-}
-
-pre code {
-  padding: 0;
-  background: transparent;
-  border: none;
-}
-
-/* ─── Buttons ───────────────────────────────────────────────── */
-.btn {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--spacing-sm);
-  padding: var(--spacing-sm) var(--spacing-md);
-  font-weight: 500;
-  border-radius: var(--radius-md);
-  transition: all var(--transition-fast);
-  cursor: pointer;
-  border: 1px solid transparent;
-}
-
-.btn-primary {
-  background: var(--color-brand-primary);
-  color: white !important;
-  border-color: var(--color-brand-primary);
-}
-
-.btn-primary:hover {
-  background: var(--color-brand-secondary);
-  border-color: var(--color-brand-secondary);
-  text-decoration: none;
-}
-
-.btn-secondary {
-  background: var(--color-bg-tertiary);
-  color: var(--color-text-primary) !important;
-  border-color: var(--color-border-primary);
-}
-
-.btn-secondary:hover {
-  background: var(--color-bg-secondary);
-  text-decoration: none;
-}
-
-.btn-outline {
-  background: transparent;
-  color: var(--color-text-secondary) !important;
-  border-color: var(--color-border-primary);
-}
-
-.btn-outline:hover {
-  border-color: var(--color-brand-primary);
-  color: var(--color-text-link) !important;
-  text-decoration: none;
-}
-
-/* ─── Tables ────────────────────────────────────────────────── */
-table {
-  width: 100%;
-  border-collapse: collapse;
-  margin: var(--spacing-lg) 0;
-  font-size: var(--font-size-sm);
-}
-
-table th, table td {
-  padding: var(--spacing-sm) var(--spacing-md);
-  border: 1px solid var(--color-border-primary);
-}
-
-table th {
-  background: var(--color-bg-secondary);
-  font-weight: 600;
-  text-align: left;
-}
-
-table tr:nth-child(even) {
-  background: var(--color-bg-secondary);
-}
-
-/* ─── Callouts ──────────────────────────────────────────────── */
-.callout {
-  padding: var(--spacing-md) var(--spacing-lg);
-  border-left: 4px solid var(--color-border-primary);
-  border-radius: var(--radius-md);
-  margin: var(--spacing-lg) 0;
-}
-
-.callout-note {
-  border-color: #a371f7;
-  background: rgba(163, 113, 247, 0.1);
-}
-
-.callout-important {
-  border-color: #58a6ff;
-  background: rgba(88, 166, 255, 0.1);
-}
-
-.callout-warning {
-  border-color: #f78166;
-  background: rgba(247, 129, 102, 0.1);
-}
-
-.callout-tip {
-  border-color: #7ee787;
-  background: rgba(126, 231, 135, 0.1);
-}
-
-/* ─── Back to Top Button ────────────────────────────────────── */
-.back-to-top {
-  position: fixed;
-  bottom: var(--spacing-xl);
-  right: var(--spacing-xl);
-  width: 44px;
-  height: 44px;
-  background: var(--color-brand-primary);
-  color: white;
-  border: none;
-  border-radius: var(--radius-full);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  cursor: pointer;
-  opacity: 0;
-  visibility: hidden;
-  transition: all var(--transition-base);
-  box-shadow: var(--shadow-lg);
-  z-index: 100;
-}
-
-.back-to-top:hover {
-  background: var(--color-brand-secondary);
-  transform: translateY(-2px);
-  box-shadow: var(--shadow-glow);
-}
-
-.back-to-top.visible {
-  opacity: 1;
-  visibility: visible;
-}
-
-/* ─── Responsive Design ────────────────────────────────────── */
-@media (max-width: 768px) {
-  h1 { font-size: var(--font-size-3xl); }
-  h2 { font-size: var(--font-size-2xl); }
-}
diff --git a/website/assets/css/custom.scss b/website/assets/css/custom.scss
index 740561f..3b264cd 100644
--- a/website/assets/css/custom.scss
+++ b/website/assets/css/custom.scss
@@ -1,634 +1,305 @@
 ---
 ---
 
-// ═══════════════════════════════════════════════════════════════
-// Tiny-LLM Custom Styles - Modern Dark/Light Theme
-// Features: CSS Variables, Animations, Responsive, Modern UI
-// ═══════════════════════════════════════════════════════════════
+/* Tiny-LLM Theme Customizations
+   Overrides for Just the Docs theme
+*/
 
-// ───────────────────────────────────────────────────────────────
-// CSS CUSTOM PROPERTIES (Variables)
-// ───────────────────────────────────────────────────────────────
+/* ============================================================================
+   COLOR VARIABLES - Support both dark and light modes
+   ============================================================================ */
 
-:root {
-  // Brand Colors
+:root,
+.dark-theme {
+  /* Brand Colors */
   --color-brand-primary: #58a6ff;
   --color-brand-secondary: #7ee787;
-  --color-brand-accent: #f778ba;
   
-  // Typography
-  --font-family-base: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-  --font-family-mono: 'JetBrains Mono', 'SF Mono', Monaco, monospace;
-  
-  // Font Sizes
-  --font-size-xs: 0.75rem;
-  --font-size-sm: 0.875rem;
-  --font-size-base: 1rem;
-  --font-size-lg: 1.125rem;
-  --font-size-xl: 1.25rem;
-  --font-size-2xl: 1.5rem;
-  --font-size-3xl: 2rem;
-  
-  // Line Heights
-  --line-height-tight: 1.25;
-  --line-height-base: 1.6;
-  --line-height-relaxed: 1.75;
-  
-  // Spacing Scale
-  --space-1: 0.25rem;
-  --space-2: 0.5rem;
-  --space-3: 0.75rem;
-  --space-4: 1rem;
-  --space-5: 1.25rem;
-  --space-6: 1.5rem;
-  --space-8: 2rem;
-  --space-10: 2.5rem;
-  --space-12: 3rem;
-  --space-16: 4rem;
-  
-  // Border Radius
-  --radius-sm: 6px;
-  --radius-md: 8px;
-  --radius-lg: 12px;
-  --radius-xl: 16px;
-  --radius-full: 9999px;
-  
-  // Shadows
-  --shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
-  --shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
-  --shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05);
-  --shadow-glow: 0 0 20px rgba(88, 166, 255, 0.3);
-  
-  // Transitions
-  --transition-fast: 150ms ease;
-  --transition-base: 250ms ease;
-  --transition-slow: 350ms ease;
-  
-  // Z-Index Scale
-  --z-dropdown: 100;
-  --z-sticky: 200;
-  --z-modal: 300;
-  --z-tooltip: 400;
-}
-
-// ───────────────────────────────────────────────────────────────
-// DARK THEME (Default)
-// ───────────────────────────────────────────────────────────────
-
-[data-theme="dark"],
-html[data-theme="dark"] {
-  // Background Colors
-  --color-bg-primary: #0d1117;
-  --color-bg-secondary: #161b22;
-  --color-bg-tertiary: #21262d;
-  --color-bg-elevated: #21262d;
-  --color-bg-overlay: rgba(13, 17, 23, 0.8);
-  
-  // Text Colors
-  --color-text-primary: #f0f6fc;
-  --color-text-secondary: #8b949e;
-  --color-text-tertiary: #6e7681;
-  --color-text-link: #58a6ff;
-  --color-text-link-hover: #79c0ff;
-  
-  // Border Colors
-  --color-border-primary: #30363d;
-  --color-border-secondary: #21262d;
-  --color-border-muted: #161b22;
-  
-  // Accent Colors
-  --color-accent-blue: #58a6ff;
-  --color-accent-green: #3fb950;
-  --color-accent-purple: #a371f7;
-  --color-accent-orange: #f0883e;
-  --color-accent-red: #f85149;
-  --color-accent-yellow: #d29922;
-  
-  // Code Colors
-  --color-code-bg: #161b22;
-  --color-code-text: #e6edf3;
-  --color-code-border: #30363d;
-}
-
-// ───────────────────────────────────────────────────────────────
-// LIGHT THEME
-// ───────────────────────────────────────────────────────────────
-
-[data-theme="light"],
-html[data-theme="light"] {
-  // Background Colors
-  --color-bg-primary: #ffffff;
-  --color-bg-secondary: #f6f8fa;
-  --color-bg-tertiary: #eaeef2;
-  --color-bg-elevated: #ffffff;
-  --color-bg-overlay: rgba(255, 255, 255, 0.8);
-  
-  // Text Colors
-  --color-text-primary: #1f2328;
-  --color-text-secondary: #656d76;
-  --color-text-tertiary: #8c959f;
-  --color-text-link: #0969da;
-  --color-text-link-hover: #0550ae;
-  
-  // Border Colors
-  --color-border-primary: #d0d7de;
-  --color-border-secondary: #e6edf3;
-  --color-border-muted: #eaeef2;
-  
-  // Accent Colors
-  --color-accent-blue: #0969da;
-  --color-accent-green: #1a7f37;
-  --color-accent-purple: #8250df;
-  --color-accent-orange: #bc4c00;
-  --color-accent-red: #cf222e;
-  --color-accent-yellow: #9a6700;
-  
-  // Code Colors
-  --color-code-bg: #f6f8fa;
-  --color-code-text: #1f2328;
-  --color-code-border: #d0d7de;
-}
-
-// ───────────────────────────────────────────────────────────────
-// BASE STYLES
-// ───────────────────────────────────────────────────────────────
+  /* Dark theme colors */
+  --text-color: #f0f6fc;
+  --text-secondary-color: #8b949e;
+  --bg-color: #0d1117;
+  --surface-color: #161b22;
+  --surface-secondary-color: #21262d;
+  --border-color: #30363d;
+  --link-color: #58a6ff;
+  --link-hover-color: #79c0ff;
+  --btn-primary-bg: #238636;
+  --btn-primary-hover: #2ea043;
+}
+
+.light-theme {
+  /* Light theme colors */
+  --text-color: #1f2328;
+  --text-secondary-color: #656d76;
+  --bg-color: #ffffff;
+  --surface-color: #f6f8fa;
+  --surface-secondary-color: #eaeef2;
+  --border-color: #d0d7de;
+  --link-color: #0969da;
+  --link-hover-color: #0550ae;
+  --btn-primary-bg: #1a7f37;
+  --btn-primary-hover: #1f8838;
+}
+
+/* ============================================================================
+   BASE OVERRIDES
+   ============================================================================ */
 
-* {
-  box-sizing: border-box;
+body {
+  color: var(--text-color);
+  background-color: var(--bg-color);
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
 }
 
-html {
-  scroll-behavior: smooth;
-  font-size: 16px;
+/* Links */
+a {
+  color: var(--link-color);
 }
 
-body {
-  font-family: var(--font-family-base);
-  font-size: var(--font-size-base);
-  line-height: var(--line-height-base);
-  color: var(--color-text-primary);
-  background-color: var(--color-bg-primary);
-  transition: background-color var(--transition-base), color var(--transition-base);
+a:hover {
+  color: var(--link-hover-color);
 }
 
-// ───────────────────────────────────────────────────────────────
-// TYPOGRAPHY
-// ───────────────────────────────────────────────────────────────
+/* ============================================================================
+   SIDEBAR OVERRIDES
+   ============================================================================ */
 
-h1, h2, h3, h4, h5, h6 {
-  font-weight: 600;
-  line-height: var(--line-height-tight);
-  color: var(--color-text-primary);
-  margin-top: var(--space-8);
-  margin-bottom: var(--space-4);
+.side-bar {
+  background-color: var(--surface-color);
+  border-right: 1px solid var(--border-color);
 }
 
-h1 { font-size: var(--font-size-3xl); }
-h2 { 
-  font-size: var(--font-size-2xl); 
-  padding-bottom: var(--space-2);
-  border-bottom: 1px solid var(--color-border-primary);
+.site-header {
+  border-bottom: 1px solid var(--border-color);
 }
-h3 { font-size: var(--font-size-xl); }
-h4 { font-size: var(--font-size-lg); }
 
-p {
-  margin-bottom: var(--space-4);
-  color: var(--color-text-secondary);
+.site-title {
+  color: var(--text-color) !important;
 }
 
-a {
-  color: var(--color-text-link);
-  text-decoration: none;
-  transition: color var(--transition-fast);
-  
-  &:hover {
-    color: var(--color-text-link-hover);
-    text-decoration: underline;
-  }
+.site-title:hover {
+  background-image: none !important;
 }
 
-// ───────────────────────────────────────────────────────────────
-// CODE & SYNTAX HIGHLIGHTING
-// ───────────────────────────────────────────────────────────────
+/* Navigation */
+.nav-list .nav-list-link {
+  color: var(--text-secondary-color);
+}
 
-code {
-  font-family: var(--font-family-mono);
-  font-size: 0.875em;
-  padding: 0.2em 0.4em;
-  background-color: var(--color-code-bg);
-  border: 1px solid var(--color-code-border);
-  border-radius: var(--radius-sm);
-  color: var(--color-accent-purple);
-}
-
-pre {
-  background-color: var(--color-code-bg) !important;
-  border: 1px solid var(--color-code-border);
-  border-radius: var(--radius-md);
-  padding: var(--space-4);
-  overflow-x: auto;
-  margin-bottom: var(--space-6);
-  
-  code {
-    background: none;
-    border: none;
-    padding: 0;
-    color: var(--color-code-text);
-  }
+.nav-list .nav-list-link:hover {
+  background-color: var(--surface-secondary-color);
+  color: var(--text-color);
 }
 
-.highlight {
-  background-color: var(--color-code-bg) !important;
-  border-radius: var(--radius-md);
-  
-  .lineno {
-    color: var(--color-text-tertiary);
-    padding-right: var(--space-4);
-    margin-right: var(--space-4);
-    border-right: 1px solid var(--color-border-primary);
-  }
+.nav-list .nav-list-link.active {
+  background-color: var(--surface-secondary-color);
+  color: var(--link-color);
 }
 
-// ───────────────────────────────────────────────────────────────
-// SIDEBAR NAVIGATION
-// ───────────────────────────────────────────────────────────────
+.aux-nav .aux-nav-list-item a {
+  color: var(--text-secondary-color);
+}
 
-.side-bar {
-  background-color: var(--color-bg-secondary);
-  border-right: 1px solid var(--color-border-primary);
+/* ============================================================================
+   MAIN CONTENT OVERRIDES
+   ============================================================================ */
+
+.main {
+  background-color: var(--bg-color);
 }
 
-.site-header {
-  border-bottom: 1px solid var(--color-border-primary);
-  
-  .site-title {
-    font-weight: 700;
-    font-size: var(--font-size-lg);
-    color: var(--color-text-primary);
-    
-    &:hover {
-      background: none;
-    }
-  }
+.main-content-wrap {
+  background-color: var(--bg-color);
 }
 
-.nav-list {
-  .nav-list-item {
-    .nav-list-link {
-      color: var(--color-text-secondary);
-      border-radius: var(--radius-md);
-      padding: var(--space-2) var(--space-3);
-      transition: all var(--transition-fast);
-      
-      &:hover,
-      &.active {
-        color: var(--color-text-primary);
-        background-color: var(--color-bg-tertiary);
-      }
-      
-      &.active {
-        font-weight: 600;
-        color: var(--color-brand-primary);
-      }
-    }
-  }
-  
-  .nav-list-item.active {
-    .nav-list-link {
-      color: var(--color-brand-primary);
-    }
-  }
+.main-content h1,
+.main-content h2,
+.main-content h3,
+.main-content h4,
+.main-content h5,
+.main-content h6 {
+  color: var(--text-color);
 }
 
-// ───────────────────────────────────────────────────────────────
-// SEARCH
-// ───────────────────────────────────────────────────────────────
+.main-content p {
+  color: var(--text-secondary-color);
+}
 
-.search-input-wrap {
-  .search-input {
-    background-color: var(--color-bg-tertiary);
-    border: 1px solid var(--color-border-primary);
-    border-radius: var(--radius-md);
-    color: var(--color-text-primary);
-    padding: var(--space-2) var(--space-3);
-    
-    &:focus {
-      outline: none;
-      border-color: var(--color-brand-primary);
-      box-shadow: 0 0 0 3px rgba(88, 166, 255, 0.3);
-    }
-    
-    &::placeholder {
-      color: var(--color-text-tertiary);
-    }
-  }
+/* Breadcrumbs */
+.breadcrumb-nav-list-item {
+  color: var(--text-secondary-color);
 }
 
-.search-results {
-  background-color: var(--color-bg-elevated);
-  border: 1px solid var(--color-border-primary);
-  border-radius: var(--radius-lg);
-  box-shadow: var(--shadow-lg);
+.breadcrumb-nav-list-item a {
+  color: var(--link-color);
 }
 
-// ───────────────────────────────────────────────────────────────
-// MAIN CONTENT
-// ───────────────────────────────────────────────────────────────
+/* ============================================================================
+   SEARCH OVERRIDES
+   ============================================================================ */
 
-.main {
-  background-color: var(--color-bg-primary);
+.search-input-wrap {
+  background-color: var(--surface-secondary-color);
+  border: 1px solid var(--border-color);
+  border-radius: 6px;
 }
 
-.main-content {
-  h1:first-of-type {
-    margin-top: 0;
-    padding-bottom: var(--space-4);
-    border-bottom: 2px solid var(--color-brand-primary);
-  }
+.search-input {
+  background-color: transparent;
+  color: var(--text-color);
 }
 
-// ───────────────────────────────────────────────────────────────
-// TABLES
-// ───────────────────────────────────────────────────────────────
-
-table {
-  width: 100%;
-  border-collapse: collapse;
-  margin-bottom: var(--space-6);
-  font-size: var(--font-size-sm);
-  
-  th {
-    background-color: var(--color-bg-secondary);
-    font-weight: 600;
-    text-align: left;
-    padding: var(--space-3) var(--space-4);
-    border-bottom: 2px solid var(--color-border-primary);
-    color: var(--color-text-primary);
-  }
-  
-  td {
-    padding: var(--space-3) var(--space-4);
-    border-bottom: 1px solid var(--color-border-secondary);
-    color: var(--color-text-secondary);
-  }
-  
-  tr:hover {
-    background-color: var(--color-bg-secondary);
-  }
+.search-input::placeholder {
+  color: var(--text-secondary-color);
 }
 
-// ───────────────────────────────────────────────────────────────
-// CALLOUTS / ALERTS
-// ───────────────────────────────────────────────────────────────
-
-.block-callout {
-  border-radius: var(--radius-md);
-  padding: var(--space-4) var(--space-5);
-  margin-bottom: var(--space-6);
-  border-left: 4px solid;
-  
-  &.callout-note {
-    background-color: rgba(163, 113, 247, 0.1);
-    border-left-color: var(--color-accent-purple);
-  }
-  
-  &.callout-warning {
-    background-color: rgba(210, 153, 34, 0.1);
-    border-left-color: var(--color-accent-yellow);
-  }
-  
-  &.callout-danger {
-    background-color: rgba(248, 81, 73, 0.1);
-    border-left-color: var(--color-accent-red);
-  }
-  
-  &.callout-success {
-    background-color: rgba(63, 185, 80, 0.1);
-    border-left-color: var(--color-accent-green);
-  }
+.search-input:focus {
+  outline: none;
 }
 
-// ───────────────────────────────────────────────────────────────
-// THEME TOGGLE BUTTON
-// ───────────────────────────────────────────────────────────────
+.search-results {
+  background-color: var(--surface-color);
+  border: 1px solid var(--border-color);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2);
+}
 
-.theme-toggle {
-  position: fixed;
-  bottom: var(--space-6);
-  right: var(--space-6);
-  z-index: var(--z-modal);
-  
-  button {
-    width: 48px;
-    height: 48px;
-    border-radius: var(--radius-full);
-    background-color: var(--color-bg-elevated);
-    border: 1px solid var(--color-border-primary);
-    box-shadow: var(--shadow-lg);
-    cursor: pointer;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    transition: all var(--transition-base);
-    
-    &:hover {
-      transform: scale(1.1);
-      box-shadow: var(--shadow-glow);
-    }
-    
-    svg {
-      width: 24px;
-      height: 24px;
-      fill: var(--color-text-secondary);
-    }
-  }
+.search-result-highlight {
+  color: var(--link-color);
 }
 
-// ───────────────────────────────────────────────────────────────
-// LANGUAGE SWITCHER
-// ───────────────────────────────────────────────────────────────
+/* ============================================================================
+   CODE BLOCKS
+   ============================================================================ */
 
-.language-switcher {
-  display: flex;
-  gap: var(--space-2);
-  padding: var(--space-3);
-  margin: var(--space-2) 0;
-  background-color: var(--color-bg-tertiary);
-  border-radius: var(--radius-md);
-  
-  a {
-    padding: var(--space-1) var(--space-3);
-    border-radius: var(--radius-sm);
-    font-size: var(--font-size-sm);
-    font-weight: 500;
-    transition: all var(--transition-fast);
-    
-    &.active {
-      background-color: var(--color-brand-primary);
-      color: white;
-    }
-    
-    &:not(.active):hover {
-      background-color: var(--color-bg-secondary);
-      text-decoration: none;
-    }
-  }
+.highlight {
+  background-color: var(--surface-color) !important;
+  border: 1px solid var(--border-color);
+  border-radius: 8px;
 }
 
-// ───────────────────────────────────────────────────────────────
-// FOOTER
-// ───────────────────────────────────────────────────────────────
-
-.site-footer {
-  background-color: var(--color-bg-secondary);
-  border-top: 1px solid var(--color-border-primary);
-  padding: var(--space-8) var(--space-6);
-  margin-top: var(--space-12);
-  color: var(--color-text-tertiary);
-  font-size: var(--font-size-sm);
+code {
+  background-color: var(--surface-secondary-color);
+  border: 1px solid var(--border-color);
+  color: var(--text-color);
+  padding: 0.2em 0.4em;
+  border-radius: 4px;
+  font-size: 0.9em;
 }
 
-// ───────────────────────────────────────────────────────────────
-// ANIMATIONS
-// ───────────────────────────────────────────────────────────────
+pre.highlight {
+  padding: 1rem;
+}
 
-@keyframes fadeIn {
-  from { opacity: 0; transform: translateY(10px); }
-  to { opacity: 1; transform: translateY(0); }
+pre.highlight code {
+  background: transparent;
+  border: none;
+  padding: 0;
 }
 
-@keyframes slideIn {
-  from { transform: translateX(-20px); opacity: 0; }
-  to { transform: translateX(0); opacity: 1; }
+/* ============================================================================
+   TABLES
+   ============================================================================ */
+
+table {
+  border-collapse: collapse;
+  color: var(--text-color);
 }
 
-@keyframes pulse {
-  0%, 100% { opacity: 1; }
-  50% { opacity: 0.5; }
+table th {
+  background-color: var(--surface-color);
+  border-bottom: 2px solid var(--border-color);
+  color: var(--text-color);
+  font-weight: 600;
+  padding: 0.75rem 1rem;
+  text-align: left;
 }
 
-.animate-fade-in {
-  animation: fadeIn 0.5s ease-out;
+table td {
+  border-bottom: 1px solid var(--border-color);
+  padding: 0.75rem 1rem;
 }
 
-.animate-slide-in {
-  animation: slideIn 0.3s ease-out;
+table tr:nth-child(even) {
+  background-color: var(--surface-color);
 }
 
-// ───────────────────────────────────────────────────────────────
-// RESPONSIVE DESIGN
-// ───────────────────────────────────────────────────────────────
+/* ============================================================================
+   FOOTER
+   ============================================================================ */
 
-@media (max-width: 800px) {
-  .main-content {
-    padding: var(--space-4);
-  }
-  
-  h1 { font-size: var(--font-size-2xl); }
-  h2 { font-size: var(--font-size-xl); }
-  h3 { font-size: var(--font-size-lg); }
-  
-  .theme-toggle {
-    bottom: var(--space-4);
-    right: var(--space-4);
-    
-    button {
-      width: 40px;
-      height: 40px;
-    }
-  }
+.site-footer {
+  color: var(--text-secondary-color);
+  border-top: 1px solid var(--border-color);
 }
 
-// ───────────────────────────────────────────────────────────────
-// SCROLLBAR STYLING
-// ───────────────────────────────────────────────────────────────
+/* ============================================================================
+   CALLOUTS (Note, Warning, etc.)
+   ============================================================================ */
 
-::-webkit-scrollbar {
-  width: 10px;
-  height: 10px;
+.block-callout {
+  border-radius: 8px;
 }
 
-::-webkit-scrollbar-track {
-  background: var(--color-bg-secondary);
+.block-callout.callout-note {
+  background-color: rgba(88, 166, 255, 0.1);
+  border-left: 4px solid #58a6ff;
 }
 
-::-webkit-scrollbar-thumb {
-  background: var(--color-border-primary);
-  border-radius: var(--radius-full);
-  border: 2px solid var(--color-bg-secondary);
-  
-  &:hover {
-    background: var(--color-text-tertiary);
-  }
+.block-callout.callout-warning {
+  background-color: rgba(210, 153, 34, 0.1);
+  border-left: 4px solid #d29922;
 }
 
-// ───────────────────────────────────────────────────────────────
-// SELECTION STYLING
-// ───────────────────────────────────────────────────────────────
+/* ============================================================================
+   SELECTION
+   ============================================================================ */
 
 ::selection {
   background-color: rgba(88, 166, 255, 0.3);
-  color: var(--color-text-primary);
+  color: var(--text-color);
 }
 
-// ───────────────────────────────────────────────────────────────
-// MERMAID DIAGRAMS
-// ───────────────────────────────────────────────────────────────
+/* ============================================================================
+   BUTTONS FOR DOCS PAGES
+   ============================================================================ */
 
-.mermaid {
-  background: transparent !important;
-  margin: var(--space-6) 0;
-  text-align: center;
+.btn-home {
+  display: inline-block;
+  padding: 0.75rem 1.5rem;
+  background: var(--btn-primary-bg);
+  color: white !important;
+  text-decoration: none !important;
+  border-radius: 8px;
+  font-weight: 600;
+  transition: all 0.2s ease;
+  margin: 0.5rem 0;
 }
 
-// ───────────────────────────────────────────────────────────────
-// ANCHOR LINKS
-// ───────────────────────────────────────────────────────────────
-
-.anchor-heading {
-  position: relative;
-  
-  .anchor-link {
-    position: absolute;
-    left: -1.5em;
-    opacity: 0;
-    transition: opacity var(--transition-fast);
-    text-decoration: none;
-    color: var(--color-text-tertiary);
-  }
-  
-  &:hover .anchor-link {
-    opacity: 1;
-  }
+.btn-home:hover {
+  background: var(--btn-primary-hover);
+  transform: translateY(-1px);
+  box-shadow: 0 4px 12px rgba(35, 134, 54, 0.3);
+  text-decoration: none !important;
 }
 
-// ───────────────────────────────────────────────────────────────
-// BADGES
-// ───────────────────────────────────────────────────────────────
+/* ============================================================================
+   PRINT STYLES
+   ============================================================================ */
 
-.badge {
-  display: inline-flex;
-  align-items: center;
-  padding: var(--space-1) var(--space-2);
-  border-radius: var(--radius-full);
-  font-size: var(--font-size-xs);
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 0.025em;
-  
-  &.badge-stable {
-    background-color: rgba(63, 185, 80, 0.2);
-    color: var(--color-accent-green);
+@media print {
+  .side-bar,
+  .site-header,
+  .site-footer,
+  .theme-toggle {
+    display: none !important;
   }
   
-  &.badge-beta {
-    background-color: rgba(210, 153, 34, 0.2);
-    color: var(--color-accent-yellow);
+  .main {
+    margin-left: 0 !important;
   }
   
-  &.badge-planned {
-    background-color: rgba(139, 148, 158, 0.2);
-    color: var(--color-text-secondary);
+  .main-content-wrap {
+    max-width: 100% !important;
   }
 }
diff --git a/website/assets/css/home.scss b/website/assets/css/home.scss
new file mode 100644
index 0000000..eb48e67
--- /dev/null
+++ b/website/assets/css/home.scss
@@ -0,0 +1,588 @@
+---
+---
+
+/* Tiny-LLM Home Page Styles
+   Modern, clean design for the landing page
+*/
+
+/* ===== HERO SECTION ===== */
+.hero-section {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 3rem;
+  align-items: center;
+  padding: 2rem 0 3rem;
+  margin-bottom: 2rem;
+  border-bottom: 1px solid var(--border-color, #30363d);
+}
+
+.hero-content {
+  max-width: 600px;
+}
+
+.hero-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-bottom: 1.5rem;
+  padding: 0.5rem 1rem;
+  background: rgba(88, 166, 255, 0.1);
+  border: 1px solid rgba(88, 166, 255, 0.3);
+  border-radius: 9999px;
+  font-size: 0.875rem;
+}
+
+.badge-highlight {
+  color: #58a6ff;
+  font-weight: 600;
+}
+
+.changelog-link {
+  color: var(--text-secondary-color, #8b949e);
+  font-size: 0.8rem;
+  text-decoration: none;
+  &:hover {
+    color: #58a6ff;
+    text-decoration: underline;
+  }
+}
+
+.hero-title {
+  font-size: 2.5rem;
+  font-weight: 800;
+  line-height: 1.2;
+  margin: 0 0 1rem 0;
+  color: var(--text-color, #f0f6fc);
+  letter-spacing: -0.02em;
+}
+
+.gradient-text {
+  background: linear-gradient(135deg, #58a6ff 0%, #7ee787 100%);
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+
+.hero-description {
+  font-size: 1.125rem;
+  line-height: 1.7;
+  color: var(--text-secondary-color, #8b949e);
+  margin-bottom: 2rem;
+  
+  strong {
+    color: var(--text-color, #f0f6fc);
+    font-weight: 600;
+  }
+}
+
+.hero-actions {
+  display: flex;
+  gap: 1rem;
+  flex-wrap: wrap;
+  margin-bottom: 2rem;
+}
+
+.btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem 1.5rem;
+  font-size: 1rem;
+  font-weight: 600;
+  text-decoration: none;
+  border-radius: 8px;
+  transition: all 0.2s ease;
+  cursor: pointer;
+  border: 1px solid transparent;
+}
+
+.btn-primary {
+  background: #238636;
+  color: white !important;
+  border-color: #238636;
+  
+  &:hover {
+    background: #2ea043;
+    border-color: #2ea043;
+    text-decoration: none;
+    transform: translateY(-1px);
+    box-shadow: 0 4px 12px rgba(35, 134, 54, 0.3);
+  }
+  
+  svg {
+    width: 18px;
+    height: 18px;
+  }
+}
+
+.btn-secondary {
+  background: var(--surface-color, #21262d);
+  color: var(--text-color, #f0f6fc) !important;
+  border-color: var(--border-color, #30363d);
+  
+  &:hover {
+    background: var(--border-color, #30363d);
+    text-decoration: none;
+  }
+  
+  svg {
+    width: 18px;
+    height: 18px;
+  }
+}
+
+.btn-outline {
+  background: transparent;
+  color: var(--text-secondary-color, #8b949e) !important;
+  border-color: var(--border-color, #30363d);
+  
+  &:hover {
+    border-color: #58a6ff;
+    color: #58a6ff !important;
+    text-decoration: none;
+  }
+}
+
+.hero-stats {
+  display: flex;
+  align-items: center;
+  gap: 1.5rem;
+  flex-wrap: wrap;
+}
+
+.stat {
+  text-align: center;
+}
+
+.stat-value {
+  display: block;
+  font-size: 1.5rem;
+  font-weight: 700;
+  color: #58a6ff;
+}
+
+.stat-label {
+  font-size: 0.75rem;
+  color: var(--text-secondary-color, #8b949e);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.stat-separator {
+  color: var(--border-color, #30363d);
+  font-weight: 300;
+}
+
+/* Code Window */
+.hero-visual {
+  display: flex;
+  justify-content: center;
+}
+
+.code-window {
+  width: 100%;
+  max-width: 480px;
+  background: #0d1117;
+  border: 1px solid #30363d;
+  border-radius: 12px;
+  overflow: hidden;
+  box-shadow: 0 20px 40px rgba(0, 0, 0, 0.4);
+}
+
+.code-header {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 0.75rem 1rem;
+  background: #161b22;
+  border-bottom: 1px solid #30363d;
+}
+
+.code-dots {
+  display: flex;
+  gap: 6px;
+  
+  span {
+    width: 12px;
+    height: 12px;
+    border-radius: 50%;
+    
+    &:nth-child(1) { background: #ff5f56; }
+    &:nth-child(2) { background: #ffbd2e; }
+    &:nth-child(3) { background: #27ca40; }
+  }
+}
+
+.code-filename {
+  font-size: 0.8rem;
+  color: #8b949e;
+  margin-left: auto;
+  font-family: 'SF Mono', Monaco, monospace;
+}
+
+.code-content {
+  padding: 1rem;
+  
+  pre {
+    margin: 0 !important;
+    background: transparent !important;
+    border: none !important;
+    padding: 0 !important;
+  }
+  
+  code {
+    font-size: 0.8rem !important;
+    line-height: 1.6 !important;
+  }
+}
+
+/* ===== FEATURES GRID ===== */
+.features-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 1.5rem;
+  margin: 2rem 0;
+}
+
+.feature-card {
+  padding: 1.5rem;
+  background: var(--surface-color, #161b22);
+  border: 1px solid var(--border-color, #30363d);
+  border-radius: 12px;
+  transition: all 0.2s ease;
+  
+  &:hover {
+    border-color: rgba(88, 166, 255, 0.3);
+    transform: translateY(-2px);
+    box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2);
+  }
+  
+  h3 {
+    margin: 0.75rem 0 0.5rem;
+    font-size: 1.125rem;
+    color: var(--text-color, #f0f6fc);
+  }
+  
+  p {
+    margin: 0;
+    font-size: 0.9rem;
+    color: var(--text-secondary-color, #8b949e);
+    line-height: 1.6;
+  }
+}
+
+.feature-icon {
+  font-size: 1.75rem;
+  line-height: 1;
+}
+
+.badge {
+  display: inline-block;
+  padding: 0.25rem 0.5rem;
+  font-size: 0.65rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  border-radius: 4px;
+  margin-top: 1rem;
+}
+
+.badge-stable {
+  background: rgba(35, 134, 54, 0.2);
+  color: #3fb950;
+}
+
+/* ===== DOCS GRID ===== */
+.docs-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 1rem;
+  margin: 2rem 0;
+}
+
+.doc-card {
+  display: block;
+  padding: 1.5rem;
+  background: var(--surface-color, #161b22);
+  border: 1px solid var(--border-color, #30363d);
+  border-radius: 12px;
+  text-decoration: none !important;
+  transition: all 0.2s ease;
+  text-align: center;
+  
+  &:hover {
+    border-color: #58a6ff;
+    transform: translateY(-3px);
+    box-shadow: 0 12px 24px rgba(0, 0, 0, 0.2);
+    text-decoration: none !important;
+  }
+  
+  .doc-icon {
+    font-size: 2rem;
+    margin-bottom: 0.75rem;
+  }
+  
+  h4 {
+    margin: 0 0 0.25rem;
+    font-size: 1rem;
+    color: var(--text-color, #f0f6fc);
+  }
+  
+  p {
+    margin: 0;
+    font-size: 0.8rem;
+    color: var(--text-secondary-color, #8b949e);
+  }
+}
+
+/* ===== PERFORMANCE SECTION ===== */
+.performance-grid {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  margin: 2rem 0;
+}
+
+.perf-item {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+}
+
+.perf-bar {
+  flex: 0 0 120px;
+  height: 8px;
+  background: var(--surface-color, #21262d);
+  border-radius: 4px;
+  overflow: hidden;
+}
+
+.perf-fill {
+  height: 100%;
+  background: linear-gradient(90deg, #238636, #3fb950);
+  border-radius: 4px;
+  transition: width 1s ease;
+}
+
+.perf-info {
+  display: flex;
+  justify-content: space-between;
+  flex: 1;
+  min-width: 0;
+}
+
+.perf-title {
+  font-weight: 500;
+  color: var(--text-color, #f0f6fc);
+}
+
+.perf-value {
+  font-size: 0.875rem;
+  color: #3fb950;
+  font-weight: 600;
+}
+
+/* ===== CTA BOX ===== */
+.cta-box {
+  padding: 1.5rem;
+  margin: 2rem 0;
+  background: linear-gradient(135deg, rgba(88, 166, 255, 0.1), rgba(126, 231, 135, 0.1));
+  border: 1px solid rgba(88, 166, 255, 0.2);
+  border-radius: 12px;
+  text-align: center;
+  
+  h4 {
+    margin: 0 0 1rem;
+    color: var(--text-color, #f0f6fc);
+  }
+}
+
+.cta-links {
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+  flex-wrap: wrap;
+}
+
+/* ===== LANGUAGE SELECTOR ===== */
+.language-selector {
+  padding: 1.5rem;
+  background: var(--surface-color, #161b22);
+  border: 1px solid var(--border-color, #30363d);
+  border-radius: 12px;
+  margin: 2rem 0;
+  
+  p {
+    margin: 0 0 1rem;
+    text-align: center;
+    color: var(--text-secondary-color, #8b949e);
+  }
+}
+
+.lang-links {
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+}
+
+.lang-link {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem 1.25rem;
+  border-radius: 8px;
+  text-decoration: none !important;
+  background: var(--surface-color, #21262d);
+  border: 1px solid var(--border-color, #30363d);
+  transition: all 0.2s ease;
+  
+  &:hover,
+  &.active {
+    border-color: #58a6ff;
+    background: rgba(88, 166, 255, 0.1);
+    text-decoration: none !important;
+  }
+  
+  &.active {
+    .lang-name {
+      color: #58a6ff;
+      font-weight: 600;
+    }
+  }
+}
+
+.lang-flag {
+  font-size: 1.25rem;
+}
+
+.lang-name {
+  color: var(--text-color, #f0f6fc);
+}
+
+/* ===== CONTRIBUTING SECTION ===== */
+.contrib-grid {
+  display: flex;
+  gap: 1rem;
+  justify-content: center;
+  flex-wrap: wrap;
+  margin: 1.5rem 0;
+}
+
+.contrib-link {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem 1.25rem;
+  background: var(--surface-color, #161b22);
+  border: 1px solid var(--border-color, #30363d);
+  border-radius: 8px;
+  color: var(--text-color, #f0f6fc) !important;
+  text-decoration: none !important;
+  transition: all 0.2s ease;
+  
+  &:hover {
+    border-color: #58a6ff;
+    text-decoration: none !important;
+    transform: translateY(-1px);
+  }
+}
+
+.contrib-icon {
+  font-size: 1.25rem;
+}
+
+/* ===== RESPONSIVE DESIGN ===== */
+@media (max-width: 900px) {
+  .hero-section {
+    grid-template-columns: 1fr;
+    text-align: center;
+  }
+  
+  .hero-content {
+    max-width: 100%;
+  }
+  
+  .hero-actions {
+    justify-content: center;
+  }
+  
+  .hero-stats {
+    justify-content: center;
+  }
+  
+  .hero-visual {
+    order: -1;
+  }
+  
+  .code-window {
+    max-width: 100%;
+  }
+  
+  .features-grid {
+    grid-template-columns: 1fr;
+  }
+  
+  .docs-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (max-width: 600px) {
+  .hero-title {
+    font-size: 1.75rem;
+  }
+  
+  .hero-description {
+    font-size: 1rem;
+  }
+  
+  .btn {
+    padding: 0.625rem 1.25rem;
+    font-size: 0.9rem;
+  }
+  
+  .docs-grid {
+    grid-template-columns: 1fr;
+  }
+  
+  .perf-info {
+    flex-direction: column;
+    gap: 0.25rem;
+  }
+  
+  .lang-links {
+    flex-direction: column;
+  }
+  
+  .cta-links {
+    flex-direction: column;
+    
+    .btn {
+      width: 100%;
+      justify-content: center;
+    }
+  }
+}
+
+/* ===== LIGHT MODE SUPPORT ===== */
+@media (prefers-color-scheme: light) {
+  .code-window {
+    background: #f6f8fa;
+    border-color: #d0d7de;
+    box-shadow: 0 20px 40px rgba(0, 0, 0, 0.1);
+  }
+  
+  .code-header {
+    background: #eaeef2;
+    border-color: #d0d7de;
+  }
+  
+  .hero-badge {
+    background: rgba(9, 105, 218, 0.1);
+    border-color: rgba(9, 105, 218, 0.3);
+  }
+  
+  .badge-highlight {
+    color: #0969da;
+  }
+}
diff --git a/website/assets/js/main.js b/website/assets/js/main.js
index 1385825..3e1a827 100644
--- a/website/assets/js/main.js
+++ b/website/assets/js/main.js
@@ -1,105 +1,56 @@
-// ═══════════════════════════════════════════════════════════════
-// Tiny-LLM Main JavaScript
-// ═══════════════════════════════════════════════════════════════
+// Tiny-LLM Site JavaScript
 
-document.addEventListener('DOMContentLoaded', () => {
-  initBackToTop();
-  initMobileMenu();
-  initThemeToggle();
-});
-
-// ─── Back to Top Button ──────────────────────────────────────
-function initBackToTop() {
-  const button = document.querySelector('.back-to-top');
-  if (!button) return;
-
-  const toggleVisibility = () => {
-    if (window.scrollY > 300) {
-      button.classList.add('visible');
-    } else {
-      button.classList.remove('visible');
-    }
-  };
-
-  window.addEventListener('scroll', toggleVisibility);
-  button.addEventListener('click', () => {
-    window.scrollTo({ top: 0, behavior: 'smooth' });
-  });
-}
-
-// ─── Mobile Menu Toggle ──────────────────────────────────────
-function initMobileMenu() {
-  const menuToggle = document.querySelector('.menu-toggle');
-  const sideBar = document.querySelector('.side-bar');
-  if (!menuToggle || !sideBar) return;
-
-  menuToggle.addEventListener('click', () => {
-    sideBar.classList.toggle('open');
-    menuToggle.classList.toggle('active');
-  });
-
-  // Close menu when clicking outside
-  document.addEventListener('click', (e) => {
-    if (!sideBar.contains(e.target) && !menuToggle.contains(e.target)) {
-      sideBar.classList.remove('open');
-      menuToggle.classList.remove('active');
-    }
-  });
-}
-
-// ─── Theme Toggle ────────────────────────────────────────────
-function initThemeToggle() {
-  // Create theme toggle button if not exists
-  const headerActions = document.querySelector('.header-actions');
-  if (!headerActions) return;
-
-  const toggle = document.createElement('button');
-  toggle.className = 'theme-toggle';
-  toggle.setAttribute('aria-label', 'Toggle theme');
-  toggle.innerHTML = getThemeIcon();
-  headerActions.prepend(toggle);
-
-  toggle.addEventListener('click', () => {
-    const currentTheme = document.documentElement.getAttribute('data-theme');
-    const newTheme = currentTheme === 'light' ? 'dark' : 'light';
-    document.documentElement.setAttribute('data-theme', newTheme);
-    localStorage.setItem('theme', newTheme);
-    toggle.innerHTML = getThemeIcon(newTheme);
-  });
-}
-
-function getThemeIcon(theme = 'dark') {
-  if (theme === 'dark') {
-    return '<svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="5"/><path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/></svg>';
-  }
-  return '<svg viewBox="0 0 24 24" width="20" height="20" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>';
-}
-
-// ─── Service Worker Update Notification ──────────────────────
-if ('serviceWorker' in navigator) {
-  navigator.serviceWorker.addEventListener('controllerchange', () => {
-    console.log('[SW] New version available, reloading...');
-    window.location.reload();
-  });
-}
-
-// ─── Copy Code Button ───────────────────────────────────────
-function initCopyCodeButtons() {
-  const codeBlocks = document.querySelectorAll('pre');
-  codeBlocks.forEach((block) => {
+// Copy code buttons
+document.addEventListener('DOMContentLoaded', function() {
+  // Add copy buttons to code blocks
+  document.querySelectorAll('pre.highlight').forEach(function(block) {
     const button = document.createElement('button');
-    button.className = 'copy-code-btn';
+    button.className = 'copy-code-button';
     button.textContent = 'Copy';
-    button.addEventListener('click', async () => {
-      const code = block.querySelector('code')?.textContent;
-      if (!code) return;
-      await navigator.clipboard.writeText(code);
-      button.textContent = 'Copied!';
-      setTimeout(() => { button.textContent = 'Copy'; }, 2000);
+    button.setAttribute('aria-label', 'Copy code to clipboard');
+    
+    button.addEventListener('click', function() {
+      const code = block.querySelector('code');
+      if (code) {
+        navigator.clipboard.writeText(code.textContent).then(function() {
+          button.textContent = 'Copied!';
+          setTimeout(function() {
+            button.textContent = 'Copy';
+          }, 2000);
+        });
+      }
     });
+    
     block.style.position = 'relative';
     block.appendChild(button);
   });
-}
+});
 
-document.addEventListener('DOMContentLoaded', initCopyCodeButtons);
+// Copy button styles (injected via JS to avoid CSS file complexity)
+const copyButtonStyles = document.createElement('style');
+copyButtonStyles.textContent = `
+  .copy-code-button {
+    position: absolute;
+    top: 0.5rem;
+    right: 0.5rem;
+    padding: 0.25rem 0.75rem;
+    font-size: 0.75rem;
+    font-weight: 500;
+    color: var(--text-secondary-color, #8b949e);
+    background: var(--surface-secondary-color, #21262d);
+    border: 1px solid var(--border-color, #30363d);
+    border-radius: 4px;
+    cursor: pointer;
+    transition: all 0.2s ease;
+  }
+  
+  .copy-code-button:hover {
+    background: var(--border-color, #30363d);
+    color: var(--text-color, #f0f6fc);
+  }
+  
+  pre.highlight:hover .copy-code-button {
+    opacity: 1;
+  }
+`;
+document.head.appendChild(copyButtonStyles);
diff --git a/website/changelog/en/docs-ci-standardization.md b/website/changelog/en/docs-ci-standardization.md
deleted file mode 100644
index 7b4cf05..0000000
--- a/website/changelog/en/docs-ci-standardization.md
+++ /dev/null
@@ -1,150 +0,0 @@
----
-layout: default
-title: "Documentation & CI Standardization — Tiny-LLM"
-description: "Documentation separation and CPU-safe CI configuration"
-nav_order: 4
----
-
-# Documentation & CI Standardization
-
-**Date**: March 13, 2026  
-**Type**: Documentation / CI
-
----
-
-## Overview
-
-Separated documentation responsibilities and modernized CI configuration for CPU-only GitHub runners.
-
----
-
-## Changed
-
-### Documentation Structure
-
-| File | Before | After |
-|------|--------|-------|
-| `README.md` | Full documentation | Repository entry point only |
-| `index.md` | Duplicate of README | Documentation homepage |
-| `docs/en/`, `docs/zh/` | Did not exist | Full documentation in both languages |
-| `changelog/` | Single file | Structured directory with EN/ZH |
-
-#### Responsibility Separation
-
-| Document | Purpose |
-|----------|---------|
-| README | Project overview, badges, quick links |
-| index.md | Documentation landing with navigation |
-| docs/en/, docs/zh/ | Complete API and architecture docs |
-| changelog/ | Version history and release notes |
-
-### CI/CD Modernization
-
-#### Problem
-GitHub Actions runners don't have GPUs, making CUDA builds fail.
-
-#### Solution
-```yaml
-# ci.yml - Simplified for CPU-only runners
-jobs:
-  format-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: jidicula/clang-format-action@v4.13.0
-        with:
-          clang-format-version: '17'
-          check-path: '.'
-          
-  # CUDA builds removed (run locally or on GPU runners)
-```
-
-#### Pages Workflow
-
-```yaml
-# pages.yml - Enhanced for broader branch support
-on:
-  push:
-    branches: [main, master]
-  pull_request:
-    branches: [main, master]
-
-# Sparse checkout for faster deployment
-- uses: actions/checkout@v4
-  with:
-    sparse-checkout: |
-      docs/
-      changelog/
-```
-
----
-
-## Added
-
-### Format Validation
-
-```yaml
-- name: Check C++ formatting
-  uses: jidicula/clang-format-action@v4.13.0
-  with:
-    clang-format-version: '17'
-    exclude-regex: '(build/|third_party/)'
-```
-
-### Ignore Patterns
-
-| Pattern | Reason |
-|---------|--------|
-| `build/**` | CMake build directory |
-| `**/CMakeFiles/**` | CMake intermediates |
-| `**/*.cmake` | Generated files |
-
----
-
-## Removed
-
-### From CI
-
-- ❌ CUDA compilation steps
-- ❌ GPU-dependent tests
-- ❌ `nvidia/cuda` containers
-
-### From README
-
-- ❌ Detailed API documentation
-- ❌ Architecture diagrams
-- ❌ Long usage examples
-
----
-
-## Migration
-
-### For Contributors
-
-**Before**:
-```bash
-# Wait for CI GPU runners
-```
-
-**After**:
-```bash
-# Local validation before push
-./scripts/format-check.sh
-mkdir build && cd build
-cmake .. && make -j$(nproc)
-ctest
-```
-
----
-
-## Impact
-
-| Aspect | Before | After |
-|--------|--------|-------|
-| CI reliability | Unreliable | ✅ Stable |
-| CI runtime | 10+ min | ✅ 30s |
-| PR friction | High | ✅ Low |
-| Doc clarity | Mixed | ✅ Focused |
-
----
-
-[← Back to Changelog](../)
diff --git a/website/changelog/en/pages-enhancement.md b/website/changelog/en/pages-enhancement.md
deleted file mode 100644
index 74a357e..0000000
--- a/website/changelog/en/pages-enhancement.md
+++ /dev/null
@@ -1,123 +0,0 @@
----
-layout: default
-title: "GitHub Pages Enhancement — Tiny-LLM"
-description: "SEO, navigation, and documentation improvements"
-nav_order: 3
----
-
-# GitHub Pages Enhancement
-
-**Date**: March 10, 2026  
-**Type**: Documentation / CI
-
----
-
-## Overview
-
-Enhanced GitHub Pages deployment with SEO optimization, improved navigation, and documentation structure.
-
----
-
-## Changed
-
-### Jekyll Configuration
-
-`_config.yml` improvements:
-
-```yaml
-title: Tiny-LLM
-description: High-performance CUDA inference engine
-url: https://lessup.github.io
-baseurl: /tiny-llm
-lang: en
-author: Tiny-LLM Team
-
-plugins:
-  - jekyll-seo-tag    # Open Graph / Twitter Cards
-  - jekyll-sitemap    # XML sitemap
-```
-
-### Documentation Structure
-
-| Before | After |
-|--------|-------|
-| README as documentation | Separate docs/ folder |
-| Single language | EN/ZH bilingual |
-| No frontmatter | YAML frontmatter with SEO |
-| Manual navigation | Auto-generated nav_order |
-
-### SEO Improvements
-
-- ✅ Meta tags for all pages
-- ✅ Open Graph support
-- ✅ Twitter Cards
-- ✅ XML sitemap
-- ✅ Semantic HTML structure
-
----
-
-## Added
-
-### Documentation Templates
-
-All documentation files now include:
-
-```yaml
----
-layout: default
-title: "Page Title — Tiny-LLM"
-description: "Page description for SEO"
-nav_order: N
----
-```
-
-### Navigation
-
-- Breadcrumb-style footer on all pages
-- Language switchers
-- Next/previous page links
-
-### Visual Enhancements
-
-| Element | Implementation |
-|---------|---------------|
-| Badges | CI, Pages, Release, License |
-| ASCII diagrams | Architecture documentation |
-| Tables | GPU support, performance |
-| Code blocks | Syntax highlighting |
-
----
-
-## Technical
-
-### Workflow Optimization
-
-```yaml
-# .github/workflows/pages.yml
-- uses: actions/checkout@v4
-  with:
-    sparse-checkout: |  # Faster checkout
-      docs/
-      changelog/
-```
-
-### Build Performance
-
-| Metric | Before | After |
-|--------|--------|-------|
-| Checkout time | 5s | 2s |
-| Build time | 45s | 30s |
-| Page load | 800ms | 450ms |
-
----
-
-## Impact
-
-- 🚀 Better search engine visibility
-- 👥 Improved user navigation
-- 🌍 Full bilingual support
-- 📱 Mobile-responsive design
-
----
-
-[← Back to Changelog](../)
diff --git a/website/changelog/en/project-infrastructure.md b/website/changelog/en/project-infrastructure.md
deleted file mode 100644
index 1a8ba7a..0000000
--- a/website/changelog/en/project-infrastructure.md
+++ /dev/null
@@ -1,85 +0,0 @@
----
-layout: default
-title: "Project Infrastructure — Tiny-LLM"
-description: "Initial project setup with LICENSE and editor configuration"
-nav_order: 5
----
-
-# Project Infrastructure
-
-**Date**: February 13, 2025  
-**Type**: Infrastructure Setup
-
----
-
-## Overview
-
-Established the foundational project structure and configuration files.
-
----
-
-## Added
-
-### Legal & Governance
-
-| File | Purpose |
-|------|---------|
-| `LICENSE` | MIT License — permissive open source licensing |
-| `CODE_OF_CONDUCT.md` | Community guidelines |
-| `CONTRIBUTING.md` | Contribution guidelines |
-| `SECURITY.md` | Security policy |
-
-### Development Environment
-
-| File | Configuration |
-|------|---------------|
-| `.editorconfig` | UTF-8, LF, 4-space indentation for C++ |
-| `.gitignore` | CMake build artifacts, IDE files |
-| `.gitattributes` | Line ending normalization |
-
-#### EditorConfig Settings
-
-```ini
-[*]
-charset = utf-8
-end_of_line = lf
-insert_final_newline = true
-trim_trailing_whitespace = true
-indent_style = space
-indent_size = 4
-
-[*.{h,hpp,c,cpp,cu,cuh}]
-indent_size = 4
-
-[*.{yml,yaml,json,md}]
-indent_size = 2
-```
-
-### Documentation
-
-- Project README with badges
-- Initial project description
-- Basic build instructions
-
-### Badges
-
-```markdown
-![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
-![CUDA](https://img.shields.io/badge/CUDA-11.0+-76B900?logo=nvidia&logoColor=white)
-![C++](https://img.shields.io/badge/C%2B%2B-17-00599C?logo=c%2B%2B&logoColor=white)
-![CMake](https://img.shields.io/badge/CMake-3.18+-064F8C?logo=cmake&logoColor=white)
-```
-
----
-
-## Impact
-
-These files establish:
-- ✅ Clear licensing terms
-- ✅ Consistent coding style
-- ✅ Collaborative development standards
-- ✅ Professional project appearance
-
----
-
-[← Back to Changelog](../)
diff --git a/website/changelog/index.md b/website/changelog/index.md
index f3112c8..6e92e0b 100644
--- a/website/changelog/index.md
+++ b/website/changelog/index.md
@@ -7,10 +7,7 @@ nav_order: 100
 
 # Changelog
 
-All notable changes to this project are documented in this file.
-
-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).
+Tiny-LLM keeps a short, release-oriented changelog. This surface is reserved for meaningful external milestones.
 
 ---
 
@@ -21,14 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-## Release History
-
-### [Unreleased]
-
-- Documentation restructuring with improved bilingual support
-- Added comprehensive troubleshooting guides
-
----
+## Releases
 
 ### [2.0.1] — 2026-04-16
 
@@ -56,33 +46,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
-### Infrastructure & Documentation
-
-| Date | Description |
-|------|-------------|
-| 2026-03-13 | [Documentation & CI Standardization](en/docs-ci-standardization) — CPU-safe CI, Pages workflow fixes |
-| 2026-03-10 | [GitHub Pages Enhancement](en/pages-enhancement) — SEO, navigation, README improvements |
-| 2025-02-13 | [Project Infrastructure](en/project-infrastructure) — LICENSE, editorconfig, badges |
-
----
-
-## Version Legend
-
-| Type | Description |
-|------|-------------|
-| 🔴 **Breaking** | Breaking changes requiring migration |
-| 🟢 **Added** | New features |
-| 🔵 **Fixed** | Bug fixes |
-| 🟡 **Changed** | Changes to existing functionality |
-| 🟣 **Security** | Security-related changes |
-
----
-
-## Release Schedule
+## Notes
 
-- **Patch releases** (x.y.Z): Bug fixes, monthly as needed
-- **Minor releases** (x.Y.z): New features, quarterly
-- **Major releases** (X.y.z): Breaking changes, annually
+- Infrastructure-only cleanup is intentionally excluded from this public changelog.
+- For the current project story and onboarding flow, start at [Home](../) or [Documentation](../docs/).
 
 ---
 
diff --git a/website/changelog/index.zh.md b/website/changelog/index.zh.md
index c5b652a..621030b 100644
--- a/website/changelog/index.zh.md
+++ b/website/changelog/index.zh.md
@@ -6,10 +6,7 @@ description: "Tiny-LLM 版本历史和发布说明"
 
 # 更新日志
 
-本文档记录项目的所有重要变更。
-
-格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
-版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/spec/v2.0.0.html)。
+Tiny-LLM 只保留简洁、面向发布的公开更新日志。这里记录真正对外有意义的版本里程碑。
 
 ---
 
@@ -20,14 +17,7 @@ description: "Tiny-LLM 版本历史和发布说明"
 
 ---
 
-## 发布历史
-
-### [未发布]
-
-- 文档重构，改进双语支持
-- 添加全面的故障排除指南
-
----
+## 发布版本
 
 ### [2.0.1] — 2026-04-16
 
@@ -55,33 +45,10 @@ description: "Tiny-LLM 版本历史和发布说明"
 
 ---
 
-### 基础设施与文档
-
-| 日期 | 描述 |
-|------|-------------|
-| 2026-03-13 | [文档与 CI 规范化](../zh/docs-ci-standardization) — CPU-safe CI，Pages 工作流修复 |
-| 2026-03-10 | [GitHub Pages 增强](../zh/pages-enhancement) — SEO、导航、README 改进 |
-| 2025-02-13 | [项目基础设施](../zh/project-infrastructure) — 许可证、编辑器配置、徽章 |
-
----
-
-## 版本标签说明
-
-| 类型 | 说明 |
-|------|-------------|
-| 🔴 **破坏性变更** | 需要迁移的破坏性变更 |
-| 🟢 **新增** | 新功能 |
-| 🔵 **修复** | Bug 修复 |
-| 🟡 **变更** | 现有功能变更 |
-| 🟣 **安全** | 安全相关变更 |
-
----
-
-## 发布节奏
+## 说明
 
-- **补丁版本** (x.y.Z): Bug 修复，按需每月发布
-- **次要版本** (x.Y.z): 新功能，每季度发布
-- **主版本** (X.y.z): 破坏性变更，每年发布
+- 纯基础设施或低信号改动不会进入公开更新日志。
+- 如果你想快速了解项目定位与入口，请从 [首页](../) 或 [文档](../docs/) 开始。
 
 ---
 
diff --git a/website/changelog/zh/docs-ci-standardization.md b/website/changelog/zh/docs-ci-standardization.md
deleted file mode 100644
index 5a94554..0000000
--- a/website/changelog/zh/docs-ci-standardization.md
+++ /dev/null
@@ -1,150 +0,0 @@
----
-layout: default
-title: "文档与 CI 规范化 — Tiny-LLM"
-description: "文档分离和 CPU-safe CI 配置"
-nav_order: 4
----
-
-# 文档与 CI 规范化
-
-**日期**: 2026年3月13日  
-**类型**: 文档 / CI
-
----
-
-## 概述
-
-分离文档职责，并为仅 CPU 的 GitHub runners 现代化 CI 配置。
-
----
-
-## 变更
-
-### 文档结构
-
-| 文件 | 之前 | 之后 |
-|------|--------|-------|
-| `README.md` | 完整文档 | 仅作为仓库入口 |
-| `index.md` | README 的副本 | 文档首页 |
-| `docs/en/`, `docs/zh/` | 不存在 | 双语完整文档 |
-| `changelog/` | 单一文件 | 带 EN/ZH 的结构化目录 |
-
-#### 职责分离
-
-| 文档 | 用途 |
-|----------|---------|
-| README | 项目概览、徽章、快速链接 |
-| index.md | 带导航的文档落地页 |
-| docs/en/, docs/zh/ | 完整的 API 和架构文档 |
-| changelog/ | 版本历史和发布说明 |
-
-### CI/CD 现代化
-
-#### 问题
-GitHub Actions runners 没有 GPU，导致 CUDA 构建失败。
-
-#### 解决方案
-```yaml
-# ci.yml - 为仅 CPU runners 简化
-jobs:
-  format-check:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: jidicula/clang-format-action@v4.13.0
-        with:
-          clang-format-version: '17'
-          check-path: '.'
-          
-  # CUDA 构建移除（在本地或 GPU runners 上运行）
-```
-
-#### Pages 工作流
-
-```yaml
-# pages.yml - 增强分支支持
-on:
-  push:
-    branches: [main, master]
-  pull_request:
-    branches: [main, master]
-
-# 稀疏检出以加快部署
-- uses: actions/checkout@v4
-  with:
-    sparse-checkout: |
-      docs/
-      changelog/
-```
-
----
-
-## 新增
-
-### 格式验证
-
-```yaml
-- name: Check C++ formatting
-  uses: jidicula/clang-format-action@v4.13.0
-  with:
-    clang-format-version: '17'
-    exclude-regex: '(build/|third_party/)'
-```
-
-### 忽略模式
-
-| 模式 | 原因 |
-|---------|--------|
-| `build/**` | CMake 构建目录 |
-| `**/CMakeFiles/**` | CMake 中间文件 |
-| `**/*.cmake` | 生成的文件 |
-
----
-
-## 移除
-
-### 从 CI
-
-- ❌ CUDA 编译步骤
-- ❌ GPU 依赖的测试
-- ❌ `nvidia/cuda` 容器
-
-### 从 README
-
-- ❌ 详细的 API 文档
-- ❌ 架构图表
-- ❌ 长示例代码
-
----
-
-## 迁移
-
-### 对于贡献者
-
-**之前**:
-```bash
-# 等待 CI GPU runners
-```
-
-**之后**:
-```bash
-# 推送前本地验证
-./scripts/format-check.sh
-mkdir build && cd build
-cmake .. && make -j$(nproc)
-ctest
-```
-
----
-
-## 影响
-
-| 方面 | 之前 | 之后 |
-|--------|--------|-------|
-| CI 可靠性 | 不可靠 | ✅ 稳定 |
-| CI 运行时间 | 10+ 分钟 | ✅ 30秒 |
-| PR 摩擦 | 高 | ✅ 低 |
-| 文档清晰度 | 混合 | ✅ 专注 |
-
----
-
-[← 返回更新日志](../)
diff --git a/website/changelog/zh/pages-enhancement.md b/website/changelog/zh/pages-enhancement.md
deleted file mode 100644
index 8100fa8..0000000
--- a/website/changelog/zh/pages-enhancement.md
+++ /dev/null
@@ -1,123 +0,0 @@
----
-layout: default
-title: "GitHub Pages 增强 — Tiny-LLM"
-description: "SEO、导航和文档改进"
-nav_order: 3
----
-
-# GitHub Pages 增强
-
-**日期**: 2026年3月10日  
-**类型**: 文档 / CI
-
----
-
-## 概述
-
-增强 GitHub Pages 部署，包括 SEO 优化、改进导航和文档结构。
-
----
-
-## 变更
-
-### Jekyll 配置
-
-`_config.yml` 改进：
-
-```yaml
-title: Tiny-LLM
-description: High-performance CUDA inference engine
-url: https://lessup.github.io
-baseurl: /tiny-llm
-lang: en
-author: Tiny-LLM Team
-
-plugins:
-  - jekyll-seo-tag    # Open Graph / Twitter Cards
-  - jekyll-sitemap    # XML sitemap
-```
-
-### 文档结构
-
-| 之前 | 之后 |
-|--------|-------|
-| README 作为文档 | 单独的 docs/ 文件夹 |
-| 单一语言 | 英/中双语 |
-| 无 frontmatter | 带 SEO 的 YAML frontmatter |
-| 手动导航 | 自动生成的 nav_order |
-
-### SEO 改进
-
-- ✅ 所有页面的 Meta 标签
-- ✅ Open Graph 支持
-- ✅ Twitter Cards
-- ✅ XML sitemap
-- ✅ 语义化 HTML 结构
-
----
-
-## 新增
-
-### 文档模板
-
-所有文档文件现在包含：
-
-```yaml
----
-layout: default
-title: "Page Title — Tiny-LLM"
-description: "Page description for SEO"
-nav_order: N
----
-```
-
-### 导航
-
-- 所有页面的面包屑页脚
-- 语言切换器
-- 下一页/上一页链接
-
-### 视觉增强
-
-| 元素 | 实现 |
-|---------|---------------|
-| 徽章 | CI, Pages, Release, License |
-| ASCII 图表 | 架构文档 |
-| 表格 | GPU 支持、性能 |
-| 代码块 | 语法高亮 |
-
----
-
-## 技术
-
-### 工作流优化
-
-```yaml
-# .github/workflows/pages.yml
-- uses: actions/checkout@v4
-  with:
-    sparse-checkout: |  # 更快的检出
-      docs/
-      changelog/
-```
-
-### 构建性能
-
-| 指标 | 之前 | 之后 |
-|--------|--------|-------|
-| 检出时间 | 5s | 2s |
-| 构建时间 | 45s | 30s |
-| 页面加载 | 800ms | 450ms |
-
----
-
-## 影响
-
-- 🚀 更好的搜索引擎可见性
-- 👥 改进的用户导航
-- 🌍 完整的双语支持
-- 📱 移动端响应式设计
-
----
-
-[← 返回更新日志](../)
diff --git a/website/changelog/zh/project-infrastructure.md b/website/changelog/zh/project-infrastructure.md
deleted file mode 100644
index 2308552..0000000
--- a/website/changelog/zh/project-infrastructure.md
+++ /dev/null
@@ -1,85 +0,0 @@
----
-layout: default
-title: "项目基础设施 — Tiny-LLM"
-description: "初始项目设置，包含许可证和编辑器配置"
-nav_order: 5
----
-
-# 项目基础设施
-
-**日期**: 2025年2月13日  
-**类型**: 基础设施设置
-
----
-
-## 概述
-
-建立项目基础结构和配置文件。
-
----
-
-## 新增
-
-### 法律和治理
-
-| 文件 | 用途 |
-|------|---------|
-| `LICENSE` | MIT 许可证 — 宽松的开源许可 |
-| `CODE_OF_CONDUCT.md` | 社区行为准则 |
-| `CONTRIBUTING.md` | 贡献指南 |
-| `SECURITY.md` | 安全政策 |
-
-### 开发环境
-
-| 文件 | 配置 |
-|------|---------------|
-| `.editorconfig` | UTF-8, LF, C++ 4 空格缩进 |
-| `.gitignore` | CMake 构建产物, IDE 文件 |
-| `.gitattributes` | 换行符规范化 |
-
-#### EditorConfig 设置
-
-```ini
-[*]
-charset = utf-8
-end_of_line = lf
-insert_final_newline = true
-trim_trailing_whitespace = true
-indent_style = space
-indent_size = 4
-
-[*.{h,hpp,c,cpp,cu,cuh}]
-indent_size = 4
-
-[*.{yml,yaml,json,md}]
-indent_size = 2
-```
-
-### 文档
-
-- 带徽章的项目 README
-- 初始项目描述
-- 基础构建说明
-
-### 徽章
-
-```markdown
-![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
-![CUDA](https://img.shields.io/badge/CUDA-11.0+-76B900?logo=nvidia&logoColor=white)
-![C++](https://img.shields.io/badge/C%2B%2B-17-00599C?logo=c%2B%2B&logoColor=white)
-![CMake](https://img.shields.io/badge/CMake-3.18+-064F8C?logo=cmake&logoColor=white)
-```
-
----
-
-## 影响
-
-这些文件建立了：
-- ✅ 清晰的许可条款
-- ✅ 一致的代码风格
-- ✅ 协作开发标准
-- ✅ 专业的项目形象
-
----
-
-[← 返回更新日志](../)
diff --git a/website/docs/en/ARCHITECTURE.md b/website/docs/en/ARCHITECTURE.md
index 2df2680..1d76f42 100644
--- a/website/docs/en/ARCHITECTURE.md
+++ b/website/docs/en/ARCHITECTURE.md
@@ -423,19 +423,6 @@ Single Token (B, 1)
 
 ---
 
-## Roadmap
-
-| Feature | Status | Target |
-|---------|--------|--------|
-| GGUF Loading | 🚧 In Progress | v2.1 |
-| PagedAttention | 📋 Planned | v2.2 |
-| Continuous Batching | 📋 Planned | v2.3 |
-| Speculative Decoding | 🔬 Research | v2.4 |
-| FP8 Support | 🔬 Research | v3.0 |
-| Multi-GPU | 📋 Planned | v3.0 |
-
----
-
 **Languages**: [English](ARCHITECTURE) | [中文](../zh/ARCHITECTURE) | [API →](API)
 
 [← Quick Start](QUICKSTART) | [Developer Guide →](DEVELOPER)
diff --git a/website/docs/index.md b/website/docs/index.md
index 8379e70..0135c55 100644
--- a/website/docs/index.md
+++ b/website/docs/index.md
@@ -13,7 +13,7 @@ Welcome to the Tiny-LLM documentation. Choose your preferred language:
 
 ## 🌐 English
 
-<a href="en/" class="btn btn-primary">English Documentation →</a>
+<a href="en/" class="btn-home">English Documentation →</a>
 
 ### Quick Links
 
@@ -29,7 +29,7 @@ Welcome to the Tiny-LLM documentation. Choose your preferred language:
 
 ## 🇨🇳 中文
 
-<a href="zh/" class="btn btn-primary">中文文档 →</a>
+<a href="zh/" class="btn-home">中文文档 →</a>
 
 ### 快速链接
 
diff --git a/website/docs/zh/ARCHITECTURE.md b/website/docs/zh/ARCHITECTURE.md
index 94b1e8d..84cf7b3 100644
--- a/website/docs/zh/ARCHITECTURE.md
+++ b/website/docs/zh/ARCHITECTURE.md
@@ -423,19 +423,6 @@ void attention_prefill(
 
 ---
 
-## 路线图
-
-| 特性 | 状态 | 目标版本 |
-|---------|--------|--------|
-| GGUF 加载 | 🚧 进行中 | v2.1 |
-| PagedAttention | 📋 计划中 | v2.2 |
-| 连续批处理 | 📋 计划中 | v2.3 |
-| 投机解码 | 🔬 研究中 | v2.4 |
-| FP8 支持 | 🔬 研究中 | v3.0 |
-| 多 GPU | 📋 计划中 | v3.0 |
-
----
-
 **Languages**: [English](../en/ARCHITECTURE) | [中文](ARCHITECTURE) | [API 参考 →](API)
 
 [← 快速开始](QUICKSTART) | [开发者指南 →](DEVELOPER)
diff --git a/website/index.md b/website/index.md
index 3f9a21f..f83ed82 100644
--- a/website/index.md
+++ b/website/index.md
@@ -6,34 +6,36 @@ nav_order: 1
 permalink: /
 ---
 
+<link rel="stylesheet" href="{{ site.baseurl }}/assets/css/home.css">
+
 <!-- Hero Section -->
 <div class="hero-section">
   <div class="hero-content">
     <div class="hero-badge">
-      <span class="badge-highlight">v{{ site.version }} Released</span>
-      <a href="{{ site.baseurl }}/changelog/" class="changelog-link">See what's new</a>
+      <span class="badge-highlight">v{{ site.version }}</span>
+      <a href="{{ site.baseurl }}/changelog/" class="changelog-link">Read release notes →</a>
     </div>
 
     <h1 class="hero-title">
-      High-Performance<br>
-      <span class="gradient-text">CUDA Inference Engine</span>
+      CUDA-native<br>
+      <span class="gradient-text">Transformer Inference</span>
     </h1>
 
     <p class="hero-description">
-      Lightweight, efficient LLM inference with <strong>W8A16 quantization</strong>,
-      <strong>KV Cache optimization</strong>, and hand-tuned <strong>CUDA kernels</strong>.
-      Built for speed. Designed for developers.
+      A focused C++/CUDA inference engine built around <strong>W8A16 quantization</strong>,
+      explicit <strong>KV cache management</strong>, and hand-tuned <strong>CUDA kernels</strong>.
+      Small runtime surface, predictable architecture, and a public workflow that stays aligned with the code.
     </p>
 
     <div class="hero-actions">
       <a href="{{ site.baseurl }}/docs/en/QUICKSTART" class="btn btn-primary">
         Get Started
-        <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
           <path d="M5 12h14M12 5l7 7-7 7"/>
         </svg>
       </a>
       <a href="{{ site.repo_url }}" class="btn btn-secondary">
-        <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor">
           <path d="M12 0c-6.626 0-12 5.373-12 12 0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23.957-.266 1.983-.399 3.003-.404 1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576 4.765-1.589 8.199-6.086 8.199-11.386 0-6.627-5.373-12-12-12z"/>
         </svg>
         View on GitHub
@@ -47,13 +49,13 @@ permalink: /
       </div>
       <div class="stat-separator">|</div>
       <div class="stat">
-        <span class="stat-value">CUDA</span>
-        <span class="stat-label">Native Implementation</span>
+        <span class="stat-value">KV Cache</span>
+        <span class="stat-label">Incremental Decoding</span>
       </div>
       <div class="stat-separator">|</div>
       <div class="stat">
-        <span class="stat-value">W8A16</span>
-        <span class="stat-label">Quantization</span>
+        <span class="stat-value">OpenSpec</span>
+        <span class="stat-label">Governed Repository</span>
       </div>
     </div>
   </div>
@@ -79,7 +81,8 @@ config.hidden_dim = 4096;
 config.num_layers = 32;
 
 // Load with W8A16 weights
-auto engine = InferenceEngine::load("model.bin", config).value();
+auto engine = InferenceEngine::load(
+    "model.bin", config).value();
 
 // Generate with KV cache
 GenerationConfig gen;
@@ -99,30 +102,30 @@ auto output = engine.generate(prompt, gen);
 
 <div class="features-grid">
   <div class="feature-card">
-    <div class="feature-icon">&#9889;</div>
+    <div class="feature-icon">⚡</div>
     <h3>W8A16 Quantization</h3>
-    <p>INT8 weights with FP16 activations deliver <strong>~50% memory reduction</strong> while maintaining inference quality. Optimized for modern GPUs with Tensor Core support.</p>
+    <p>INT8 weights with FP16 activations deliver <strong>~50% memory reduction</strong> while maintaining inference quality.</p>
     <span class="badge badge-stable">Stable</span>
   </div>
 
   <div class="feature-card">
-    <div class="feature-icon">&#128190;</div>
+    <div class="feature-icon">💾</div>
     <h3>Efficient KV Cache</h3>
-    <p>State-of-the-art key-value cache management with <strong>O(1) incremental decoding</strong>. Supports dynamic sequence allocation and explicit length advancement.</p>
+    <p>State-of-the-art key-value cache with <strong>O(1) incremental decoding</strong> and dynamic allocation.</p>
     <span class="badge badge-stable">Stable</span>
   </div>
 
   <div class="feature-card">
-    <div class="feature-icon">&#128295;</div>
+    <div class="feature-icon">🔧</div>
     <h3>Optimized CUDA Kernels</h3>
-    <p>Hand-tuned kernels featuring shared memory tiling, warp shuffle reductions, and memory coalescing. Up to <strong>80% Tensor Core utilization</strong> on Ampere GPUs.</p>
+    <p>Hand-tuned kernels with shared-memory tiling and warp-level primitives tuned for inference workloads.</p>
     <span class="badge badge-stable">Stable</span>
   </div>
 
   <div class="feature-card">
-    <div class="feature-icon">&#127922;</div>
+    <div class="feature-icon">🎲</div>
     <h3>Advanced Sampling</h3>
-    <p>Multiple decoding strategies: Greedy, Temperature, Top-k, and Top-p (nucleus) sampling. All implemented as reusable standalone functions.</p>
+    <p>Greedy, temperature, top-k, and top-p sampling implemented as reusable engine utilities.</p>
     <span class="badge badge-stable">Stable</span>
   </div>
 </div>
@@ -146,12 +149,11 @@ git clone https://github.com/LessUp/tiny-llm.git
 cd tiny-llm
 
 # Build
-mkdir build && cd build
-cmake .. -DCMAKE_BUILD_TYPE=Release
-make -j$(nproc)
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
+cmake --build build -j$(nproc)
 
 # Run tests
-ctest --output-on-failure
+ctest --test-dir build --output-on-failure --timeout 300
 ```
 
 <div class="cta-box">
@@ -168,37 +170,37 @@ ctest --output-on-failure
 
 <div class="docs-grid">
   <a href="{{ site.baseurl }}/docs/en/QUICKSTART" class="doc-card">
-    <div class="doc-icon">&#128640;</div>
+    <div class="doc-icon">🚀</div>
     <h4>Quick Start</h4>
     <p>Get up and running in minutes</p>
   </a>
 
   <a href="{{ site.baseurl }}/docs/en/ARCHITECTURE" class="doc-card">
-    <div class="doc-icon">&#127959;</div>
+    <div class="doc-icon">🏗️</div>
     <h4>Architecture</h4>
     <p>System design and components</p>
   </a>
 
   <a href="{{ site.baseurl }}/docs/en/API" class="doc-card">
-    <div class="doc-icon">&#128214;</div>
+    <div class="doc-icon">📖</div>
     <h4>API Reference</h4>
     <p>Complete API documentation</p>
   </a>
 
   <a href="{{ site.baseurl }}/docs/en/DEVELOPER" class="doc-card">
-    <div class="doc-icon">&#128295;</div>
+    <div class="doc-icon">🔧</div>
     <h4>Developer Guide</h4>
     <p>Development and contribution</p>
   </a>
 
   <a href="{{ site.baseurl }}/docs/en/BENCHMARKS" class="doc-card">
-    <div class="doc-icon">&#9889;</div>
+    <div class="doc-icon">⚡</div>
     <h4>Benchmarks</h4>
     <p>Performance metrics and profiling</p>
   </a>
 
   <a href="{{ site.baseurl }}/docs/en/TROUBLESHOOTING" class="doc-card">
-    <div class="doc-icon">&#128269;</div>
+    <div class="doc-icon">🔍</div>
     <h4>Troubleshooting</h4>
     <p>Common issues and solutions</p>
   </a>
@@ -212,11 +214,11 @@ ctest --output-on-failure
   <p>Documentation available in multiple languages:</p>
   <div class="lang-links">
     <a href="{{ site.baseurl }}/docs/en/" class="lang-link active">
-      <span class="lang-flag">&#127482;&#127480;</span>
+      <span class="lang-flag">🇺🇸</span>
       <span class="lang-name">English</span>
     </a>
     <a href="{{ site.baseurl }}/docs/zh/" class="lang-link">
-      <span class="lang-flag">&#127464;&#127475;</span>
+      <span class="lang-flag">🇨🇳</span>
       <span class="lang-name">简体中文</span>
     </a>
   </div>
@@ -224,7 +226,7 @@ ctest --output-on-failure
 
 ---
 
-## Performance Highlights
+## Engineering Highlights
 
 <div class="performance-grid">
   <div class="perf-item">
@@ -232,8 +234,8 @@ ctest --output-on-failure
       <div class="perf-fill" style="width: 50%"></div>
     </div>
     <div class="perf-info">
-      <span class="perf-title">Memory Usage</span>
-      <span class="perf-value">-50% with W8A16</span>
+      <span class="perf-title">Quantization Path</span>
+      <span class="perf-value">W8A16 cuts weight memory</span>
     </div>
   </div>
 
@@ -242,8 +244,8 @@ ctest --output-on-failure
       <div class="perf-fill" style="width: 80%"></div>
     </div>
     <div class="perf-info">
-      <span class="perf-title">Tensor Core Util</span>
-      <span class="perf-value">~80% peak</span>
+      <span class="perf-title">Kernel Path</span>
+      <span class="perf-value">CUDA-native kernel path</span>
     </div>
   </div>
 
@@ -252,8 +254,8 @@ ctest --output-on-failure
       <div class="perf-fill" style="width: 95%"></div>
     </div>
     <div class="perf-info">
-      <span class="perf-title">Test Coverage</span>
-      <span class="perf-value">Comprehensive</span>
+      <span class="perf-title">Repository Workflow</span>
+      <span class="perf-value">OpenSpec + targeted validation</span>
     </div>
   </div>
 </div>
@@ -262,19 +264,19 @@ ctest --output-on-failure
 
 ## Contributing
 
-We welcome contributions! Check out our [Contributing Guide]({{ site.baseurl }}/CONTRIBUTING) to get started.
+Tiny-LLM accepts focused contributions. Start with the OpenSpec-aware [Contributing Guide]({{ site.baseurl }}/CONTRIBUTING) before broad edits.
 
 <div class="contrib-grid">
-  <a href="https://github.com/LessUp/tiny-llm/issues" class="contrib-link">
-    <span class="contrib-icon">&#128027;</span>
+  <a href="{{ site.repo_url }}/issues" class="contrib-link">
+    <span class="contrib-icon">🐛</span>
     <span>Report Issues</span>
   </a>
-  <a href="https://github.com/LessUp/tiny-llm/pulls" class="contrib-link">
-    <span class="contrib-icon">&#128260;</span>
+  <a href="{{ site.repo_url }}/pulls" class="contrib-link">
+    <span class="contrib-icon">🔄</span>
     <span>Submit PRs</span>
   </a>
-  <a href="https://github.com/LessUp/tiny-llm/discussions" class="contrib-link">
-    <span class="contrib-icon">&#128172;</span>
+  <a href="{{ site.repo_url }}/discussions" class="contrib-link">
+    <span class="contrib-icon">💬</span>
     <span>Discussions</span>
   </a>
 </div>
diff --git a/website/manifest.json b/website/manifest.json
index 61d84d9..46c77de 100644
--- a/website/manifest.json
+++ b/website/manifest.json
@@ -1,46 +1,24 @@
 {
   "name": "Tiny-LLM Documentation",
   "short_name": "TinyLLM",
-  "description": "High-Performance CUDA Inference Engine for LLMs — W8A16 quantization, KV Cache, and optimized CUDA kernels",
+  "description": "High-Performance CUDA Inference Engine for LLMs",
   "start_url": "/tiny-llm/",
   "scope": "/tiny-llm/",
   "display": "standalone",
-  "orientation": "portrait",
   "background_color": "#0d1117",
   "theme_color": "#0d1117",
   "icons": [
     {
-      "src": "/tiny-llm/assets/images/favicon-32x32.png",
-      "sizes": "32x32",
-      "type": "image/png",
-      "purpose": "any maskable"
-    },
-    {
-      "src": "/tiny-llm/assets/images/favicon-16x16.png",
-      "sizes": "16x16",
-      "type": "image/png",
-      "purpose": "any maskable"
-    },
-    {
-      "src": "/tiny-llm/assets/images/apple-touch-icon.png",
-      "sizes": "180x180",
-      "type": "image/png",
-      "purpose": "any"
-    },
-    {
-      "src": "/tiny-llm/assets/images/icon-192x192.png",
+      "src": "/tiny-llm/assets/icons/icon-192x192.svg",
       "sizes": "192x192",
-      "type": "image/png",
-      "purpose": "any maskable"
+      "type": "image/svg+xml"
     },
     {
-      "src": "/tiny-llm/assets/images/icon-512x512.png",
+      "src": "/tiny-llm/assets/icons/icon-512x512.svg",
       "sizes": "512x512",
-      "type": "image/png",
-      "purpose": "any maskable"
+      "type": "image/svg+xml"
     }
   ],
-  "categories": ["developer tools", "documentation"],
   "lang": "en",
   "dir": "ltr"
 }
diff --git a/website/sw.js b/website/sw.js
index 1c2e7d1..e98d45c 100644
--- a/website/sw.js
+++ b/website/sw.js
@@ -1,169 +1,39 @@
-// ═══════════════════════════════════════════════════════════════
-// Tiny-LLM Service Worker - PWA Support
-// Strategy: Cache-First with Network Fallback
-// Version: 2.1.0
-// ═══════════════════════════════════════════════════════════════
+// Tiny-LLM Service Worker (Minimal)
 
-const CACHE_VERSION = 'v2.1.0';
-const CACHE_NAME = `tiny-llm-${CACHE_VERSION}`;
-const STATIC_CACHE = `${CACHE_NAME}-static`;
-const DOCS_CACHE = `${CACHE_NAME}-docs`;
-
-// Assets to pre-cache on install
-const PRECACHE_URLS = [
+const CACHE_NAME = 'tiny-llm-v1';
+const STATIC_ASSETS = [
   '/tiny-llm/',
-  '/tiny-llm/index.html',
-  '/tiny-llm/manifest.json',
   '/tiny-llm/assets/css/custom.css',
-  '/tiny-llm/assets/js/main.js',
-  '/tiny-llm/404.html'
+  '/tiny-llm/assets/css/home.css',
+  '/tiny-llm/assets/js/main.js'
 ];
 
-// ═══════════════════════════════════════════════════════════════
-// INSTALL EVENT - Pre-cache critical assets
-// ═══════════════════════════════════════════════════════════════
-self.addEventListener('install', (event) => {
-  console.log('[SW] Installing v' + CACHE_VERSION);
-
+self.addEventListener('install', event => {
   event.waitUntil(
-    caches.open(STATIC_CACHE)
-      .then((cache) => {
-        console.log('[SW] Pre-caching assets');
-        return cache.addAll(PRECACHE_URLS);
-      })
-      .then(() => self.skipWaiting())
-      .catch((err) => console.error('[SW] Pre-cache failed:', err))
+    caches.open(CACHE_NAME).then(cache => {
+      return cache.addAll(STATIC_ASSETS);
+    })
   );
+  self.skipWaiting();
 });
 
-// ═══════════════════════════════════════════════════════════════
-// ACTIVATE EVENT - Clean up old caches
-// ═══════════════════════════════════════════════════════════════
-self.addEventListener('activate', (event) => {
-  console.log('[SW] Activating v' + CACHE_VERSION);
-
+self.addEventListener('activate', event => {
   event.waitUntil(
-    caches.keys()
-      .then((cacheNames) => {
-        return Promise.all(
-          cacheNames
-            .filter((name) => !name.startsWith(CACHE_NAME))
-            .map((name) => caches.delete(name))
-        );
-      })
-      .then(() => self.clients.claim())
+    caches.keys().then(cacheNames => {
+      return Promise.all(
+        cacheNames
+          .filter(name => name !== CACHE_NAME)
+          .map(name => caches.delete(name))
+      );
+    })
   );
+  self.clients.claim();
 });
 
-// ═══════════════════════════════════════════════════════════════
-// FETCH EVENT - Cache strategies
-// ═══════════════════════════════════════════════════════════════
-self.addEventListener('fetch', (event) => {
-  const { request } = event;
-  const url = new URL(request.url);
-
-  // Skip non-GET requests
-  if (request.method !== 'GET') return;
-
-  // Skip external requests
-  if (!url.pathname.startsWith('/tiny-llm/')) return;
-
-  // Choose strategy based on request type
-  if (isHTML(request)) {
-    event.respondWith(networkFirst(request));
-  } else if (isCSS(request) || isJS(request)) {
-    event.respondWith(staleWhileRevalidate(request));
-  } else if (isImage(request)) {
-    event.respondWith(cacheFirst(request, 'images'));
-  } else {
-    event.respondWith(cacheFirst(request));
-  }
-});
-
-// ═══════════════════════════════════════════════════════════════
-// CACHE STRATEGIES
-// ═══════════════════════════════════════════════════════════════
-
-// Cache First - For images and static assets
-async function cacheFirst(request, cacheName = STATIC_CACHE) {
-  const cached = await caches.match(request);
-  if (cached) return cached;
-
-  try {
-    const response = await fetch(request);
-    if (response.ok) {
-      const cache = await caches.open(cacheName);
-      cache.put(request, response.clone());
-    }
-    return response;
-  } catch (err) {
-    console.error('[SW] Cache-first fetch failed:', err);
-    return new Response('Offline', { status: 503 });
-  }
-}
-
-// Network First - For HTML pages (fresh content priority)
-async function networkFirst(request) {
-  const cache = await caches.open(DOCS_CACHE);
-
-  try {
-    const response = await fetch(request);
-    if (response.ok) {
-      cache.put(request, response.clone());
-    }
-    return response;
-  } catch (err) {
-    console.log('[SW] Network failed, serving cached:', request.url);
-    return cache.match(request) || caches.match('/tiny-llm/404.html');
-  }
-}
-
-// Stale While Revalidate - For CSS/JS (fast load + background update)
-async function staleWhileRevalidate(request) {
-  const cache = await caches.open(STATIC_CACHE);
-  const cached = await cache.match(request);
-
-  const fetchPromise = fetch(request)
-    .then((response) => {
-      if (response.ok) {
-        cache.put(request, response.clone());
-      }
-      return response;
+self.addEventListener('fetch', event => {
+  event.respondWith(
+    caches.match(event.request).then(response => {
+      return response || fetch(event.request);
     })
-    .catch(() => cached);
-
-  return cached || fetchPromise;
-}
-
-// ═══════════════════════════════════════════════════════════════
-// UTILITY FUNCTIONS
-// ═══════════════════════════════════════════════════════════════
-function isHTML(request) {
-  return request.headers.get('accept')?.includes('text/html') ||
-         request.url.endsWith('.html') ||
-         request.url.endsWith('/');
-}
-
-function isCSS(request) {
-  return request.url.endsWith('.css') ||
-         request.headers.get('accept')?.includes('text/css');
-}
-
-function isJS(request) {
-  return request.url.endsWith('.js') ||
-         request.headers.get('accept')?.includes('javascript');
-}
-
-function isImage(request) {
-  return request.destination === 'image' ||
-         /\.(jpg|jpeg|png|gif|webp|svg|ico)$/i.test(request.url);
-}
-
-// Message handler
-self.addEventListener('message', (event) => {
-  if (event.data?.type === 'SKIP_WAITING') {
-    self.skipWaiting();
-  }
+  );
 });
-
-console.log('[SW] Tiny-LLM Service Worker loaded');

From eca3b1e70768d1d1b7c7c246b00e09b3a3bcffae Mon Sep 17 00:00:00 2001
From: shijiashuai <shijiashuai@bgi.com>
Date: Fri, 24 Apr 2026 02:52:18 +0800
Subject: [PATCH 6/6] chore: remove obsolete specs and AI tool configs

- Remove legacy specs/ directory (migrated to openspec/)
- Remove QWEN.md and .qwen/ (consolidated to CLAUDE.md)
---
 .qwen/settings.json                        |   8 -
 QWEN.md                                    | 325 ---------------------
 specs/README.md                            |  28 --
 specs/api/inference-engine.yaml            |  77 -----
 specs/db/schema-v1.dbml                    | 178 -----------
 specs/product/tiny-llm-inference-engine.md | 104 -------
 specs/rfc/0001-core-architecture.md        | 156 ----------
 specs/rfc/0002-implementation-tasks.md     | 106 -------
 specs/testing/inference-engine.feature     |  77 -----
 9 files changed, 1059 deletions(-)
 delete mode 100644 .qwen/settings.json
 delete mode 100644 QWEN.md
 delete mode 100644 specs/README.md
 delete mode 100644 specs/api/inference-engine.yaml
 delete mode 100644 specs/db/schema-v1.dbml
 delete mode 100644 specs/product/tiny-llm-inference-engine.md
 delete mode 100644 specs/rfc/0001-core-architecture.md
 delete mode 100644 specs/rfc/0002-implementation-tasks.md
 delete mode 100644 specs/testing/inference-engine.feature

diff --git a/.qwen/settings.json b/.qwen/settings.json
deleted file mode 100644
index 933f475..0000000
--- a/.qwen/settings.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(find *)"
-    ]
-  },
-  "$version": 3
-}
\ No newline at end of file
diff --git a/QWEN.md b/QWEN.md
deleted file mode 100644
index 5a1f054..0000000
--- a/QWEN.md
+++ /dev/null
@@ -1,325 +0,0 @@
-# Tiny-LLM — Project Context
-
-## Project Overview
-
-**Tiny-LLM** is a lightweight, high-performance CUDA C++ inference engine for Transformer models. It is designed for efficient LLM deployment on NVIDIA GPUs (Compute Capability 7.0+ / Volta or newer) with W8A16 quantization (INT8 weights + FP16 activations), achieving ~50% memory reduction compared to FP16 inference.
-
-### Key Technologies
-
-| Technology | Version | Purpose |
-|------------|---------|---------|
-| CUDA | 11.0+ | GPU acceleration |
-| C++ | 17 | Host-side code |
-| CMake | 3.18+ | Build system |
-| spdlog | 1.12.0 | Logging (auto-fetched) |
-| GoogleTest | 1.14.0 | Unit testing (auto-fetched) |
-| RapidCheck | master | Property-based testing (auto-fetched) |
-
-### Architecture Constraints
-
-- **No exceptions for control flow** — errors use `Result<T>` monad
-- **W8A16 quantization** — INT8 weights, FP16 activations
-- **Zero external runtime dependencies** — pure CUDA C++
-- **Spec-Driven Development** — specs are the single source of truth
-
----
-
-## Directory Structure
-
-```
-tiny-llm/
-├── include/tiny_llm/      # Public headers (11 files)
-│   ├── inference_engine.h # Main engine class
-│   ├── kv_cache.h         # KVCacheManager
-│   ├── model_loader.h     # Model loading (binary + GGUF parser)
-│   ├── gguf_parser.h      # GGUF format parser (consolidated types)
-│   ├── transformer.h      # TransformerLayer forward pass
-│   ├── types.h            # ModelConfig, ModelWeights, GenerationConfig
-│   ├── result.h           # Result<T> monad for error handling
-│   ├── cuda_utils.h       # CUDA_CHECK macros, CudaException, DeviceBuffer
-│   ├── cuda_streams.h     # StreamPool, CudaEvent, KernelConfig
-│   ├── logger.h           # Logger singleton + TLLM_* macros
-│   └── validator.h        # Input validation utilities
-├── kernels/               # CUDA kernels (.cu / .cuh)
-│   ├── w8a16_matmul.cu    # Quantized matrix multiplication
-│   ├── attention.cu       # Attention decode/prefill kernels
-│   ├── rmsnorm.cu         # RMS normalization kernels
-│   ├── elementwise.cu     # Add, SiLU, gather embeddings kernels
-│   └── warp_utils.cuh     # Warp-level reduction utilities
-├── src/                   # Host-side implementations (.cpp)
-│   ├── main.cpp           # Demo entry point (excluded from lib)
-│   ├── inference_engine.cpp
-│   ├── model_loader.cpp
-│   ├── gguf_parser.cpp
-│   ├── kv_cache.cpp
-│   ├── transformer.cpp
-│   ├── types.cpp
-│   └── logger.cpp
-├── tests/                 # Unit & property-based tests (10 files)
-│   ├── test_main.cpp      # Test entry point
-│   ├── test_*.cpp         # CPU tests
-│   └── test_*.cu          # GPU tests
-├── specs/                 # Spec-Driven Development documents
-│   ├── product/           # Feature requirements
-│   ├── rfc/               # Architecture decisions (RFCs)
-│   ├── api/               # API definitions (YAML)
-│   ├── db/                # Data/model schemas
-│   └── testing/           # BDD test specs (.feature)
-├── website/               # GitHub Pages site (Jekyll)
-│   ├── docs/              # Documentation (EN/ZH)
-│   ├── changelog/         # Version history
-│   ├── assets/            # CSS, JS, images
-│   └── _config.yml        # Jekyll configuration
-├── .github/workflows/     # CI/CD pipelines
-│   ├── ci.yml             # Format check + build + test
-│   ├── pages.yml          # Jekyll build + deploy
-│   └── release.yml        # Release artifacts + GitHub release
-├── CMakeLists.txt         # Build configuration
-├── .clang-format          # LLVM-based C++17 formatting
-├── .editorconfig          # Editor settings
-└── README.md              # Project readme
-```
-
----
-
-## Building and Running
-
-### Prerequisites
-
-- NVIDIA GPU: SM 7.0+ (Volta or newer)
-- CUDA Toolkit: 11.0+
-- CMake: 3.18+
-- C++ Compiler: GCC 9+ or Clang 10+
-
-### Build Commands
-
-```bash
-# Clone
-git clone https://github.com/LessUp/tiny-llm.git
-cd tiny-llm
-
-# Configure and build (Release, with tests by default)
-mkdir build && cd build
-cmake .. -DCMAKE_BUILD_TYPE=Release
-make -j$(nproc)
-
-# Run tests
-ctest --output-on-failure
-
-# Debug build with tests
-cmake .. -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
-make -j$(nproc)
-ctest --output-on-failure
-
-# Build without tests
-cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=OFF
-make -j$(nproc)
-```
-
-### Build Targets
-
-| Target | Type | Description |
-|--------|------|-------------|
-| `tiny_llm` | Static library | Core inference engine |
-| `tiny_llm_demo` | Executable | Demo entry point (`src/main.cpp`) |
-| `tiny_llm_tests` | Executable | GoogleTest + RapidCheck tests |
-
-### Run Demo
-
-```bash
-./build/tiny_llm_demo
-```
-
----
-
-## Code Style and Conventions
-
-### Formatting
-
-- **Tool**: `clang-format` (LLVM-based, C++17)
-- **Config**: `.clang-format` at project root
-- **Column limit**: 100 characters
-- **Indentation**: 4 spaces (2 spaces for YAML/JSON)
-- **Pointer alignment**: Right (`int* ptr`)
-- **Brace style**: Attach (K&R)
-- **Include sorting**: Case-insensitive, preserve blocks
-
-Run formatting check:
-```bash
-clang-format -i src/*.cpp include/tiny_llm/*.h kernels/*.cu tests/*.cpp tests/*.cu
-```
-
-### Naming Conventions
-
-| Element | Style | Example |
-|---------|-------|---------|
-| Classes | PascalCase | `InferenceEngine`, `KVCacheManager` |
-| Functions | camelCase | `generate()`, `loadGGUF()` |
-| Member variables | snake_case with trailing `_` | `config_`, `weights_` |
-| Constants / macros | UPPER_SNAKE_CASE | `TLLM_INFO`, `BIN_MAGIC` |
-| Namespaces | snake_case | `tiny_llm` |
-| Files | snake_case | `inference_engine.h`, `w8a16_matmul.cu` |
-
-### Error Handling
-
-Use `Result<T>` monad — **never throw exceptions for control flow**:
-
-```cpp
-Result<ModelWeights> loadModel(const std::string& path) {
-    if (!fileExists(path)) {
-        return Result<ModelWeights>::err("File not found: " + path);
-    }
-    // ...
-    return Result<ModelWeights>::ok(weights);
-}
-
-// Usage
-auto result = loadModel("model.bin");
-if (result.isErr()) {
-    TLLM_ERROR("Failed to load model: {}", result.error());
-    return;
-}
-auto weights = result.value();
-```
-
-### Logging
-
-Use the `TLLM_*` macros from `logger.h`:
-
-```cpp
-TLLM_INFO("Model loaded successfully: {}", model_path);
-TLLM_WARN("KV cache full, evicting oldest sequence");
-TLLM_ERROR("CUDA kernel failed: {}", cudaGetErrorString(err));
-TLLM_DEBUG("Token generated: {}", token_id);
-```
-
----
-
-## Testing Practices
-
-### Test Framework
-
-- **GoogleTest** — unit tests, fixture-based tests
-- **RapidCheck** — property-based testing (generative tests)
-
-### Test File Conventions
-
-- Test files go in `tests/`
-- Naming: `test_<module>.cpp` or `test_<module>.cu`
-- `.cpp` for CPU tests, `.cu` for GPU tests
-- Each test file should have a corresponding header/implementation
-
-### Running Tests
-
-```bash
-# Run all tests
-ctest --output-on-failure
-
-# Run specific test by name
-ctest -R test_kv_cache
-
-# Run with verbose output
-ctest --output-on-failure -V
-
-# Run tests with timeout (seconds)
-ctest --output-on-failure --timeout 300
-```
-
----
-
-## Spec-Driven Development (SDD)
-
-This project follows **Spec-Driven Development**. Before writing code:
-
-1. **Read specs** in `/specs/` — they are the single source of truth
-2. **Update specs first** if creating new features or changing APIs
-3. **Implement code** that adheres to spec definitions
-4. **Write tests** based on spec acceptance criteria
-
-### Spec Directories
-
-| Directory | Purpose |
-|-----------|---------|
-| `specs/product/` | Feature requirements and acceptance criteria |
-| `specs/rfc/` | Technical design decisions (RFC format) |
-| `specs/api/` | API interface definitions (YAML) |
-| `specs/db/` | Data model schemas |
-| `specs/testing/` | BDD test case specifications (.feature) |
-
-### Spec Naming
-
-| Type | Pattern | Example |
-|------|---------|---------|
-| Product | `<feature-name>.md` | `tiny-llm-inference-engine.md` |
-| RFC | `<NNNN>-<short-title>.md` | `0001-core-architecture.md` |
-| API | `<feature-name>.yaml` | `inference-engine.yaml` |
-| Testing | `<feature-name>.feature` | `inference-engine.feature` |
-
----
-
-## CI/CD
-
-### Workflows
-
-| Workflow | Trigger | Purpose |
-|----------|---------|---------|
-| `ci.yml` | Push/PR to main | Format check → Build → Test |
-| `pages.yml` | Push to `website/` | Build & deploy GitHub Pages |
-| `release.yml` | Tag `v*.*.*` or manual | Create release with artifacts |
-
-### Environment Variables
-
-- `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` — set in all workflows to avoid Node.js 20 deprecation
-
----
-
-## Key Components
-
-### InferenceEngine
-
-Main entry point. Handles model loading, prompt prefilling, token generation, and sampling.
-
-```cpp
-auto engine = InferenceEngine::load("model.bin", config).value();
-auto tokens = engine.generate(prompt_tokens, gen_config).value();
-```
-
-### KVCacheManager
-
-Manages key-value cache for incremental decoding. Supports dynamic sequence allocation, explicit length advancement, and cache eviction.
-
-```cpp
-KVCacheManager cache(config);
-auto seq = cache.allocateSequence(64).value();
-cache.updateLength(seq.id, new_length);
-cache.releaseSequence(seq.id);
-```
-
-### W8A16 MatMul
-
-Quantized matrix multiplication: INT8 weights × FP16 input → FP32 output. Uses shared memory tiling and warp-level reductions for performance.
-
-### Result<T>
-
-Monadic error handling type. Key methods: `isOk()`, `isErr()`, `value()`, `error()`, `valueOr(default)`, `map(f)`, `flatMap(f)`.
-
----
-
-## Useful Commands
-
-```bash
-# Check formatting
-clang-format --dry-run --Werror $(find . -name '*.cpp' -o -name '*.h' -o -name '*.cu' -o -name '*.cuh' | grep -v build)
-
-# Generate compile_commands.json for IDE
-cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
-
-# Clean build
-rm -rf build/
-
-# Run tests with Google Test filter
-./build/tiny_llm_tests --gtest_filter="*KVCache*"
-
-# Check CUDA availability
-nvcc --version
-```
diff --git a/specs/README.md b/specs/README.md
deleted file mode 100644
index 93ac541..0000000
--- a/specs/README.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Specifications
-
-This directory contains all specification documents for the Tiny-LLM project. Specs are the **single source of truth** for all implementation decisions.
-
-## Directory Structure
-
-| Directory | Purpose |
-|-----------|---------|
-| `product/` | Product feature definitions, requirements, and acceptance criteria |
-| `rfc/` | Technical design documents and architecture decisions (RFC format) |
-| `api/` | API interface definitions (YAML, human and machine readable) |
-| `db/` | Database and model schema definitions |
-| `testing/` | BDD-style test case specifications (.feature files) |
-
-## Naming Conventions
-
-- **Product specs**: `<feature-name>.md` (e.g., `tiny-llm-inference-engine.md`)
-- **RFCs**: `<NNNN>-<short-title>.md` (e.g., `0001-core-architecture.md`)
-- **API specs**: `<feature-name>.yaml` or `<feature-name>.json`
-- **Test specs**: `<feature-name>.feature`
-
-## Workflow
-
-1. **New feature**: Create a product spec in `product/` and an RFC in `rfc/`
-2. **API changes**: Update or create files in `api/`
-3. **Test cases**: Define in `testing/` before implementation
-
-See [AGENTS.md](../AGENTS.md) for the complete Spec-Driven Development workflow.
diff --git a/specs/api/inference-engine.yaml b/specs/api/inference-engine.yaml
deleted file mode 100644
index 70022af..0000000
--- a/specs/api/inference-engine.yaml
+++ /dev/null
@@ -1,77 +0,0 @@
-# Tiny-LLM API Specification
-# Human-readable API definition for the inference engine
-
-## Core Types
-
-### ModelConfig
-Configuration for loading a Transformer model.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| vocab_size | int | Vocabulary size |
-| hidden_dim | int | Hidden dimension |
-| num_layers | int | Number of Transformer layers |
-| num_heads | int | Number of attention heads |
-| num_kv_heads | int | Number of KV heads (for GQA) |
-| head_dim | int | Dimension per head |
-| intermediate_dim | int | FFN intermediate dimension |
-| max_seq_len | int | Maximum sequence length |
-| rope_theta | float | RoPE theta |
-| rms_norm_eps | float | RMSNorm epsilon |
-
-### GenerationConfig
-Configuration for text generation.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| max_new_tokens | int | Maximum tokens to generate |
-| temperature | float | Sampling temperature |
-| top_k | int | Top-k sampling parameter |
-| top_p | float | Top-p (nucleus) sampling parameter |
-| eos_token_id | int | End-of-sequence token ID |
-
-## Public API
-
-### InferenceEngine::load(path, config) -> Result<InferenceEngine>
-Load a model from file path with given configuration.
-
-**Parameters:**
-- `path`: Model file path (string)
-- `config`: ModelConfig struct
-
-**Returns:**
-- `Result<InferenceEngine>`: Engine instance or error
-
-**Errors:**
-- File not found
-- Corrupted model file
-- GPU memory allocation failure
-- Invalid model dimensions
-
-### InferenceEngine::generate(tokens, config) -> vector<int>
-Generate tokens from a prompt.
-
-**Parameters:**
-- `tokens`: Input token IDs (vector<int>)
-- `config`: GenerationConfig struct
-
-**Returns:**
-- Generated token sequence including input tokens
-
-### InferenceEngine::prefill(tokens) -> void
-Process input tokens in parallel (prefill phase).
-
-### InferenceEngine::decodeStep(config) -> int
-Generate a single token (decode phase).
-
-**Returns:**
-- Next token ID
-
-## Error Types
-
-| Error | Description |
-|-------|-------------|
-| CudaException | CUDA runtime error with file and line |
-| ModelLoadError | Failed to load or validate model |
-| OutOfMemoryError | GPU memory exhausted |
-| InvalidModelError | Model file corrupted or invalid |
diff --git a/specs/db/schema-v1.dbml b/specs/db/schema-v1.dbml
deleted file mode 100644
index dfb0e2e..0000000
--- a/specs/db/schema-v1.dbml
+++ /dev/null
@@ -1,178 +0,0 @@
-// Tiny-LLM Model Schema
-// DBML-style definition for model architecture and data structures
-// Version: 2.0.1 | Last Updated: 2026-04-17
-
-// =============================================================================
-// Core Configuration Models
-// =============================================================================
-
-Table model_config {
-  vocab_size int [not null, default: 32000, note: "Vocabulary size"]
-  hidden_dim int [not null, default: 4096, note: "Hidden dimension (d_model)"]
-  num_layers int [not null, default: 32, note: "Number of Transformer layers"]
-  num_heads int [not null, default: 32, note: "Number of attention heads"]
-  num_kv_heads int [not null, default: 32, note: "Number of KV heads (GQA)"]
-  head_dim int [not null, default: 128, note: "Dimension per attention head"]
-  intermediate_dim int [not null, default: 11008, note: "FFN intermediate dimension"]
-  max_seq_len int [not null, default: 2048, note: "Maximum sequence length"]
-  rope_theta float [not null, default: 10000.0, note: "RoPE theta parameter"]
-  rms_norm_eps float [not null, default: 1e-5, note: "RMSNorm epsilon"]
-  eos_token_id int [not null, default: 2, note: "End-of-sequence token ID"]
-  bos_token_id int [not null, default: 1, note: "Beginning-of-sequence token ID"]
-}
-
-Table quantization_params {
-  group_size int [not null, default: 128, note: "Elements per scale factor"]
-  symmetric bool [not null, default: true, note: "Symmetric quantization (no zero point)"]
-}
-
-// =============================================================================
-// Weight Tensor Models
-// =============================================================================
-
-Table quantized_weight {
-  id int [pk]
-  name varchar [not null, note: "Weight tensor name"]
-  rows int [not null, note: "Number of rows (output dimension)"]
-  cols int [not null, note: "Number of columns (input dimension)"]
-  group_size int [not null, default: 128, note: "Quantization group size"]
-
-  // Derived fields (computed)
-  scale_rows int [note: "ceil(rows/group_size)"]
-  scale_cols int [note: "Same as cols"]
-  weight_bytes bigint [note: "rows * cols * sizeof(int8)"]
-  scale_bytes bigint [note: "scale_rows * scale_cols * sizeof(fp16)"]
-  total_bytes bigint [note: "weight_bytes + scale_bytes"]
-}
-
-Table transformer_weights {
-  id int [pk]
-  layer_index int [not null, note: "Layer index in model"]
-
-  // Attention weights (all quantized)
-  wq_id int [ref: > quantized_weight.id, note: "Query projection [hidden_dim, hidden_dim]"]
-  wk_id int [ref: > quantized_weight.id, note: "Key projection [hidden_dim, kv_dim]"]
-  wv_id int [ref: > quantized_weight.id, note: "Value projection [hidden_dim, kv_dim]"]
-  wo_id int [ref: > quantized_weight.id, note: "Output projection [hidden_dim, hidden_dim]"]
-
-  // FFN weights (SwiGLU, all quantized)
-  w1_id int [ref: > quantized_weight.id, note: "Gate projection [hidden_dim, intermediate_dim]"]
-  w2_id int [ref: > quantized_weight.id, note: "Down projection [intermediate_dim, hidden_dim]"]
-  w3_id int [ref: > quantized_weight.id, note: "Up projection [hidden_dim, intermediate_dim]"]
-
-  // Normalization weights (FP16, not quantized)
-  rms_att_weight_dim int [not null, note: "RMS attention weight dimension [hidden_dim]"]
-  rms_ffn_weight_dim int [not null, note: "RMS FFN weight dimension [hidden_dim]"]
-}
-
-Table model_weights {
-  id int [pk]
-
-  // Token embedding (FP16)
-  token_embedding_rows int [not null, note: "vocab_size"]
-  token_embedding_cols int [not null, note: "hidden_dim"]
-
-  // Output
-  final_norm_weight_dim int [not null, note: "hidden_dim"]
-  lm_head_id int [ref: > quantized_weight.id, note: "Output projection [hidden_dim, vocab_size]"]
-}
-
-// =============================================================================
-// Runtime State Models
-// =============================================================================
-
-Table kv_cache_config {
-  num_layers int [not null, default: 32]
-  num_heads int [not null, default: 32]
-  head_dim int [not null, default: 128]
-  max_seq_len int [not null, default: 2048]
-  max_batch_size int [not null, default: 1]
-}
-
-Table kv_cache_slot {
-  slot_id int [pk]
-  seq_len int [not null, default: 0, note: "Current sequence length"]
-  is_active bool [not null, default: false, note: "Slot is in use"]
-
-  // Memory layout: [num_layers, 2, max_seq_len, num_heads, head_dim]
-  // 2 = K and V tensors
-  k_cache_ptr bigint [note: "GPU pointer to K cache"]
-  v_cache_ptr bigint [note: "GPU pointer to V cache"]
-}
-
-Table generation_config {
-  max_new_tokens int [not null, default: 256]
-  temperature float [not null, default: 1.0]
-  top_k int [not null, default: 50]
-  top_p float [not null, default: 0.9]
-  do_sample bool [not null, default: false, note: "false = greedy"]
-  repetition_penalty float [not null, default: 1.0]
-}
-
-Table generation_stats {
-  prefill_time_ms float [default: 0.0]
-  decode_time_ms float [default: 0.0]
-  prompt_tokens int [default: 0]
-  tokens_generated int [default: 0]
-  tokens_per_second float [default: 0.0]
-  peak_memory_bytes bigint [default: 0]
-}
-
-// =============================================================================
-// Memory Layout Specifications
-// =============================================================================
-
-// KV Cache Memory Layout (FP16):
-// Shape: [num_layers, 2, max_batch_size, max_seq_len, num_heads, head_dim]
-// Total elements: num_layers * 2 * max_batch_size * max_seq_len * num_heads * head_dim
-// Total bytes: total_elements * sizeof(half) = total_elements * 2
-
-// Weight Memory Layout:
-// - QuantizedWeight: INT8 weights + FP16 scales
-// - Weights: [rows, cols] int8
-// - Scales: [ceil(rows/group_size), cols] fp16
-
-// Example for Llama-2-7B (hidden_dim=4096, num_layers=32, intermediate_dim=11008):
-// Per-layer attention: 4 * 4096 * 4096 = 67M parameters -> 67MB INT8 + 0.5MB scales
-// Per-layer FFN: 3 * 4096 * 11008 = 135M parameters -> 135MB INT8 + 1MB scales
-// Total per layer: ~202MB INT8 + ~1.5MB scales = ~203.5MB
-// Full model (32 layers): ~6.5GB INT8 (vs ~13GB FP16)
-
-// =============================================================================
-// GGUF File Format Schema
-// =============================================================================
-
-Table gguf_header {
-  magic varchar [not null, note: "GGUF magic number"]
-  version int [not null, note: "Format version"]
-  tensor_count bigint [not null, note: "Number of tensors"]
-  metadata_kv_count bigint [not null, note: "Number of metadata key-value pairs"]
-}
-
-Table gguf_metadata {
-  key varchar [pk, not null]
-  value_type varchar [not null, note: "String, Float, Int, Bool, Array, etc."]
-  value text [not null, note: "JSON-encoded value"]
-}
-
-Table gguf_tensor_info {
-  name varchar [pk, not null, note: "Tensor name"]
-  n_dims int [not null, note: "Number of dimensions"]
-  dims array [not null, note: "Dimension sizes"]
-  dtype varchar [not null, note: "Data type (F16, Q8_0, etc.)"]
-  offset bigint [not null, note: "Offset in file"]
-}
-
-// =============================================================================
-// Indexes for Query Optimization
-// =============================================================================
-
-// Primary lookup paths:
-// 1. Model config -> Model weights -> Transformer weights per layer
-// 2. Generation config -> Generation stats
-// 3. KV cache config -> KV cache slots by is_active
-
-// Notes:
-// - All GPU memory allocations use RAII pattern (DeviceBuffer)
-// - Error handling via Result<T> monad (no exceptions for control flow)
-// - Thread-safe: single-owner model, concurrent KV cache slot allocation
diff --git a/specs/product/tiny-llm-inference-engine.md b/specs/product/tiny-llm-inference-engine.md
deleted file mode 100644
index dc192d1..0000000
--- a/specs/product/tiny-llm-inference-engine.md
+++ /dev/null
@@ -1,104 +0,0 @@
-# Tiny-LLM Inference Engine — Product Specification
-
-> **Version:** 2.0.1 | **Date:** 2026-04-16 | **Status:** Implemented
-
-## Overview
-
-A lightweight LLM inference engine implementing W8A16 quantization, KV Cache incremental decoding, and modular Transformer inference for CUDA-enabled GPUs.
-
----
-
-## Terminology
-
-| Term | Description |
-|------|-------------|
-| W8A16 | Mixed precision: INT8 weights, FP16 activations |
-| KV Cache | Key-Value cache for autoregressive generation |
-| Warp Shuffle | CUDA warp-level data exchange instruction |
-| GQA | Grouped Query Attention |
-| GGUF | LLM model weight file format |
-
----
-
-## Functional Requirements
-
-### REQ-1: Model Loading
-
-- [x] Parse GGUF file headers and configuration
-- [x] Read binary format quantized weights
-- [x] Load INT8 weights and scales simultaneously
-- [x] Allocate GPU memory and transfer data
-- [x] Return error for corrupted files
-- [x] Provide structured model representation
-
-### REQ-2: W8A16 Matrix Multiplication
-
-- [x] Accept INT8 weights, FP16 activations, and scales
-- [x] Register-level dequantization
-- [x] Use CUDA intrinsics
-- [x] Warp shuffle optimization
-- [x] Configurable tile sizes
-- [x] Error vs FP16 baseline < 1%
-
-### REQ-3: KV Cache Management
-
-- [x] Pre-allocated GPU memory pool
-- [x] Allocate/release sequence slots
-- [x] Append KV pairs incrementally
-- [x] Track per-sequence usage
-- [x] Return error on memory exhaustion
-
-### REQ-4: Transformer Layer
-
-- [x] Q, K, V projections using W8A16
-- [x] Causal masking
-- [x] FFN using W8A16
-- [x] RMSNorm
-- [x] Residual connections
-- [x] Incremental decoding
-
-### REQ-5: Token Generation
-
-- [x] Prefill parallel processing
-- [x] Compute logits + sampling
-- [x] Update KV cache
-- [x] Configurable maximum length
-- [x] EOS detection for stopping
-- [x] Tokens/second statistics
-
-### REQ-6: Performance Optimization
-
-- [x] Global memory coalesced access
-- [x] Shared memory tiling
-- [x] Optimized thread block dimensions
-- [x] Minimized synchronization points
-- [x] CUDA streams support
-
-### REQ-7: Error Handling
-
-- [x] CUDA error capture
-- [x] Weight dimension validation
-- [x] Numerical validation options
-- [x] Memory allocation failure reporting
-- [x] Profiling mode timing
-
----
-
-## Non-Functional Requirements
-
-| Category | Requirement |
-|----------|-------------|
-| Precision | W8A16 achieves 99%+ precision vs FP16 baseline |
-| Memory | INT8 reduces ~50% weight memory |
-| Compatibility | CUDA 11.0+, CMake 3.18+, C++17 |
-| GPU | Compute Capability 7.0+ |
-
----
-
-## Version History
-
-| Version | Date | Changes |
-|---------|------|---------|
-| 2.0.1 | 2026-04-16 | Fixed scale dimension calculation bug |
-| 2.0.0 | 2026-03-09 | KVCache API refactoring |
-| 1.0.0 | 2025-02-13 | Initial release |
diff --git a/specs/rfc/0001-core-architecture.md b/specs/rfc/0001-core-architecture.md
deleted file mode 100644
index 55d29e7..0000000
--- a/specs/rfc/0001-core-architecture.md
+++ /dev/null
@@ -1,156 +0,0 @@
-# RFC-0001: Tiny-LLM Core Architecture
-
-> **Version:** 2.0.1 | **Date:** 2026-04-16 | **Status:** Implemented
-
-## Overview
-
-This RFC defines the core architecture of the lightweight LLM inference engine, focusing on W8A16 quantized inference and CUDA kernel implementation.
-
-### Design Goals
-
-| Goal | Description |
-|------|-------------|
-| Memory Efficiency | INT8 weight quantization, reducing ~50% memory |
-| Bandwidth Optimization | Register-level dequantization, maximizing bandwidth utilization |
-| Computational Efficiency | Warp shuffle + shared memory tiling |
-| Extensibility | Modular design supporting different model architectures |
-
----
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                      Host (CPU)                             │
-│  Model Loader  │  Tokenizer  │  Generation Controller      │
-└─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                      Device (GPU)                           │
-│                                                             │
-│  ┌─ Memory ─────────────────────────────────────────────┐  │
-│  │  Weight Memory (INT8+Scales)  │  KV Cache  │  Activ  │  │
-│  └───────────────────────────────────────────────────────┘  │
-│                                                             │
-│  ┌─ Kernels ────────────────────────────────────────────┐  │
-│  │  W8A16 MatMul  │  Attention  │  RMSNorm  │  Elemwise │  │
-│  └───────────────────────────────────────────────────────┘  │
-│                                                             │
-│  ┌─ Transformer ────────────────────────────────────────┐  │
-│  │  Layer 1  →  Layer 2  →  ...  →  Layer N            │  │
-│  └───────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Core Components
-
-### Model Loader
-
-```cpp
-struct ModelConfig {
-    int vocab_size, hidden_dim, num_layers;
-    int num_heads, num_kv_heads, head_dim;
-    int intermediate_dim, max_seq_len;
-    float rope_theta, rms_norm_eps;
-};
-
-struct QuantizedWeight {
-    int8_t* data;      // INT8 weights
-    half* scales;      // Per-group scales
-    int rows, cols, group_size;
-};
-```
-
-### W8A16 MatMul
-
-Formula: `output = input @ (weight_int8 * scales)`
-
-Optimization techniques:
-- Shared memory tiling: TILE_M × TILE_N × BLOCK_K
-- Warp shuffle reduction
-- Register-level dequantization
-
-### KV Cache Manager
-
-Key APIs:
-```cpp
-Result<int> allocateSequence(int max_len);
-void appendKV(seq_id, layer_idx, k, v, n);  // write-only
-void advanceSeqLen(seq_id, n);              // explicit advance
-void releaseSequence(int seq_id);
-```
-
----
-
-## Correctness Properties
-
-| ID | Property | Validation Requirement |
-|----|----------|----------------------|
-| P1 | W8A16 relative error < 1% | 2.5, 2.6 |
-| P2 | KV Cache invariants | 3.2-3.6 |
-| P3 | Causal masking correctness | 4.2 |
-| P4 | RMSNorm output RMS ≈ 1 | 4.4 |
-| P5 | Incremental decoding equivalent to full computation | 4.6 |
-| P6 | Greedy sampling = argmax | 5.2 |
-| P7 | Generation length ≤ max_new_tokens | 5.4 |
-| P8 | Scale dimension correctness | 1.3, 7.2 |
-| P9 | Corrupted file does not crash | 1.5 |
-
----
-
-## Error Handling
-
-```cpp
-// CUDA error checking
-#define CUDA_CHECK(call) \
-    do { \
-        cudaError_t err = call; \
-        if (err != cudaSuccess) throw CudaException(err, __FILE__, __LINE__); \
-    } while(0)
-
-// Result type
-template<typename T>
-class Result {
-    static Result<T> ok(T value);
-    static Result<T> err(std::string message);
-    bool isOk() const;
-    T& value();
-    const std::string& error() const;
-};
-```
-
----
-
-## Test Strategy
-
-| Type | Framework | Coverage |
-|------|-----------|----------|
-| Unit Tests | GoogleTest | Concrete examples, edge cases |
-| Property Tests | RapidCheck | General correctness (100+ iterations) |
-| Integration Tests | GoogleTest | End-to-end inference |
-
----
-
-## File Structure
-
-```
-tiny-llm/
-├── include/tiny_llm/     # Public headers
-│   ├── types.h           # Core types
-│   ├── result.h          # Error handling
-│   ├── cuda_utils.h      # CUDA utilities
-│   ├── kv_cache.h        # KV Cache
-│   ├── transformer.h     # Transformer layer
-│   ├── model_loader.h    # Model loading
-│   └── inference_engine.h
-├── kernels/              # CUDA Kernels
-│   ├── w8a16_matmul.cu
-│   ├── attention.cu
-│   ├── rmsnorm.cu
-│   └── elementwise.cu
-├── src/                  # Implementation
-└── tests/                # Tests
-```
diff --git a/specs/rfc/0002-implementation-tasks.md b/specs/rfc/0002-implementation-tasks.md
deleted file mode 100644
index d6d723f..0000000
--- a/specs/rfc/0002-implementation-tasks.md
+++ /dev/null
@@ -1,106 +0,0 @@
-# Tiny-LLM Implementation Tasks
-
-> **Version:** 2.0.1 | **Status:** ✅ Complete
-
----
-
-## Overview
-
-| Phase | Tasks | Status |
-|-------|-------|--------|
-| 1. Infrastructure | 3 | ✅ |
-| 2. Data Types | 2 | ✅ |
-| 3. Model Loading | 5 | ✅ |
-| 4. W8A16 | 4 | ✅ |
-| 5. KV Cache | 3 | ✅ |
-| 6. Attention | 4 | ✅ |
-| 7. Transformer | 3 | ✅ |
-| 8. Inference Engine | 5 | ✅ |
-| 9. Optimization | 3 | ✅ |
-| 10. Integration | 2 | ✅ |
-
----
-
-## Phase 1: Infrastructure ✅
-
-- [x] 1.1 Directory structure + CMake
-- [x] 1.2 CUDA error handling (CUDA_CHECK, Result<T>)
-- [x] 1.3 Error handling tests
-
-## Phase 2: Data Types ✅
-
-- [x] 2.1 ModelConfig, QuantizedWeight, TransformerWeights
-- [x] 2.2 Property test: Scale dimension consistency (P8)
-
-## Phase 3: Model Loading ✅
-
-- [x] 3.1 GGUF header parsing
-- [x] 3.2 Binary weight loading
-- [x] 3.3 GPU memory transfer
-- [x] 3.4 Property test: Corrupted file (P9)
-- [x] 3.5 Unit tests
-
-## Phase 4: W8A16 ✅
-
-- [x] 4.1 MatMul Kernel (tiling + dequant)
-- [x] 4.2 Warp shuffle optimization
-- [x] 4.3 Property test: Numerical precision (P1)
-- [x] 4.4 Unit tests
-
-## Phase 5: KV Cache ✅
-
-- [x] 5.1 Memory pool + slot management
-- [x] 5.2 allocate/append/release/getCache
-- [x] 5.3 Property test: Invariants (P2)
-
-## Phase 6: Attention ✅
-
-- [x] 6.1 RMSNorm Kernel
-- [x] 6.2 Property test: RMSNorm (P4)
-- [x] 6.3 Attention Kernel + causal masking
-- [x] 6.4 Property test: Causal masking (P3)
-
-## Phase 7: Transformer ✅
-
-- [x] 7.1 TransformerLayer (attention + FFN + residual)
-- [x] 7.2 KV Cache integration
-- [x] 7.3 Property test: Incremental decoding (P5)
-
-## Phase 8: Inference Engine ✅
-
-- [x] 8.1 prefill + decodeStep
-- [x] 8.2 Sampling strategies (greedy/temp/top-k/top-p)
-- [x] 8.3 Property test: Greedy sampling (P6)
-- [x] 8.4 Generation control + statistics
-- [x] 8.5 Property test: Length limit (P7)
-
-## Phase 9: Optimization ✅
-
-- [x] 9.1 Memory coalesced access
-- [x] 9.2 Block configuration optimization
-- [x] 9.3 CUDA streams
-
-## Phase 10: Integration ✅
-
-- [x] 10.1 Test models
-- [x] 10.2 End-to-end tests
-
----
-
-## Fixed Issues
-
-### v2.0.1 (2026-04-16)
-
-- [x] `test_integration.cu`: Scale dimension calculation error
-- [x] `attention.cu`: Removed unused code
-
----
-
-## Future Plans
-
-| Priority | Task | Status |
-|----------|------|--------|
-| P1 | Full GGUF runtime | Planned |
-| P2 | Configurable group_size | Planned |
-| P2 | Kernel error checking | Planned |
-| P3 | Paged Attention | Under evaluation |
diff --git a/specs/testing/inference-engine.feature b/specs/testing/inference-engine.feature
deleted file mode 100644
index ab06a14..0000000
--- a/specs/testing/inference-engine.feature
+++ /dev/null
@@ -1,77 +0,0 @@
-# Tiny-LLM Testing Specification
-# BDD-style test scenarios for the inference engine
-
-## Feature: Model Loading
-
-### Scenario: Load valid model file
-- Given a valid GGUF model file
-- When InferenceEngine::load() is called
-- Then the engine is successfully created
-- And weights are transferred to GPU memory
-
-### Scenario: Handle corrupted model file
-- Given a corrupted or invalid model file
-- When InferenceEngine::load() is called
-- Then an error is returned (not a crash)
-- And the error message describes the issue
-
-## Feature: W8A16 Quantization
-
-### Scenario: W8A16 MatMul precision
-- Given INT8 weights and FP16 activations
-- When W8A16 matmul is executed
-- Then the relative error vs FP16 baseline is < 1%
-
-### Scenario: Scale dimension correctness
-- Given per-group quantization scales
-- When scales are applied to weights
-- Then the output dimensions are correct
-
-## Feature: KV Cache
-
-### Scenario: Allocate and release sequence
-- Given an initialized KV cache
-- When a sequence is allocated
-- Then memory is reserved for the sequence
-- When the sequence is released
-- Then memory is freed and available for new sequences
-
-### Scenario: KV cache invariants
-- Given an active sequence in KV cache
-- When KV pairs are appended
-- Then the cache size never exceeds allocated capacity
-- And sequence length is tracked correctly
-
-## Feature: Token Generation
-
-### Scenario: Greedy sampling
-- Given logits from the model
-- When greedy sampling is used
-- Then the token with highest probability is selected
-
-### Scenario: Generation length limit
-- Given max_new_tokens = N
-- When generation is executed
-- Then the output length never exceeds N tokens
-- And EOS token stops generation early if encountered
-
-## Feature: Incremental Decoding
-
-### Scenario: Incremental equals full computation
-- Given a sequence of tokens
-- When incremental decoding processes tokens one-by-one
-- Then the output is equivalent to processing all tokens at once
-
-## Feature: Error Handling
-
-### Scenario: CUDA error recovery
-- Given a CUDA operation that may fail
-- When the operation fails
-- Then a CudaException is thrown
-- And the error includes file and line information
-
-### Scenario: Memory exhaustion
-- Given limited GPU memory
-- When allocation exceeds available memory
-- Then an OutOfMemoryError is returned
-- And existing allocations remain intact