diff --git a/pages/public/CNAME b/pages/public/CNAME
new file mode 100644
index 00000000..e72d26a1
--- /dev/null
+++ b/pages/public/CNAME
@@ -0,0 +1 @@
+open-codereview.ai
diff --git a/pages/src/components/HeroSection.tsx b/pages/src/components/HeroSection.tsx
index 32f895b2..0af00952 100644
--- a/pages/src/components/HeroSection.tsx
+++ b/pages/src/components/HeroSection.tsx
@@ -1,5 +1,6 @@
 import React, { useCallback, useState, useEffect } from 'react';
 import ReactDOM from 'react-dom';
+import { Link } from 'react-router-dom';
 import { useTranslation } from '../i18n';
 import { useResponsive } from '../hooks/useResponsive';
 import ColorBends from './ColorBends';
@@ -313,8 +314,8 @@ const HeroSection: React.FC = () => {
           >
             {t('hero.quickStart')}
           </a>
-          <a
-            href="#/docs"
+          <Link
+            to="/docs"
             style={{
               height: 32,
               display: 'flex',
@@ -330,7 +331,7 @@ const HeroSection: React.FC = () => {
             }}
           >
             {t('hero.learnMore')}
-          </a>
+          </Link>
         </div>
 
         {/* Terminal */}
diff --git a/pages/src/index.tsx b/pages/src/index.tsx
index 70557bcc..a9e25baf 100644
--- a/pages/src/index.tsx
+++ b/pages/src/index.tsx
@@ -1,6 +1,6 @@
 import React from 'react';
 import ReactDOM from 'react-dom/client';
-import { HashRouter } from 'react-router-dom';
+import { BrowserRouter } from 'react-router-dom';
 import App from './App';
 import { LanguageProvider } from './i18n';
 import './styles/index.css';
@@ -16,9 +16,9 @@ const root = ReactDOM.createRoot(rootElement);
 root.render(
   <React.StrictMode>
     <LanguageProvider>
-      <HashRouter>
+      <BrowserRouter>
         <App />
-      </HashRouter>
+      </BrowserRouter>
     </LanguageProvider>
   </React.StrictMode>
 );
diff --git a/pages/webpack.config.js b/pages/webpack.config.js
index 55e8b9f9..1aea6b54 100644
--- a/pages/webpack.config.js
+++ b/pages/webpack.config.js
@@ -8,7 +8,7 @@ module.exports = {
   output: {
     path: path.resolve(__dirname, 'dist'),
     filename: 'bundle.js',
-    publicPath: process.env.NODE_ENV === 'production' ? '/open-code-review/' : '/'
+    publicPath: '/'
   },
   module: {
     rules: [
@@ -65,6 +65,13 @@ module.exports = {
       template: './index.html',
       inject: 'body'
     }),
+    // SPA fallback: serve the app shell for deep links / refreshes on client-side
+    // routes (BrowserRouter). GitHub Pages returns this for unknown paths.
+    new HtmlWebpackPlugin({
+      template: './index.html',
+      inject: 'body',
+      filename: '404.html'
+    }),
     new CopyPlugin({
       patterns: [
         { from: 'public', to: '.', noErrorOnMissing: true }