diff --git a/README.md b/README.md
new file mode 100644
index 00000000..0b0490c2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,92 @@
+# Chronicle
+
+Config-driven documentation framework built on Next.js, Fumadocs, and Apsara UI.
+
+## Features
+
+- **Config-driven** — Single `chronicle.yaml` for all site configuration
+- **Themeable** — Built-in themes: `default` (sidebar + TOC) and `paper` (book-style)
+- **MDX** — Write docs in MDX with callouts, tabs, mermaid diagrams, and syntax highlighting
+- **API docs** — Interactive OpenAPI documentation with "Try it out" panel
+- **LLMs** — Auto-generate `/llms.txt` and `/llms-full.txt` for AI consumption
+- **CLI** — `init`, `dev`, `build`, `start`, `serve` commands
+
+## Quick Start
+
+### Install
+
+```bash
+bun add @raystack/chronicle
+```
+
+Or run directly without installing:
+
+```bash
+bunx @raystack/chronicle init
+```
+
+### Initialize
+
+```bash
+chronicle init
+```
+
+Creates a `chronicle.yaml` and sample `index.mdx`.
+
+### Develop
+
+```bash
+chronicle dev
+```
+
+Open [http://localhost:3000](http://localhost:3000).
+
+### Build for production
+
+```bash
+chronicle build
+chronicle start
+```
+
+## Contributing
+
+We welcome contributions! Here's how to get started:
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) >= 22
+- [Bun](https://bun.sh/) >= 1.3
+
+### Running Locally
+
+1. Fork and clone the repository
+
+```bash
+git clone https://github.com/<your-username>/chronicle.git
+cd chronicle
+```
+
+2. Install dependencies
+
+```bash
+bun install
+```
+
+3. Run the dev server
+
+```bash
+cd docs && bun ../packages/chronicle/bin/chronicle.js dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) to see the docs site.
+
+### Making Changes
+
+1. Create a branch from `main`
+2. Make your changes
+3. Test locally from the `docs/` directory
+4. Open a pull request
+
+## License
+
+[Apache-2.0](LICENSE)
diff --git a/docs/chronicle.yaml b/docs/chronicle.yaml
new file mode 100644
index 00000000..c955c5c5
--- /dev/null
+++ b/docs/chronicle.yaml
@@ -0,0 +1,23 @@
+title: Chronicle
+description: Config-driven documentation framework
+
+theme:
+  name: paper
+
+navigation:
+  links:
+    - label: GitHub
+      href: https://github.com/raystack/chronicle
+
+search:
+  enabled: true
+  placeholder: Search docs...
+
+llms:
+  enabled: true
+
+footer:
+  copyright: "© 2026 Raystack. All rights reserved."
+  links:
+    - label: GitHub
+      href: https://github.com/raystack/chronicle
diff --git a/docs/cli.mdx b/docs/cli.mdx
new file mode 100644
index 00000000..74b8d9b7
--- /dev/null
+++ b/docs/cli.mdx
@@ -0,0 +1,84 @@
+---
+title: CLI Commands
+description: Chronicle CLI commands reference.
+order: 2
+---
+
+# CLI Commands
+
+Chronicle provides a CLI to initialize, develop, build, and serve your documentation site.
+
+## init
+
+Scaffold a new Chronicle project.
+
+```bash
+chronicle init [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-d, --dir <path>` | Target directory | `.` (current directory) |
+
+Creates a `chronicle.yaml` config file and a sample `index.mdx` in the specified directory.
+
+## dev
+
+Start the development server with hot reload.
+
+```bash
+chronicle dev [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --port <port>` | Port number | `3000` |
+| `-c, --content <path>` | Content directory | Current directory |
+
+## build
+
+Build the site for production.
+
+```bash
+chronicle build [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-c, --content <path>` | Content directory | Current directory |
+
+## start
+
+Start the production server. Requires a prior `chronicle build`.
+
+```bash
+chronicle start [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --port <port>` | Port number | `3000` |
+| `-c, --content <path>` | Content directory | Current directory |
+
+## serve
+
+Build and start the production server in one step.
+
+```bash
+chronicle serve [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --port <port>` | Port number | `3000` |
+| `-c, --content <path>` | Content directory | Current directory |
+
+## Content Directory Resolution
+
+The content directory is resolved in this order:
+
+1. `--content` CLI flag (highest priority)
+2. `CHRONICLE_CONTENT_DIR` environment variable
+3. Current working directory (default)
+
+The content directory must contain a `chronicle.yaml` file.
diff --git a/docs/components.mdx b/docs/components.mdx
new file mode 100644
index 00000000..11d2622d
--- /dev/null
+++ b/docs/components.mdx
@@ -0,0 +1,213 @@
+---
+title: Components
+description: MDX components and admonitions supported in Chronicle.
+order: 6
+---
+
+# Components
+
+Chronicle provides built-in MDX components that enhance standard markdown with interactive elements and styled content.
+
+## Callout
+
+Callouts highlight important information with colored boxes.
+
+### Directive Syntax
+
+Use `:::` fenced directives in your MDX files:
+
+```mdx
+:::note
+This is a note callout.
+:::
+
+:::tip
+Helpful tip for users.
+:::
+
+:::warning
+Be careful with this operation.
+:::
+
+:::danger
+This action is irreversible.
+:::
+
+:::success
+Operation completed successfully.
+:::
+```
+
+### Directive Types
+
+| Directive | Callout Type | Color |
+|-----------|-------------|-------|
+| `:::note` | `accent` | Blue |
+| `:::tip` | `accent` | Blue |
+| `:::info` | `accent` | Blue |
+| `:::warn` | `attention` | Yellow |
+| `:::warning` | `attention` | Yellow |
+| `:::danger` | `alert` | Red |
+| `:::caution` | `alert` | Red |
+| `:::success` | `success` | Green |
+
+### JSX Syntax
+
+For more control, use the `Callout` component directly:
+
+````mdx
+<Callout type="accent">
+  <CalloutTitle>Note</CalloutTitle>
+  <CalloutDescription>This is a custom callout with title and description.</CalloutDescription>
+</Callout>
+````
+
+**Callout Props**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'accent' \| 'attention' \| 'alert' \| 'success' \| 'grey'` | `'grey'` | Callout color variant |
+| `outline` | `boolean` | `false` | Use outline style |
+| `width` | `string` | — | Custom width |
+| `className` | `string` | — | Additional CSS class |
+
+## Tabs
+
+Tabbed content panels using Apsara's `Tabs` component.
+
+````mdx
+<Tabs defaultValue="npm">
+  <Tabs.List>
+    <Tabs.Trigger value="npm">npm</Tabs.Trigger>
+    <Tabs.Trigger value="bun">bun</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="npm">
+
+    ```bash
+    npm install @raystack/chronicle
+    ```
+
+  </Tabs.Content>
+  <Tabs.Content value="bun">
+
+    ```bash
+    bun add @raystack/chronicle
+    ```
+
+  </Tabs.Content>
+</Tabs>
+````
+
+## Mermaid Diagrams
+
+Render diagrams using Mermaid syntax in fenced code blocks:
+
+````mdx
+```mermaid
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action]
+    B -->|No| D[End]
+```
+````
+
+Mermaid is loaded dynamically on the client side. Supports all standard Mermaid diagram types: flowcharts, sequence diagrams, class diagrams, state diagrams, etc.
+
+## Code Blocks
+
+Fenced code blocks are syntax-highlighted using Shiki.
+
+````mdx
+```typescript
+function hello(name: string): string {
+  return `Hello, ${name}!`
+}
+```
+````
+
+### Code Block Title
+
+Add a title to code blocks:
+
+````mdx
+```typescript title="hello.ts"
+function hello(name: string): string {
+  return `Hello, ${name}!`
+}
+```
+````
+
+## Tables
+
+Standard markdown tables are rendered with Apsara styling:
+
+```mdx
+| Column A | Column B | Column C |
+|----------|----------|----------|
+| Cell 1   | Cell 2   | Cell 3   |
+| Cell 4   | Cell 5   | Cell 6   |
+```
+
+## Images
+
+Images support both local and external sources:
+
+```mdx
+![Alt text](./screenshot.png)
+
+![External image](https://example.com/image.png)
+```
+
+- **Local images** — Rendered with Next.js `Image` component (optimized, default 800x400)
+- **External images** — Rendered with standard `<img>` tag
+
+## Links
+
+Links are automatically handled:
+
+```mdx
+[Internal link](/docs/configuration)
+[External link](https://github.com)
+[Anchor link](#section)
+```
+
+- **Internal links** — Use Next.js client-side navigation
+- **External links** — Open in a new tab automatically
+- **Anchor links** — Smooth scroll to the section
+
+## Details / Collapsible
+
+Collapsible content sections:
+
+````mdx
+<details>
+  <summary>Click to expand</summary>
+
+  Hidden content goes here. Supports full markdown inside.
+
+</details>
+````
+
+## Blockquotes
+
+Standard blockquotes render as grey callouts:
+
+```mdx
+> This is a blockquote rendered as a callout.
+```
+
+## HTML Tag Overrides
+
+Chronicle overrides these HTML elements with styled components:
+
+| HTML Element | Chronicle Component | Notes |
+|-------------|-------------------|-------|
+| `<p>` | `MdxParagraph` | Auto-converts to `<div>` when containing block elements |
+| `<img>` | `Image` | Next.js optimized for local, standard for external |
+| `<a>` | `Link` | Smart routing with external link detection |
+| `<code>` | `MdxCode` | Inline code styling |
+| `<pre>` | `MdxPre` | Code blocks with optional title header |
+| `<table>` | `MdxTable` | Apsara Table component |
+| `<blockquote>` | `MdxBlockquote` | Rendered as grey Callout |
+| `<details>` | `MdxDetails` | Collapsible sections |
+| `<summary>` | `MdxSummary` | Collapsible section header |
diff --git a/docs/configuration.mdx b/docs/configuration.mdx
new file mode 100644
index 00000000..789d0119
--- /dev/null
+++ b/docs/configuration.mdx
@@ -0,0 +1,217 @@
+---
+title: Configuration
+description: Full chronicle.yaml configuration reference.
+order: 3
+---
+
+# Configuration
+
+All site configuration lives in a single `chronicle.yaml` file in your content directory.
+
+## Full Example
+
+```yaml
+title: My Project Docs
+description: Documentation for My Project
+
+logo:
+  light: ./logo-light.png
+  dark: ./logo-dark.png
+
+theme:
+  name: default
+
+navigation:
+  links:
+    - label: GitHub
+      href: https://github.com/myorg/myproject
+    - label: Blog
+      href: https://blog.example.com
+
+search:
+  enabled: true
+  placeholder: Search docs...
+
+footer:
+  copyright: "© 2026 My Company"
+  links:
+    - label: GitHub
+      href: https://github.com/myorg/myproject
+    - label: License
+      href: /license
+
+api:
+  - name: REST API
+    spec: ./openapi.yaml
+    basePath: /apis
+    server:
+      url: https://api.example.com
+      description: Production Server
+    auth:
+      type: apiKey
+      header: Authorization
+      placeholder: "Bearer token"
+```
+
+## Reference
+
+### title
+
+**Required.** The site title displayed in the navbar and browser tab.
+
+```yaml
+title: My Documentation
+```
+
+### description
+
+Optional meta description for SEO.
+
+```yaml
+description: Documentation powered by Chronicle
+```
+
+### logo
+
+Logo configuration with theme-aware variants.
+
+```yaml
+logo:
+  light: ./logo-light.png
+  dark: ./logo-dark.png
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `light` | `string` | Logo path or URL for light theme |
+| `dark` | `string` | Logo path or URL for dark theme |
+
+### theme
+
+Theme selection and customization.
+
+```yaml
+theme:
+  name: default
+```
+
+| Field | Type | Description | Default |
+|-------|------|-------------|---------|
+| `name` | `'default' \| 'paper'` | Theme to use | `default` |
+| `colors` | `Record<string, string>` | Custom color overrides | — |
+
+See [Themes](/docs/themes) for details on each theme.
+
+### navigation
+
+Top navbar links and social icons.
+
+```yaml
+navigation:
+  links:
+    - label: GitHub
+      href: https://github.com/myorg/myproject
+    - label: API
+      href: /apis
+  social:
+    - type: github
+      href: https://github.com/myorg/myproject
+    - type: discord
+      href: https://discord.gg/example
+```
+
+**navigation.links**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `label` | `string` | Link text |
+| `href` | `string` | URL (internal or external) |
+
+**navigation.social**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `string` | Icon type: `github`, `twitter`, `discord`, or custom |
+| `href` | `string` | URL |
+
+### search
+
+Search functionality powered by Fumadocs.
+
+```yaml
+search:
+  enabled: true
+  placeholder: Search documentation...
+```
+
+| Field | Type | Description | Default |
+|-------|------|-------------|---------|
+| `enabled` | `boolean` | Enable/disable search | `true` |
+| `placeholder` | `string` | Search input placeholder | `Search...` |
+
+When enabled, search is accessible via the navbar button or keyboard shortcut `Cmd+K` / `Ctrl+K`.
+
+### footer
+
+Footer content displayed at the bottom of every page.
+
+```yaml
+footer:
+  copyright: "© 2026 My Company. All rights reserved."
+  links:
+    - label: Terms
+      href: /terms
+    - label: Privacy
+      href: /privacy
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `copyright` | `string` | Copyright text (left-aligned) |
+| `links` | `NavLink[]` | Footer links (right-aligned) |
+
+### api
+
+OpenAPI specification configuration for interactive API documentation.
+
+```yaml
+api:
+  - name: Petstore API
+    spec: ./petstore.yaml
+    basePath: /apis
+    server:
+      url: https://petstore.swagger.io/v2
+      description: Production Server
+    auth:
+      type: apiKey
+      header: api_key
+      placeholder: Enter your API key
+```
+
+Each entry in the `api` array creates a section of API documentation.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | API display name |
+| `spec` | `string` | Path to OpenAPI spec file (JSON or YAML), relative to `chronicle.yaml` |
+| `basePath` | `string` | URL path prefix for API pages (e.g., `/apis`) |
+| `server.url` | `string` | Base URL for the API server |
+| `server.description` | `string` | Server description |
+| `auth.type` | `string` | Authentication type (e.g., `apiKey`, `bearer`) |
+| `auth.header` | `string` | Header name for auth token |
+| `auth.placeholder` | `string` | Placeholder text in auth input |
+
+API pages include a "Try it out" panel that uses the configured server URL and auth settings.
+
+## Defaults
+
+If `chronicle.yaml` is missing or fields are omitted, these defaults apply:
+
+```yaml
+title: Documentation
+theme:
+  name: default
+search:
+  enabled: true
+  placeholder: Search...
+```
diff --git a/docs/docker.mdx b/docs/docker.mdx
new file mode 100644
index 00000000..03d3defb
--- /dev/null
+++ b/docs/docker.mdx
@@ -0,0 +1,66 @@
+---
+title: Docker
+description: Run Chronicle with Docker.
+order: 8
+---
+
+# Docker
+
+Chronicle is available as a Docker image on [Docker Hub](https://hub.docker.com/r/raystack/chronicle).
+
+## Pull the Image
+
+```bash
+docker pull raystack/chronicle
+```
+
+## Production Server
+
+The default command builds and starts a production server on port 3000.
+
+```bash
+docker run -p 3000:3000 -v ./content:/app/content raystack/chronicle
+```
+
+Mount your content directory (containing `chronicle.yaml` and MDX files) to `/app/content`.
+
+## Development Server
+
+Override the default command with `dev` for hot reload:
+
+```bash
+docker run -p 3000:3000 -v ./content:/app/content raystack/chronicle dev --port 3000
+```
+
+## Custom Port
+
+```bash
+docker run -p 8080:8080 -v ./content:/app/content raystack/chronicle serve --port 8080
+```
+
+## Docker Compose
+
+```yaml
+services:
+  docs:
+    image: raystack/chronicle
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./content:/app/content
+```
+
+## Available Commands
+
+The entrypoint is `chronicle`, so any CLI command can be passed:
+
+```bash
+# Build only
+docker run -v ./content:/app/content raystack/chronicle build
+
+# Start pre-built server
+docker run -p 3000:3000 -v ./content:/app/content raystack/chronicle start --port 3000
+
+# Build and start (default)
+docker run -p 3000:3000 -v ./content:/app/content raystack/chronicle serve --port 3000
+```
diff --git a/docs/frontmatter.mdx b/docs/frontmatter.mdx
new file mode 100644
index 00000000..ad4abb6f
--- /dev/null
+++ b/docs/frontmatter.mdx
@@ -0,0 +1,115 @@
+---
+title: Frontmatter
+description: Page-level metadata options for MDX files.
+order: 4
+---
+
+# Frontmatter
+
+Every MDX file supports YAML frontmatter at the top of the file for page-level configuration.
+
+## Example
+
+```mdx
+---
+title: Getting Started
+description: A quick guide to set up your project
+order: 2
+icon: rectangle-stack
+---
+
+# Getting Started
+
+Your content here...
+```
+
+## Fields
+
+### title
+
+**Required.** The page title used in navigation, browser tab, and page heading.
+
+```yaml
+title: Installation Guide
+```
+
+### description
+
+Optional meta description for the page. Used in SEO metadata.
+
+```yaml
+description: Step-by-step installation instructions
+```
+
+### order
+
+Controls the page's position in sidebar navigation. Lower numbers appear first.
+
+```yaml
+order: 1
+```
+
+**Decimal ordering** is supported for inserting pages between existing ones:
+
+```yaml
+# Page A: order 1
+# New page: order 1.5 (appears between A and B)
+# Page B: order 2
+```
+
+Pages without an `order` value appear after ordered pages.
+
+### icon
+
+Icon identifier displayed next to the page title in the sidebar.
+
+```yaml
+icon: rectangle-stack
+```
+
+**Available icons:**
+
+| Value | Description |
+|-------|-------------|
+| `rectangle-stack` | Rectangle stack icon |
+| `method-get` | HTTP GET badge |
+| `method-post` | HTTP POST badge |
+| `method-put` | HTTP PUT badge |
+| `method-delete` | HTTP DELETE badge |
+| `method-patch` | HTTP PATCH badge |
+
+## Navigation Ordering
+
+Sidebar navigation is determined by:
+
+1. **Frontmatter `order`** — Pages sorted by `order` value (ascending)
+2. **Decimal values** — Use `1`, `1.5`, `2` for fine-grained positioning
+3. **Folders** — Directories become collapsible groups, auto-named from the folder name (capitalized)
+4. **No `meta.json` required** — Ordering is entirely frontmatter-based
+
+### Example structure
+
+```
+content/
+├── index.mdx          # order: 1
+├── quickstart.mdx     # order: 2
+├── guides/
+│   ├── setup.mdx      # order: 1
+│   └── advanced.mdx   # order: 2
+└── reference/
+    ├── cli.mdx        # order: 1
+    └── config.mdx     # order: 2
+```
+
+This produces sidebar navigation:
+
+```
+Home (order: 1)
+Quickstart (order: 2)
+▸ Guides
+    Setup (order: 1)
+    Advanced (order: 2)
+▸ Reference
+    CLI (order: 1)
+    Config (order: 2)
+```
diff --git a/docs/index.mdx b/docs/index.mdx
new file mode 100644
index 00000000..c02a3284
--- /dev/null
+++ b/docs/index.mdx
@@ -0,0 +1,84 @@
+---
+title: Getting Started
+description: Install and set up Chronicle, a config-driven documentation framework.
+order: 1
+---
+
+# Getting Started
+
+Chronicle is a config-driven documentation framework built on Next.js 15, Fumadocs, and Apsara UI components. Write MDX content, configure with a single YAML file, and get a fully themed documentation site.
+
+## Installation
+
+```bash
+bun add @raystack/chronicle
+```
+
+## Quick Start
+
+### 1. Initialize a new project
+
+```bash
+chronicle init
+```
+
+This creates:
+- `chronicle.yaml` — your site configuration
+- `index.mdx` — a sample documentation page
+
+### 2. Start the development server
+
+```bash
+chronicle dev
+```
+
+Your docs site is now running at [http://localhost:3000](http://localhost:3000).
+
+### 3. Add content
+
+Create `.mdx` files in your content directory. Each file becomes a page. Use folders to create nested navigation.
+
+```
+content/
+├── chronicle.yaml
+├── index.mdx
+├── getting-started.mdx
+└── guides/
+    ├── installation.mdx
+    └── configuration.mdx
+```
+
+### 4. Build for production
+
+```bash
+chronicle build
+chronicle start
+```
+
+Or use the combined command:
+
+```bash
+chronicle serve
+```
+
+## Project Structure
+
+A minimal Chronicle project looks like:
+
+```
+my-docs/
+├── chronicle.yaml      # Site configuration
+├── index.mdx           # Home page
+└── guides/
+    └── setup.mdx       # Nested page at /guides/setup
+```
+
+All configuration is done through `chronicle.yaml`. No additional config files needed.
+
+## Next Steps
+
+- [CLI Commands](/docs/cli) — All available CLI commands and flags
+- [Configuration](/docs/configuration) — Full `chronicle.yaml` reference
+- [Frontmatter](/docs/frontmatter) — Page-level metadata options
+- [Components](/docs/components) — MDX components and admonitions
+- [Themes](/docs/themes) — Available themes and customization
diff --git a/docs/themes.mdx b/docs/themes.mdx
new file mode 100644
index 00000000..74ab076e
--- /dev/null
+++ b/docs/themes.mdx
@@ -0,0 +1,59 @@
+---
+title: Themes
+description: Available themes and customization options.
+order: 7
+---
+
+# Themes
+
+Chronicle ships with two built-in themes. Set the theme in your `chronicle.yaml`:
+
+```yaml
+theme:
+  name: default
+```
+
+## Default Theme
+
+A traditional documentation layout with three-column design.
+
+```yaml
+theme:
+  name: default
+```
+
+### Layout
+
+- **Left sidebar** — Collapsible navigation tree with page icons
+- **Main content** — Centered content area
+- **Right sidebar** — Table of contents (auto-generated from headings)
+- **Top navbar** — Site title, search button, navigation links, theme toggle
+
+### Features
+
+- Responsive sidebar (collapsible on mobile)
+- Keyboard-accessible search (`Cmd+K` / `Ctrl+K`)
+- Light/dark mode toggle
+- Breadcrumb navigation
+- Active heading tracking in table of contents
+
+## Paper Theme
+
+A book-style layout optimized for long-form reading.
+
+```yaml
+theme:
+  name: paper
+```
+
+### Layout
+
+- **Left sidebar** — Chapter-style navigation
+- **Main content** — Centered content area with reading-optimized width
+- **Reading progress** — Progress indicator for current page
+
+### Features
+
+- Minimal, distraction-free design
+- Reading progress tracking
+- Optimized typography for long content