docs: generate llms.txt from the docs and host it on docs website

docs/docs/api/appkit-ui/styling.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 4
+---
+
+# Styling
+
+This guide covers how to style AppKit UI components using CSS variables and theming.
+
+## CSS import
+
+In your main CSS file, import the AppKit UI styles:
+
+```css
+@import "@databricks/appkit-ui/styles.css";
+```
+
+This provides a default theme for your app using CSS variables.
+
+## Customizing theme
+
+AppKit UI uses CSS variables for theming, supporting both light and dark modes automatically.
+
+### Full variable list
+
+You can customize the theme by overriding CSS variables. See the [CSS variables](https://github.com/databricks/appkit/blob/main/packages/appkit-ui/src/react/styles/globals.css) for the full list of variables.
+
+:::warning Important
+If you change any variable, you must change it for **both light and dark mode** to ensure consistent appearance across color schemes.
+:::
+
+## Color system
+
+AppKit UI uses the OKLCH color space for better perceptual uniformity. The format is:
+
+```
+oklch(lightness chroma hue)
+```
+
+Where:
+- **lightness**: 0-1 (0 = black, 1 = white)
+- **chroma**: 0-0.4 (saturation)
+- **hue**: 0-360 (color angle)
+
+## Semantic color variables
+
+### Core colors
+
+- `--background` / `--foreground` - Main background and text
+- `--card` / `--card-foreground` - Card backgrounds
+- `--popover` / `--popover-foreground` - Popover/dropdown backgrounds
+
+### Interactive colors
+
+- `--primary` / `--primary-foreground` - Primary actions
+- `--secondary` / `--secondary-foreground` - Secondary actions
+- `--muted` / `--muted-foreground` - Muted/disabled states
+- `--accent` / `--accent-foreground` - Accent highlights
+
+### Status colors
+
+- `--destructive` / `--destructive-foreground` - Destructive actions
+- `--success` / `--success-foreground` - Success states
+- `--warning` / `--warning-foreground` - Warning states
+
+### UI elements
+
+- `--border` - Border colors
+- `--input` - Input field borders
+- `--ring` - Focus ring colors
+- `--radius` - Border radius
+
+### Charts
+
+- `--chart-1` through `--chart-5` - Chart color palette
+
+### Sidebar
+
+- `--sidebar-*` - Sidebar-specific colors
+
+## See also
+
+- [API Reference](/docs/api/appkit-ui) - Complete UI components API documentation

docs/docs/app-management.mdx

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 3
+sidebar_position: 2
 ---
 
 import Prerequisites from './_prerequisites.mdx';
@@ -16,12 +16,10 @@ See the [Quick start](./index.md) section to create a new Databricks app with Ap
 
 ## Configuration
 
-Before deploying your app, configure it according to your needs. See the [Databricks Apps Configuration](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/configuration) documentation for details on:
-
-- App configuration file (`app.yaml`)
-- Environment variables
-- Authorization and permissions
-- Networking configuration
+Before deploying your app, you need to configure it. See the [Configuration guide](./configuration.mdx) for details on:
+- `app.yaml` configuration and command specification
+- Environment variables and SQL warehouse binding
+- Local development authentication options
 
 ## Deploy app
 

docs/docs/configuration.mdx

@@ -0,0 +1,145 @@
+---
+sidebar_position: 5
+---
+
+# Configuration
+
+This guide covers environment variables and configuration options for AppKit applications.
+
+## App deployment configuration
+
+### `app.yaml` file
+
+The `app.yaml` file configures your app's runtime environment in Databricks Apps.
+
+**Basic example:**
+
+```yaml
+command:
+  - node
+  - build/index.mjs
+env:
+  - name: DATABRICKS_WAREHOUSE_ID
+    valueFrom: sql-warehouse
+```
+
+### Command specification
+
+Specify how to start your app in the `command` field:
+
+```yaml
+command:
+  - node
+  - build/index.mjs
+```
+
+This runs the production build of your AppKit server (created by `npm run build`).
+
+### Binding a SQL warehouse
+
+To use the analytics plugin, bind a SQL warehouse in your `app.yaml`:
+
+```yaml
+env:
+  - name: DATABRICKS_WAREHOUSE_ID
+    valueFrom: sql-warehouse
+```
+
+This makes the warehouse ID available to your app at runtime. The `valueFrom: sql-warehouse` directive tells Databricks Apps to inject the configured warehouse ID.
+
+For advanced configuration options (authorization, networking, resource limits), see the [Databricks Apps Configuration](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/configuration) documentation.
+
+## Environment variables
+
+### Required for Databricks Apps deployment
+
+These are typically **provided by Databricks Apps runtime** (exact set can vary by platform/version):
+
+| Variable | Description |
+|----------|-------------|
+| `DATABRICKS_HOST` | Workspace URL (e.g. `https://xxx.cloud.databricks.com`) |
+| `DATABRICKS_APP_PORT` | Port to bind (default: `8000`) |
+| `DATABRICKS_APP_NAME` | App name in Databricks |
+
+### Required for SQL queries (analytics plugin)
+
+| Variable | Description | How to Set |
+|----------|-------------|------------|
+| `DATABRICKS_WAREHOUSE_ID` | SQL warehouse ID | In `app.yaml`: `valueFrom: sql-warehouse` |
+
+See the [App deployment configuration](#app-deployment-configuration) section above for details on how to bind this variable.
+
+### Optional variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DATABRICKS_WORKSPACE_ID` | Workspace ID | Auto-fetched from API |
+| `NODE_ENV` | `"development"` or `"production"` | — |
+| `FLASK_RUN_HOST` | Host to bind | `0.0.0.0` |
+
+### Telemetry (optional)
+
+| Variable | Description |
+|----------|-------------|
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry collector endpoint |
+| `OTEL_SERVICE_NAME` | Service name for traces |
+
+## Local development authentication
+
+For local development, you need to authenticate with Databricks. Choose one of the following options:
+
+### Option 1: Databricks CLI authentication (recommended)
+
+Configure authentication once using the Databricks CLI:
+
+```bash
+databricks auth login --host [host] --profile [profile-name]
+```
+
+If you use `DEFAULT` as the profile name, you can run your dev server directly:
+
+```bash
+npm run dev
+```
+
+To run with a specific profile, set the `DATABRICKS_CONFIG_PROFILE` environment variable:
+
+```bash
+DATABRICKS_CONFIG_PROFILE=my-profile npm run dev
+```
+
+Note: Some Databricks SDK versions use `DATABRICKS_PROFILE` instead of `DATABRICKS_CONFIG_PROFILE`.
+
+### Option 2: Environment variables
+
+```bash
+export DATABRICKS_HOST="https://xxx.cloud.databricks.com"
+export DATABRICKS_TOKEN="dapi..."
+export DATABRICKS_WAREHOUSE_ID="abc123..."
+npm run dev
+```
+
+### Option 3: `.env` file (auto-loaded by AppKit)
+
+Create a `.env` file in your project root (add to `.gitignore`!):
+
+```bash
+DATABRICKS_HOST=https://xxx.cloud.databricks.com
+DATABRICKS_TOKEN=dapi...
+DATABRICKS_WAREHOUSE_ID=abc123...
+```
+
+Then run:
+
+```bash
+npm run dev
+```
+
+## Advanced configuration
+
+For advanced Databricks Apps configuration (authorization, networking, resource limits), refer to the [Databricks Apps Configuration](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/configuration) documentation.
+
+## See also
+
+- [App management](./app-management.mdx) - Deploying and managing apps
+- [Plugins](./plugins.md) - Plugin configuration options

docs/docs/development/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Development",
+  "position": 7,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Development",
+    "description": "Guides for developing AppKit applications"
+  }
+}

docs/docs/development/llm-guide.mdx

@@ -0,0 +1,82 @@
+---
+sidebar_position: 8
+---
+
+# LLM Guide
+
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+export function LlmsTxtLink({ children = '`llms.txt`' }) {
+  const { siteConfig } = useDocusaurusContext();
+  const llmsTxtUrl = `${siteConfig.baseUrl}llms.txt`;
+  return <a href={llmsTxtUrl}>{children}</a>;
+}
+
+This document provides prescriptive guidance for AI coding assistants generating code with Databricks AppKit. It is intentionally opinionated to ensure consistent, production-ready code generation.
+
+:::note
+This file contains just a subset of the LLM guidance.
+To get the complete guidance, see the <LlmsTxtLink /> file for full guidance based on the AppKit documentation.
+:::
+
+## High-level mission
+
+Build **full-stack TypeScript apps** on Databricks using:
+
+- **Backend**: `@databricks/appkit`
+- **Frontend**: `@databricks/appkit-ui`
+- **Analytics**: SQL files in `config/queries/*.sql` executed via the AppKit analytics plugin
+
+This guide is designed to work even when you *do not* have access to the AppKit source repo. Prefer only public package APIs and portable project structures.
+
+## Hard rules (LLM guardrails)
+
+- **Do not invent APIs**. If unsure, stick to the patterns shown in the documentation and only use documented exports from `@databricks/appkit` and `@databricks/appkit-ui`.
+- **`createApp()` is async**. Prefer **top-level `await createApp(...)`**. If you can't, use `void createApp(...)` and do not ignore promise rejection.
+- **Always memoize query parameters** passed to `useAnalyticsQuery` / charts to avoid refetch loops.
+- **Always handle loading/error/empty states** in UI (use `Skeleton`, error text, empty state).
+- **Always use `sql.*` helpers** for query parameters (do not pass raw strings/numbers unless the query expects none).
+- **Never construct SQL strings dynamically**. Use parameterized queries with `:paramName`.
+- **Never use `require()`**. Use ESM `import/export`.
+
+## TypeScript import rules
+
+If your `tsconfig.json` uses `"verbatimModuleSyntax": true`, **always use `import type` for type-only imports** (otherwise builds can fail in strict setups):
+
+```ts
+import type { ReactNode } from "react";
+import { useMemo } from "react";
+```
+
+## LLM checklist (before finalizing code)
+
+### Project setup
+
+- `package.json` has `"type": "module"`
+- `tsx` is in devDependencies for dev server
+- `dev` script uses `NODE_ENV=development tsx watch server/index.ts`
+- `client/index.html` exists with `<div id="root"></div>` and script pointing to `client/src/main.tsx`
+
+### Backend
+
+- `await createApp({ plugins: [...] })` is used (or `void createApp` with intent)
+- `server()` is included (always)
+- If using SQL: `analytics({})` included + `config/queries/*.sql` present
+- Queries use `:param` placeholders, and params are passed from UI using `sql.*`
+- If query needs workspace scoping: uses `:workspaceId`
+
+### Frontend
+
+- `useMemo` wraps parameters objects
+- Loading/error/empty states are explicit
+- Charts use `format="auto"` unless you have a reason to force `"json"`/`"arrow"`
+- Charts use props (`xKey`, `yKey`, `colors`) NOT children (they're ECharts-based, not Recharts)
+- If using tooltips: root is wrapped with `<TooltipProvider>`
+
+### Never
+
+- Don't build SQL strings manually
+- Don't pass untyped raw params for annotated queries
+- Don't ignore `createApp()`'s promise
+- Don't invent UI components not listed in the documentation
+- Don't pass Recharts children (`<Bar>`, `<XAxis>`, etc.) to AppKit chart components