docs(sqlite-studio): bootstrap docs app

AGENTS.md

@@ -0,0 +1,21 @@
+# Docs Maintenance Guide
+Use this file as the handoff checklist for future edits to this documentation PR.
+## Source Layout
+- The docs source lives in `apps/docs`.
+- `docs.json` is the Docs Cloud configuration for publishing, previews, and content roots.
+- Keep every page grounded in README content, package metadata, source exports, CLI help, environment examples, or existing docs.
+## Docs Routes
+- /docs - Introduction
+- /docs/installation - Installation
+- /docs/quickstart - Quickstart
+- /docs/configuration - Configuration
+- /docs/databases - Databases
+- /docs/features - Features
+## Editing Guidelines
+- Prefer reader-facing setup, usage, and troubleshooting notes over source inventories.
+- Do not add commands, flags, environment variables, routes, imports, or framework names unless they are present in the repository.
+- If you add or rename a page, keep its frontmatter title and description accurate and make sure the navigation ordering still includes it.
+- Avoid analyzer language such as generated from, source evidence, implementation map, source surface, or detected in files.
+## Verification
+- Build the docs site with `cd apps/docs && node ./scripts/docs-cloud-vercel.mjs install && node ./scripts/docs-cloud-vercel.mjs build` before handing off a docs PR.
+- Open `/docs` and at least one generated leaf page to confirm the sidebar and page content match the PR.

apps/docs/.gitignore

@@ -0,0 +1,14 @@
+node_modules
+.env*
+!.env.example
+.next
+.nuxt
+.output
+.svelte-kit
+.astro
+dist
+build
+.vercel
+app/api/docs
+app/docs/layout.tsx
+mdx-components.tsx

apps/docs/app/docs/configuration/page.mdx

@@ -0,0 +1,69 @@
+---
+title: "Configuration"
+description: "Global CLI options, environment variables, and deployment configuration."
+order: 0
+---
+
+# Configuration
+
+SQL Studio is configured entirely through CLI flags and environment variables — there is no configuration file. Global options must be placed **before** the subcommand name.
+
+```bash
+sql-studio [OPTIONS] <SUBCOMMAND> [ARGS...]
+```
+
+## Global Options
+
+| Option | Short | Description | Default | Env Var |
+|--------|-------|-------------|---------|---------|
+| `--address` | `-a` | Address and port to bind to | `127.0.0.1:3030` | `ADDRESS` |
+| `--timeout` | `-t` | Timeout for queries from the Query page | `5secs` | `TIMEOUT` |
+| `--base-path` | `-b` | Base URL path for the UI (e.g. `/sql-studio`) | _(none)_ | `BASE_PATH` |
+| `--no-browser` | | Don't open a browser window on startup | `false` | `NO_BROWSER` |
+| `--no-shutdown` | | Hide the shutdown button in the UI | `false` | `NO_SHUTDOWN` |
+
+Each option has a corresponding environment variable, so you can configure SQL Studio without passing flags every time.
+
+## Timeout Format
+
+The `--timeout` value accepts human-readable durations. Examples: `5secs`, `30secs`, `1min`, `2min 30secs`. Use longer values when querying large datasets on slow connections.
+
+## Environment Variables
+
+You can set any option via its environment variable instead of a flag:
+
+```bash
+ADDRESS=0.0.0.0:8080
+TIMEOUT=30secs
+NO_BROWSER=true
+NO_SHUTDOWN=true
+BASE_PATH=/sql-studio
+```
+
+The `RUST_LOG` variable controls server-side log verbosity. Set it to `debug` or `info` to see request logs:
+
+```bash
+RUST_LOG=info
+```
+
+## Examples
+
+Bind to all interfaces on port 8080 without opening a browser:
+
+```bash
+sql-studio --address 0.0.0.0:8080 --no-browser sqlite ./app.db
+```
+
+Serve the UI under a sub-path (useful behind a reverse proxy):
+
+```bash
+sql-studio --base-path /sql-studio postgres postgres://localhost:5432/mydb
+```
+
+Raise the query timeout for heavy analytical queries:
+
+```bash
+sql-studio --timeout 60secs duckdb ./warehouse.duckdb
+```
+
+> **Note:** Options like `--no-browser` and `--no-shutdown` are particularly useful when running SQL Studio in Docker or behind a reverse proxy. See [Installation](/docs/installation) for the recommended Docker invocation.

apps/docs/app/docs/databases/page.mdx

@@ -0,0 +1,32 @@
+---
+title: "Databases"
+description: "Overview of all databases supported by SQL Studio."
+order: 1
+---
+
+# Databases
+
+SQL Studio supports a wide range of databases and file formats. Each has its own subcommand with specific connection arguments. Global options like `--address` and `--timeout` go before the subcommand; connection arguments go after.
+
+```bash
+sql-studio [OPTIONS] <SUBCOMMAND> [ARGS...]
+```
+
+## Supported Databases
+
+| Database | Subcommand | Type |
+|----------|------------|------|
+| SQLite | `sqlite` | Local file |
+| libSQL | `libsql` | Remote server |
+| Local libSQL | `local-libsql` | Local file (libSQL driver) |
+| PostgreSQL | `postgres` | Remote server |
+| MySQL / MariaDB | `mysql` | Remote server |
+| DuckDB | `duckdb` | Local file |
+| Parquet | `parquet` | Local file |
+| CSV | `csv` | Local file |
+| ClickHouse | `clickhouse` | Remote server |
+| Microsoft SQL Server | `mssql` | Remote server |
+
+> **Note:** DuckDB, Parquet, and CSV are not available in the `musl` static Linux build. Use the glibc Linux build, macOS, or Windows for those subcommands.
+
+See [Configuration](/docs/configuration) for the global options that apply to every subcommand.

apps/docs/app/docs/features/page.mdx

@@ -0,0 +1,19 @@
+---
+title: "Features"
+description: "Explore the SQL Studio user interface."
+order: 12
+---
+
+# Features
+
+SQL Studio provides four main UI pages, all accessible from the left sidebar once the server is running. Every page works against any supported database — the same UI surfaces whether you're browsing a SQLite file, a PostgreSQL server, or a Parquet dataset.
+
+## Pages
+
+**Overview Dashboard** is the landing page. It shows database metadata — file name, version, size, creation and modification timestamps — plus summary statistics (table count, index count, trigger count, view count) and bar charts that break row counts and column counts down per table.
+
+**Table Explorer** lists every table in the sidebar with its row count. Selecting a table shows metadata cards, the `CREATE TABLE` statement, and a data grid that loads rows on demand via infinite scroll.
+
+**Query Editor** gives you a full Monaco editor (the same engine as VS Code) with SQL syntax highlighting and IntelliSense autocomplete powered by your live database schema. Write your query and run it to see paginated results.
+
+**ERD Viewer** renders an interactive entity-relationship diagram with tables as nodes, columns annotated with types and constraints, and foreign-key edges connecting related tables. You can pan, zoom, and drag nodes to rearrange the layout.

apps/docs/app/docs/installation/page.mdx

@@ -0,0 +1,70 @@
+---
+title: "Installation"
+description: "Install and configure SQL Studio."
+order: 10
+---
+
+# Installation
+
+SQL Studio ships as a self-contained binary with no runtime dependencies. Pick the method that suits your platform.
+
+## Shell Script (macOS and Linux)
+
+The fastest way to get the latest release:
+
+```bash
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/frectonz/sql-studio/releases/download/0.1.51/sql-studio-installer.sh | sh
+```
+
+After the script completes, `sql-studio` is on your `PATH` and ready to use.
+
+## PowerShell (Windows)
+
+Open a PowerShell terminal and run the installer from the same releases page. The installer places the binary in a location already on your `PATH`.
+
+## Nix
+
+SQL Studio is available in Nixpkgs. Add it to your environment or run it directly with `nix run`.
+
+## Docker
+
+A Docker image is published on Docker Hub as `frectonz/sql-studio`. The recommended flags when running in a container are `--no-browser` (no desktop browser inside a container), `--no-shutdown` (keep the server alive), and `--address=0.0.0.0:3030` (bind to all interfaces so the host can reach it):
+
+```bash
+docker run -p 3030:3030 frectonz/sql-studio /bin/sql-studio \
+  --no-browser \
+  --no-shutdown \
+  --address=0.0.0.0:3030 \
+  postgres \
+  postgres://localhost:5432/mydb
+```
+
+## Building from Source
+
+You need Rust (via `cargo`) and Node.js installed. The UI is compiled separately and then embedded in the Rust binary at build time.
+
+```bash
+git clone git@github.com:frectonz/sql-studio.git
+cd sql-studio
+cd ui
+npm install
+npm run build
+cd ..
+cargo build --release
+```
+
+The compiled binary lands at `target/release/sql-studio`.
+
+> **Note:** DuckDB-backed formats (DuckDB, Parquet, CSV) are not available in the `musl` static Linux build due to DuckDB's compatibility requirements. Use the glibc Linux build, macOS, or Windows for those subcommands.
+
+## Updating
+
+If you installed via the shell script or the PowerShell installer, re-run the same install command to pull the latest release. Docker users can `docker pull frectonz/sql-studio` to get the newest image.
+
+Once installed, confirm everything works by running:
+
+```bash
+sql-studio --help
+```
+
+You should see the list of subcommands and global options. From here, jump to the [Quickstart](/docs/quickstart) to launch your first session.

apps/docs/app/docs/page.mdx

@@ -0,0 +1,21 @@
+---
+title: "Introduction"
+description: "Single binary, single command SQL database explorer for SQLite, PostgreSQL, MySQL, DuckDB, ClickHouse, MSSQL, Parquet, CSV, and more."
+order: 0
+---
+
+# Introduction
+
+SQL Studio is a single-binary, single-command web-based SQL database explorer. Point it at any supported database and you instantly get a rich browser UI for browsing schemas, exploring tables, running queries, and visualizing relationships — no configuration files, no installation wizards, no daemon to manage.
+
+The entire UI is statically embedded in the binary. You run one command, a browser window opens, and you're looking at your data. When you're done, click the shutdown button or press `Ctrl+C`.
+
+SQL Studio supports SQLite, libSQL (Turso), PostgreSQL, MySQL/MariaDB, DuckDB, ClickHouse, Microsoft SQL Server, Parquet files, and CSV files. Every database has its own subcommand:
+
+```bash
+sql-studio sqlite my-database.db
+sql-studio postgres postgres://localhost:5432/mydb
+sql-studio parquet data.parquet
+```
+
+If you're ready to install, head to [Installation](/docs/installation). To run SQL Studio for the first time in under a minute, see the [Quickstart](/docs/quickstart). Once it's running, the [Features](/docs/features) section explains every UI page. To connect a specific database, the [Databases](/docs/databases) section has a dedicated page for each supported engine.

apps/docs/app/docs/quickstart/page.mdx

@@ -0,0 +1,50 @@
+---
+title: "Quickstart"
+description: "Run SQL Studio for the first time."
+order: 20
+---
+
+# Quickstart
+
+SQL Studio ships with a built-in sample SQLite database so you can try the full UI without any setup. Install the binary (see [Installation](/docs/installation)), then run:
+
+```bash
+sql-studio sqlite preview
+```
+
+This launches SQL Studio against a built-in sample database and opens `http://127.0.0.1:3030` in your default browser. You'll land on the Overview page with database metadata, table counts, and row-count bar charts — no file required.
+
+## Use Your Own Database
+
+Point SQL Studio at a local SQLite file you already have:
+
+```bash
+sql-studio sqlite ./my-app.db
+```
+
+Or connect to a running PostgreSQL server:
+
+```bash
+sql-studio postgres postgres://localhost:5432/mydb
+```
+
+The subcommand determines the driver. Every other supported database works the same way — see [Databases](/docs/databases) for the full list and connection string formats.
+
+## What You'll See
+
+Once the browser opens you'll find four pages in the left sidebar:
+
+- **Overview** — database name, version, size, and summary statistics
+- **Tables** — row counts, column definitions, creation SQL, and an infinite-scroll data grid for every table
+- **Query** — a Monaco-powered SQL editor with IntelliSense autocomplete backed by your live schema
+- **Schema** — an interactive ERD diagram showing tables, columns, and foreign-key relationships
+
+## Controlling the Server
+
+By default SQL Studio binds to `127.0.0.1:3030` and opens a browser window automatically. You can change this with global flags placed *before* the subcommand:
+
+```bash
+sql-studio --address 0.0.0.0:8080 --no-browser sqlite ./my-app.db
+```
+
+See [Configuration](/docs/configuration) for the full list of options and their equivalent environment variables.

apps/docs/app/global.css

@@ -0,0 +1,2 @@
+@import "tailwindcss";
+@import "@farming-labs/theme/colorful/css";

apps/docs/app/layout.tsx

@@ -0,0 +1,33 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import { RootProvider } from "@farming-labs/theme";
+import docsConfig from "../docs.config";
+import "./global.css";
+
+const geistSans = Geist({
+  variable: "--fd-font-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--fd-font-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: {
+    default: "Docs",
+    template: docsConfig.metadata?.titleTemplate ?? "%s",
+  },
+  description: docsConfig.metadata?.description,
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className={`${geistSans.variable} ${geistMono.variable} font-sans antialiased`}>
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}

apps/docs/app/page.tsx

@@ -0,0 +1,14 @@
+import Link from "next/link";
+
+const title = "SQL Studio";
+const description = "Single binary, single command SQL database explorer for SQLite, PostgreSQL, MySQL, DuckDB, ClickHouse, MSSQL, Parquet, CSV, and more.";
+
+export default function HomePage() {
+  return (
+    <main style={{ padding: 32 }}>
+      <h1>{title}</h1>
+      <p>{description}</p>
+      <Link href="/docs">Open docs</Link>
+    </main>
+  );
+}

apps/docs/docs.config.tsx

@@ -0,0 +1,28 @@
+import { defineDocs } from "@farming-labs/docs";
+import { colorful } from "@farming-labs/theme/colorful";
+
+export default defineDocs({
+  entry: "docs",
+  theme: colorful(),
+  ordering: [
+    {
+      "slug": "quickstart"
+    },
+    {
+      "slug": "installation"
+    },
+    {
+      "slug": "configuration"
+    },
+    {
+      "slug": "databases"
+    },
+    {
+      "slug": "features"
+    }
+  ],
+  metadata: {
+    titleTemplate: "%s – Docs",
+    description: "Generated by @farming-labs/docs Cloud",
+  },
+});

apps/docs/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.