docs: audit and fix documentation architecture

CONTRIBUTING.md

@@ -172,35 +172,23 @@ These commands help maintainers manage community contributions effectively and a
 
 ### Overview
 
-This documentation website is a **separate repository** from the main KubeStellar codebase. Here's the key architecture:
+This documentation website manages all content locally. Here's the repository structure:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│  Main KubeStellar Repository                                 │
-│  github.com/kubestellar/kubestellar                          │
+│  Docs Website Repository (THIS REPO)                         │
+│  github.com/kubestellar/docs                                 │
 │                                                               │
-│  📁 docs/content/                                            │
+│  📁 docs/content/        ← [SOURCE] All Markdown/MDX files   │
 │     ├── readme.md                                            │
-│     ├── architecture.md                                      │
 │     ├── direct/                                              │
-│     │   ├── binding.md                                       │
-│     │   └── wds.md                                           │
-│     └── ... (all documentation content)                      │
-└─────────────────────────────────────────────────────────────┘
-                          ↓
-                    (Fetched via GitHub API)
-                          ↓
-┌─────────────────────────────────────────────────────────────┐
-│  Docs Website Repository (THIS REPO)                         │
-│  github.com/kubestellar/docs                                 │
+│     └── ...                                                  │
 │                                                               │
-│  📁 src/app/docs/                                            │
-│     ├── page-map.ts     ← Defines navigation structure      │
-│     ├── layout.tsx       ← Nextra theme integration         │
-│     └── [...slug]/page.tsx  ← Renders fetched content       │
+│  📁 src/app/docs/        ← [ENGINE] Next.js/Nextra logic     │
+│     ├── page-map.ts      ← Defines sidebar structure         │
+│     └── [...slug]/page.tsx ← Renders content from docs/content│
 │                                                               │
-│  📁 next.config.ts      ← Nextra configuration              │
-│  📁 mdx-components.js   ← MDX component mappings            │
+│  📁 messages/            ← [I18N] Translation files          │
 └─────────────────────────────────────────────────────────────┘
                           ↓
                     (Built & Deployed)

docs/DEVELOPER_GUIDE.md

@@ -0,0 +1,45 @@
+# KubeStellar Documentation Developer Guide
+
+Welcome! This guide explains how the documentation system works and how to contribute effectively.
+
+## Architecture
+
+This site is built with **Next.js 15** and **Nextra 4**. It uses a hybrid approach:
+
+- **Unified Content**: Almost all documentation resides in `docs/content/`.
+- **Dynamic Routing**: The `src/app/docs/[...slug]` route dynamically renders Markdown/MDX files from the content folder.
+- **Navigation**: Sidebar structure is defined statically in `src/app/docs/page-map.ts`.
+
+## How to Add a Page
+
+1. **Add the File**: Create a `.md` or `.mdx` file in `docs/content/` (or a subfolder).
+2. **Update Navigation**: Add an entry to the `NAV_STRUCTURE` array in [page-map.ts](file:///Users/p0ptr0n/Documents/c0des/LFX/docs/src/app/docs/page-map.ts).
+   ```typescript
+   { 'My New Page': 'path/to/file.md' }
+   ```
+
+## Images and Assets
+
+- Images should be placed in `docs/content/images/` or a subfolder within the project (e.g., `docs/content/console/images/`).
+- **Pathing Rule**: Use the standardized `/docs-images/` prefix in your MDX/Markdown.
+  - Good: `![Logo](/docs-images/logo.png)`
+  - Next.js will automatically rewrite this to the correct local API for serving images from the content folder.
+
+## Internationalization (i18n)
+
+- UI strings are located in `messages/*.json`.
+- **Sidebar Titles**: We are currently migrating sidebar titles to use `next-intl`. Use the translation keys defined in the JSON files.
+
+## Maintenance Commands
+
+- `npm run dev`: Start local development server.
+- `npm run build`: Run production build (verifies MDX integrity).
+- `npm run lint`: Check for code and accessibility issues.
+
+## Common Issues
+
+### Build Failure: `localStorage is not defined`
+The build runs on the server. If a dependency uses `localStorage`, it will break. We have a mock in `next.config.ts`, but try to keep client-side code inside `useEffect` or behind a client-check.
+
+### Link Resolution
+The dynamic router tries to resolve relative links. If a link breaks, check that the file path in [page-map.ts](file:///Users/p0ptr0n/Documents/c0des/LFX/docs/src/app/docs/page-map.ts) exactly matches the file on disk.

docs/content/console/all-cards.md

@@ -224,7 +224,29 @@ The console includes 44+ additional specialized cards across categories like:
 - **Deploy** - Deployment management and progress tracking
 - **Events** - Event timeline and filtering
 - **Data Compliance** - Data classification and compliance checks
-- **Arcade** - Interactive visualizations
+- **Data Compliance** - Data classification and compliance checks
+- **Arcade** - Interactive visualizations:
+  - Kube-Man (Pac-Man style)
+  - Kube Kong (Donkey Kong style)
+  - Node Invaders (Space Invaders)
+  - Pod Pitfall (Pitfall adventure)
+  - Container Tetris
+  - Flappy Pod
+  - Pod Sweeper (Minesweeper)
+  - Kube 2048
+  - AI Checkers
+  - AI Chess
+  - Kube Solitaire
+  - Kube Match (Memory game)
+  - Kubedle (Wordle style)
+  - Sudoku
+  - Pod Brothers (Mario style)
+  - Kube Kart (Racing)
+  - Kube Pong
+  - Kube Snake
+  - Kube Galaga
+  - KubeCraft 2D
+  - KubeCraft 3D
 - **Card History** - Track card changes over time
 - **User Management** - Console user management