diff --git a/src/content/_meta.ts b/src/content/_meta.ts
index 3e40325..68866af 100644
--- a/src/content/_meta.ts
+++ b/src/content/_meta.ts
@@ -1,5 +1,22 @@
 const meta = {
-  index: "Getting Started",
+  index: 'Getting Started',
+
+  // guides: {
+  //   title: 'Guides',
+  //   collapsed: false,
+  //   order: 1,
+  // },
+
+  // reference: {
+  //   title: 'Reference',
+  //   collapsed: false,
+  //   order: 2,
+  // },
+
+  // architecture: {
+  //   title: 'Architecture',
+  //   order: 3,
+  // },
 };
 
 export default meta;
diff --git a/src/content/architecture/_meta.ts b/src/content/architecture/_meta.ts
new file mode 100644
index 0000000..42f95b4
--- /dev/null
+++ b/src/content/architecture/_meta.ts
@@ -0,0 +1,5 @@
+const meta = {
+  index: "Architecture",
+};
+
+export default meta;
diff --git a/src/content/architecture/index.mdx b/src/content/architecture/index.mdx
new file mode 100644
index 0000000..7013610
--- /dev/null
+++ b/src/content/architecture/index.mdx
@@ -0,0 +1,69 @@
+---
+title: "System Architecture"
+description: "A high-level overview of how the front-end, API routes and third-party services fit together."
+---
+
+import { Mermaid, Callout } from 'nextra/components'
+
+# System Architecture
+
+The project consists of **three main layers**:
+
+1. **Front-end** – a Next.js App Router application rendered on the edge.
+2. **API routes** – collocated inside <code>app/api/*</code>, exposing server-less endpoints.
+3. **Third-party services** – OpenAI, Vercel KV and Pagefind for search.
+
+---
+
+## Component diagram
+
+<Mermaid chart={`flowchart LR
+    subgraph Client
+        A[Browser] -- HTTP --> B[Next.js App]
+    end
+    subgraph Serverless
+        B --> C[API Route – /api/chat]
+        B --> D[API Route – /api/image]
+        B --> E[API Route – /api/articles/*]
+    end
+    subgraph OpenAI
+        F[(Chat Completion)]
+        G[(Embeddings)]
+        H[(TTS)]
+    end
+    C -- Web-Stream --> F
+    D --> H
+    E --> G
+    style A fill:#46f488,color:#fff
+    style B fill:#d06bee,color:#fff
+    style C fill:#fa7b6a,color:#fff
+    style D fill:#fa7b6a,color:#fff
+    style E fill:#fa7b6a,color:#fff
+    style F fill:#000,color:#46f488
+    style G fill:#000,color:#46f488
+    style H fill:#000,color:#46f488
+`} />
+
+---
+
+## Data flow (user asks a question in the chat widget)
+
+1. **Message mutation** – The React chat widget POSTs the message to **`/api/chat`**.
+2. **Tool-enabled streaming** – The API route uses <code>@ai-sdk/openai</code> to stream chunks back.
+3. **UI hydration** – The front-end consumes the stream with Server Sent Events and updates the UI in real time.
+
+---
+
+<Callout type="tip">The entire round-trip is <strong>edge-optimised</strong> – everything happens close to the user for low latency.</Callout>
+
+---
+
+## Where to look next
+
+| Path                       | What you will find                              |
+| -------------------------- | ----------------------------------------------- |
+| <code>app/api/chat/</code>         | Streaming AI completions with tools         |
+| <code>app/api/articles/*</code>    | Vector store ingest & search               |
+| <code>components/chat/</code>      | Front-end chat widget with tool rendering  |
+
+This should give you enough pointers to dive into the code with confidence.
diff --git a/src/content/guides/_meta.ts b/src/content/guides/_meta.ts
new file mode 100644
index 0000000..7dcc997
--- /dev/null
+++ b/src/content/guides/_meta.ts
@@ -0,0 +1,8 @@
+const meta = {
+  // index: "Guides",
+  // quickstart: "Quickstart",
+  // "documentation-authoring": "Documentation Authoring",
+  // contributing: "Contributing",
+};
+
+export default meta;
diff --git a/src/content/guides/contributing.mdx b/src/content/guides/contributing.mdx
new file mode 100644
index 0000000..125447f
--- /dev/null
+++ b/src/content/guides/contributing.mdx
@@ -0,0 +1,59 @@
+---
+title: "Contributing"
+description: "Guidelines for reporting issues, adding new features or improving the documentation."
+---
+
+import { Callout } from 'nextra/components'
+
+# Contributing
+
+We :heart: contributions! Whether it is a **bug report**, a **new feature** or an improvement to the **documentation**, your help makes the project better for everyone.
+
+---
+
+## 1&nbsp;· Find something to work on
+
+1. Browse the **Issues** tab and filter by the `good first issue` or `documentation` labels.
+2. Join the discussion to avoid duplicate work.
+
+<Callout type="tip">If you are unsure, open a **Draft PR** early – reviewers can then give feedback as you iterate.</Callout>
+
+---
+
+## 2&nbsp;· Fork & create a branch
+
+```bash
+git checkout -b feat/my-awesome-thing
+```
+
+Use **present-tense imperative** commit messages – e.g. _"Add solar panel power graph"_.
+
+---
+
+## 3&nbsp;· Run the checks locally
+
+```bash
+pnpm lint   # ESLint, TypeScript & MDX
+pnpm test   # unit tests (if any)
+pnpm build  # type errors & static site build
+```
+
+The CI pipeline runs the same commands – make them pass locally to save round-trips.
+
+---
+
+## 4&nbsp;· Open the pull request
+
+The PR template will ask you to confirm:
+
+• The code builds.  
+• New docs include front-matter.  
+• Screenshots / GIFs for UI changes are attached.
+
+Reviewers strive to respond within **48&nbsp;hours**. Feel free to ping after that.
+
+---
+
+## 5&nbsp;· Celebrate 🎉
+
+Your changes will land in `main` once approvals are in and checks are green. Thank you for investing your time!
diff --git a/src/content/guides/documentation-authoring.mdx b/src/content/guides/documentation-authoring.mdx
new file mode 100644
index 0000000..5fecee9
--- /dev/null
+++ b/src/content/guides/documentation-authoring.mdx
@@ -0,0 +1,99 @@
+---
+title: "Documentation Authoring"
+description: "Write, organise and publish MDX pages using Nextra."
+---
+
+import { Callout } from "nextra/components";
+
+# Documentation Authoring
+
+<Callout type="info">
+  If you prefer a deep-dive, open `deep-wiki/MARKDOWN_AUTHORING_GUIDE.md`. The
+  following is an opinionated **cheat-sheet** that covers 80&nbsp;% of
+  day-to-day cases.
+</Callout>
+
+---
+
+## File location
+
+• All docs live in **`deep-wiki/src/content/`**.  
+• Folders and filenames map 1-to-1 to the URL.
+
+```text
+src/content/
+└─ guides/
+   └─ quickstart.mdx  → /guides/quickstart
+```
+
+---
+
+## Front-matter template
+
+```mdx
+---
+title: "My Page Title"
+description: "One-sentence meta description (max ~160 chars)."
+---
+```
+
+`title` and `description` are **mandatory** – the CI fails otherwise.
+
+Optional extras:
+
+| Key            | What it does                              |
+| -------------- | ----------------------------------------- |
+| `sidebarTitle` | Short label in the sidebar                |
+| `toc`          | `false` hides the table of contents       |
+| `asIndexPage`  | Marks the file as the folder landing page |
+
+---
+
+## Update the sidebar (`_meta.ts`)
+
+Each folder has its own `_meta.ts` – update or create it:
+
+```ts
+const meta = {
+  index: "Overview",
+  quickstart: "Quickstart",
+  "documentation-authoring": "Documentation Authoring",
+};
+
+export default meta;
+```
+
+Not in the list? → Nextra will show the page **alphabetically at the bottom**.
+
+---
+
+## Built-in components
+
+| Component | Use-case                  | Example                              |
+| --------- | ------------------------- | ------------------------------------ |
+| `Callout` | Tips, warnings            | `<Callout type="tip">…</Callout>`    |
+| `Steps`   | Multi-step walkthroughs   | `<Steps>### One … ### Two …</Steps>` |
+| `Tabs`    | Code in npm / pnpm / yarn | `npm2yarn`                           |
+
+All components are tree-shaken by Next.js and add **zero client-side JS** unless needed.
+
+---
+
+## Preview locally
+
+```bash
+pnpm dev            # http://localhost:3000/docs
+```
+
+Hot re-load applies to both code **and** docs.
+
+---
+
+## Pull request checklist
+
+1. CI passes (`pnpm lint && pnpm build`).
+2. Exactly one `# H1` per file, no orphan `###` headings.
+3. No lines > 120&nbsp;chars outside code blocks.
+4. Every new page added to `_meta.ts`.
+
+Happy writing! ✨
diff --git a/src/content/guides/index.mdx b/src/content/guides/index.mdx
new file mode 100644
index 0000000..05eb542
--- /dev/null
+++ b/src/content/guides/index.mdx
@@ -0,0 +1,28 @@
+---
+title: "Guides"
+description: "Step-by-step tutorials that teach you how to work with the codebase and contribute to the project."
+asIndexPage: true
+---
+
+import { Steps, Callout } from 'nextra/components'
+
+# Guides
+
+This section is **task-oriented** – each article walks you through a specific activity such as spinning up the project for the first time, authoring new documentation, or submitting a pull request.
+
+<Callout type="info">If you are completely new to the codebase start with <strong>Quickstart</strong>.</Callout>
+
+<Steps>
+### Quickstart
+Clone the repo, install dependencies and run the development server locally.
+
+### Documentation Authoring
+Learn the MDX conventions and how to make your page appear in the sidebar.
+
+### Contributing
+Open a ticket, create a branch and raise a pull-request – our quality checklist in detail.
+</Steps>
+
+---
+
+Select a guide from the sidebar to get started ➡️
diff --git a/src/content/guides/quickstart.mdx b/src/content/guides/quickstart.mdx
new file mode 100644
index 0000000..64d54ba
--- /dev/null
+++ b/src/content/guides/quickstart.mdx
@@ -0,0 +1,85 @@
+---
+title: "Quickstart"
+description: "Zero-to-running in less than five minutes."
+---
+
+import { Steps, Callout } from "nextra/components";
+
+# Quickstart
+
+These instructions assume **macOS / Linux**.  
+Windows users can follow the same steps inside **WSL&nbsp;2**.
+
+---
+
+## 1&nbsp;· Clone & install dependencies
+
+```bash
+git clone <your-fork-url>
+cd <project-root>
+pnpm install
+```
+
+---
+
+## 2&nbsp;· Environment variables
+
+```bash
+cp .env.example .env
+# then open .env and fill in the missing secrets
+```
+
+At minimum you will need valid **OpenAI** keys if you intend to test the AI features locally.
+
+---
+
+## 3&nbsp;· Start the dev server
+
+```bash
+pnpm dev
+```
+
+Output should end with something like:
+
+```text
+ready - started server on 0.0.0.0:3000, url: http://localhost:3000
+```
+
+• **Main app:** [http://localhost:3000](http://localhost:3000)  
+• **Docs site:** [http://localhost:3000/docs](http://localhost:3000/docs)
+
+<Callout type="tip">
+  Both apps run in the same Next.js instance – there is no need to launch two
+  separate processes.
+</Callout>
+
+---
+
+## 4&nbsp;· Common dev commands
+
+| Command      | Purpose                             |
+| ------------ | ----------------------------------- |
+| `pnpm dev`   | Hot-reloading development server    |
+| `pnpm build` | Production build (app **and** docs) |
+| `pnpm lint`  | TypeScript, ESLint & MDX checks     |
+| `pnpm test`  | Jest / vitest (if present)          |
+
+---
+
+## 5&nbsp;· Next steps
+
+<Steps>
+### Play with components
+Open <code>components/</code> and tweak something – the browser auto reloads.
+
+### Explore the API routes
+
+Visit `/api/iss` in the browser – you should see live JSON from the International Space Station.
+
+### Add a new documentation page
+
+Follow the **Documentation Authoring** guide → create `src/content/my-page.mdx` → refresh `/docs`.
+
+</Steps>
+
+You are now set! 🚀
diff --git a/src/content/index.mdx b/src/content/index.mdx
index ae4b8e6..9553aaf 100644
--- a/src/content/index.mdx
+++ b/src/content/index.mdx
@@ -1,176 +1,94 @@
 ---
 title: "Getting Started"
-description: "Quickly learn how to set up and start using this project."
+description: "Install dependencies, run the project locally and get an overview of what lives where."
 ---
 
-import { Steps, Callout, Mermaid } from 'nextra/components'
-
-## ➊ Where to drop a new page
-
-```text
-app/
-  docs/                 ← existing docs tree (App Router)
-    <topic>/page.mdx    ← add files here **or**
-content/                ← optional flat MDX tree (no page.mdx rule)
-src/mdx-components.js   ← must exist – leave untouched
-```
-
-- **App folder = “page.mdx” convention.**
-  Create `app/docs/my-topic/page.mdx`.
-- **Content folder = filename is route.**
-  Create `content/my-topic.mdx`, **plus** the catch-all route already in `app/[[...mdxPath]]/page.jsx`.
-
-> If you choose `content/`, set `contentDirBasePath` in `next.config.mjs` if you need a prefix (e.g. `/docs`).
-
----
-
-## ➋ Front-matter template
+import { Callout, Steps } from "nextra/components";
 
-Every MDX file should start with something like:
+# Welcome 👋
 
-```md
----
-title: Awesome Feature # <h1> title
-sidebarTitle: Awesome # optional, compact label in sidebar
-description: Short SEO-ish blurb shown in <meta>
-icon: FileIcon # if the parent section supports it
-asIndexPage: true # only if this page IS the folder index
----
-```
+This short guide helps you **clone, install and run** the project in less than&nbsp;5&nbsp;minutes.  
+If you are looking for more in-depth material, head over to the **Guides** and **Reference** sections in the sidebar.
 
 ---
 
-## ➌ Adding rich content
+## Project prerequisites
 
-| Want                        | Minimal syntax (**works out-of-box**)                                                                       | Notes                                                                        |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| **Table**                   | GFM pipes:<br/>`\| a \| b \|`                                                                               | Auto-drawn & styled. Raw `<table>` needs `whiteListTagsStyling` option.      |
-| **Mermaid diagram**         | `mermaid code block`                                                                                        | Plugin replaces block with `<Mermaid>` component.                            |
-| **KaTeX / MathJax**         | `$a^2+b^2=c^2$` or fenced `math blocks`                                                                     | Ensure `latex: true` (KaTeX) or `{renderer:'mathjax'}` in `next.config.mjs`. |
-| **Syntax-highlighted code** | `js {1,4-5} copy showLineNumbers`                                                                           | Shiki; line/substring/filename/highlight/copy supported.                     |
-| **npm → Yarn tabs**         | \`\`\`sh npm2yarn                                                                                           | Shows tabs for npm/yarn/pnpm/bun via `remark-npm2yarn`.                      |
-| **Twoslash TS hovers**      | \`\`\`ts twoslash                                                                                           | Show type-insight balloons & custom `@log`, `@error`…                        |
-| **Steps / Tabs / Callout**  | Import from `nextra/components` inside MDX: <br/>`import { Steps, Tabs, Callout } from 'nextra/components'` | Rich layout helpers.                                                         |
-| **Static image with zoom**  | `![Alt](/public/foo.png)`                                                                                   | Next/Image wrapper & zoom by default; disable via custom `img`.              |
-| **Live coding**             | Embed Sandpack / react-live like any React component.                                                       |                                                                              |
+| Tool                           | Version | Notes                                           |
+| ------------------------------ | :-----: | ----------------------------------------------- |
+| [Node.js](https://nodejs.org/) |  ≥ 18   | Required by `next` and the build step           |
+| [pnpm](https://pnpm.io/)       |   ≥ 8   | We use the fast, disk-efficient package manager |
+| **.env** file                  |    –    | Copy `.env.example` → `.env` and fill in keys   |
 
-### Steps component example
-
-<Steps>
-### Install
-Run `npm create latest`
-### Develop
-Start the local dev server with `npm run dev`.
-### Deploy
-Push to Vercel / Netlify or any static host.
-</Steps>
+<Callout type="warning">
+  If you are using **nvm** make sure to <code>nvm use</code> the correct Node
+  version **before** you run any commands.
+</Callout>
 
 ---
 
-## ➍ Sidebar & navbar housekeeping (`_meta.js`)
-
-- **Order / titles** – Add or override keys in the folder’s `_meta.js`:
-
-  ```js
-  export default {
-    index: "Intro",
-    advanced: "Advanced Guides",
-    "###": { type: "separator", title: "Extra" },
-    faq: { title: "FAQ", type: "page" }, // moves into top navbar
-  };
-  ```
+## ➊ Install dependencies
 
-- **Hide a file** – `display: 'hidden'`.
-
-- **Per-page theme tweaks** – `theme: { sidebar:false, layout:'full', typesetting:'article' }`.
+```bash
+pnpm install
+```
 
 ---
 
-## ➎ Global features already on
+## ➋ Local development
 
-- **Search** → requires `pagefind` + postbuild script.
-  _(If you copied the starter, this is configured – otherwise add it.)_
-- **Static image optimisation** – `staticImage:true` defaults.
-- **Syntax highlighting** – `codeHighlight:true`.
-- **Image zoom** – enabled; use `<Image>` to opt-out per image.
+```bash
+pnpm dev
+```
 
----
+When the server boots you should see two separate applications:
 
-## ➏ Common pitfalls an LLM should avoid
+1. **Main app** – [http://localhost:3000](http://localhost:3000)
+2. **Docs site** – [http://localhost:3000/docs](http://localhost:3000/docs)
 
-| Pitfall                                                         | How to dodge it                                                                  |
-| --------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| Using **Pages router** examples                                 | Nextra v4 **only** supports App Router.                                          |
-| Forgetting `mdx-components.js`                                  | File must export `useMDXComponents`; leave starter intact.                       |
-| Adding non-serialisable functions when Turbopack dev flag is on | Keep `remarkPlugins` etc. out of `nextra()` when running `next dev --turbopack`. |
-| KaTeX CSS missing                                               | Import `katex/dist/katex.min.css` or link CDN **when `latex:true`.**             |
-| Raw HTML table unstyled                                         | Either write GFM or whitelist tags with `whiteListTagsStyling`.                  |
+Changes in `app/` (product) or in `deep-wiki/src/content/` (docs) trigger **hot-reload**.
 
 ---
 
-## ➐ End-to-end example: new page with table + diagram
-
-````mdx
-## <!-- app/docs/performance/page.mdx -->
+## ➌ Production build
 
-title: Performance Tips
-sidebarTitle: ⚡️ Perf
-description: Practical tricks to speed things up.
-icon: LightningIcon
+```bash
+pnpm build       # build everything (app _and_ docs)
+pnpm start       # preview the output locally
+```
 
 ---
 
-import { Callout, Steps } from "nextra/components";
-
-# Performance Tips
-
-<Callout type="tip">Start with measuring!</Callout>
+## ➍ Project layout (quick tour)
 
-## Benchmark table
-
-| Technique  | Avg gain |
-| :--------- | -------: |
-| Memoize    |     23 % |
-| Code-split |     15 % |
-
-
-## Architecture
-
-<Mermaid chart={`graph LR
-A[User] --> B(CDN) --> C(Edge Fn) --> D(DB)
-`} />
-````
-
-```mdx
-<Steps>### Measure Explain how... ### Optimise Explain how...</Steps>
+```text
+app/                     ← Next.js (App Router)
+└─ api/                  ← Edge & Serverless routes
+components/              ← Re-usable UI building blocks
+deep-wiki/               ← Documentation site (this folder)
+└─ src/content/          ← **Your .mdx docs live here**
+public/                  ← Static assets (images, fonts…)
 ```
 
-Save the file, run `npm run dev`, and the page auto-appears in the sidebar under **⚡️ Perf**.
+For a **detailed walk-through** of the docs system itself, read the
+[Documentation Authoring](/guides/documentation-authoring) guide.
 
 ---
 
-### Live preview of the example
+## ➎ Next steps
 
-<Callout type="tip">Start with measuring!</Callout>
+<Steps>
+### Explore the code
+Open the `app/` and `components/` folders – each file is typed and documented.
 
-## Benchmark table
+### Read the guides
 
-| Technique  | Avg gain |
-| :--------- | -------: |
-| Memoize    |     23 % |
-| Code-split |     15 % |
+Navigate to the **Guides** section for tutorials like _Quickstart_ and _Contributing_.
 
-## Architecture
+### Build something cool!
 
-<Mermaid chart={`graph LR
-A[User] --> B(CDN) --> C(Edge Fn) --> D(DB)
-`} />
+Clone a page from `app/charts` or `components/solar-panel` and start hacking.
 
-<Steps>
-### Measure
-Explain how...
-### Optimise
-Explain how...
 </Steps>
 
----
+Happy coding! ✨
diff --git a/src/content/reference/_meta.ts b/src/content/reference/_meta.ts
new file mode 100644
index 0000000..7435a39
--- /dev/null
+++ b/src/content/reference/_meta.ts
@@ -0,0 +1,7 @@
+const meta = {
+  // index: 'Overview',
+  // api: 'API',
+  // components: 'Components',
+};
+
+export default meta;
diff --git a/src/content/reference/api.mdx b/src/content/reference/api.mdx
new file mode 100644
index 0000000..3ce10e0
--- /dev/null
+++ b/src/content/reference/api.mdx
@@ -0,0 +1,97 @@
+---
+title: "API"
+description: "HTTP endpoints exposed under /api with example requests and responses."
+---
+
+import { Callout, Tabs } from "nextra/components";
+
+# API Reference
+
+All backend functionality is delivered through **Next.js API Routes** under `/api/*`. Each route runs in a **serverless environment** (Edge Runtime where possible) and can therefore be called from any HTTP client.
+
+Authentication is handled via bearer tokens where required; public routes (e.g. ISS position) need none.
+
+---
+
+## Index
+
+|   Method   | Route                         | Description                                                  |
+| :--------: | ----------------------------- | ------------------------------------------------------------ |
+|    GET     | `/api/iss`                    | Real-time International Space Station position.              |
+|    POST    | `/api/chat`                   | Streaming AI chat completions with **tool calling** enabled. |
+|    POST    | `/api/image`                  | Generates an image using the OpenAI Images API.              |
+|    GET     | `/api/articles/ingest`        | Embed & store the sample articles in the vector DB.          |
+|    GET     | `/api/articles/search?query=` | Semantic search across the vector DB.                        |
+|    POST    | `/api/moderate`               | Content moderation – flags rude / offensive comments.        |
+| GET / POST | `/api/podcast`                | Text-to-Speech (TTS) – returns an MP3 / WAV audio stream.    |
+|    GET     | `/api/session`                | Creates an ephemeral OpenAI **real-time** session token.     |
+
+---
+
+## Examples
+
+### 1. Chat
+
+<Tabs items={["cURL", "JavaScript (fetch)"]}>
+  <div>
+    ```bash
+    curl -X POST \
+      -H "Content-Type: application/json" \
+      -d '{
+            "messages": [
+              {"role": "user", "content": "Give me a TL;DR of the latest news"}
+        ]}' \
+      http://localhost:3000/api/chat
+    ```
+    The endpoint returns a **Server-Sent Event** (SSE) stream. Read it chunk-by-chunk for real-time updates.
+    ```
+    data: {"id":"chatcmpl…","choices":[{"delta":{"content":"Sure!"}}]}
+    ```
+  </div>
+  <div>
+    ```ts
+    const res = await fetch('/api/chat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ messages }),
+    });
+    // Create a reader for the ReadableStream and process chunks
+    const reader = res.body?.getReader();
+    // …
+    ```
+  </div>
+</Tabs>
+
+---
+
+### 2. Article search
+
+```bash
+curl "http://localhost:3000/api/articles/search?query=typescript%203.5"
+```
+
+Response (truncated):
+
+```json
+[
+  {
+    "id": "getting-started-with-ts",
+    "score": 0.92,
+    "title": "Getting started with TypeScript 3.5"
+  }
+]
+```
+
+---
+
+## Versioning
+
+The API is **currently experimental** – expect breaking changes while the project is <span style={{fontWeight:600}}>0.x</span>.  
+Pin your client to a specific commit hash if stability is critical.
+
+---
+
+<Callout type="warning">
+  Never expose your **OpenAI API key** in client-side code – always call the
+  serverless routes instead.
+</Callout>
diff --git a/src/content/reference/components.mdx b/src/content/reference/components.mdx
new file mode 100644
index 0000000..dc552f7
--- /dev/null
+++ b/src/content/reference/components.mdx
@@ -0,0 +1,65 @@
+---
+title: "Components"
+description: "Catalogue of reusable React components available in the project."
+---
+
+import { Callout, Tabs } from "nextra/components";
+
+# Components
+
+The <code>components/</code> directory gathers reusable UI building blocks ranging from simple **buttons** to fully-fledged **charts** and **chat widgets**. They are written in **TypeScript**, follow the [Radix UI accessibility](https://www.radix-ui.com/) guidelines and ship with zero client-side CSS by default thanks to Tailwind CSS.
+
+<Callout type="info">
+  Below is a curated list of the most frequently used components. For the full
+  source open the corresponding file in your editor.
+</Callout>
+
+| Name                  | Path                               | Purpose                                                   |
+| --------------------- | ---------------------------------- | --------------------------------------------------------- |
+| **Button**            | `components/ui/button.tsx`         | Base button with variants (`primary`, `ghost`, …)         |
+| **Card**              | `components/ui/card.tsx`           | Wrapper with shadow, border & padding                     |
+| **Accordion**         | `components/ui/accordion.tsx`      | Collapse / expand sections                                |
+| **Chart**             | `components/charts/*`              | Thin wrappers around [visx](https://airbnb.io/visx/) & D3 |
+| **Chat Widget**       | `components/chat/chat-widget.tsx`  | Streaming AI chat with tool calls                         |
+| **Solar Panel Scene** | `components/solar-panel/scene.tsx` | 3D canvas demo powered by Three.js                        |
+
+---
+
+## Usage example
+
+<Tabs items={["tsx"]}>
+  <div>
+    ```tsx filename="app/example/page.tsx"
+    import { Button } from '@/components/ui/button'
+
+    export default function Example() {
+      return (
+        <Button variant="primary" onClick={() => alert('Hello!')}>
+          Click me
+        </Button>
+      )
+    }
+    ```
+
+  </div>
+</Tabs>
+
+---
+
+## Customising
+
+Every component exposes a **Tailwind `className` prop** so you can extend or override styles inline:
+
+```tsx
+<Card className="bg-sky-50 dark:bg-sky-900" />
+```
+
+If you need a brand-new component follow this checklist:
+
+1. Create the file inside `components/` (or a sub-folder).
+2. Write it in **TypeScript** – insist on explicit props.
+3. Add a **Storybook story** (if present) or screenshot to help reviewers.
+
+---
+
+Happy building! 🔨
diff --git a/src/content/reference/index.mdx b/src/content/reference/index.mdx
new file mode 100644
index 0000000..c8e0bc1
--- /dev/null
+++ b/src/content/reference/index.mdx
@@ -0,0 +1,14 @@
+---
+title: "Reference"
+description: "Deep-dive technical reference for APIs and UI components."
+asIndexPage: true
+---
+
+# Reference
+
+Choose a topic from the sidebar:
+
+• **API** – HTTP endpoints exposed under `/api/*`  
+• **Components** – React building blocks in `components/`
+
+For practical, step-by-step instructions head over to the **Guides** section.