databricks · pkosiec · Jan 13, 2026 · Jan 9, 2026 · Jan 9, 2026
diff --git a/docs/docs/api/index.md b/docs/docs/api/index.md
@@ -4,5 +4,19 @@ This section contains the API reference for the AppKit packages.
 
 ## Modules
 
-- [`appkit`](appkit/index.md) - Core library
-- [`appkit-ui`](appkit-ui/index.md) - UI components library
+- [`appkit`](appkit/index.md) - Core library. Provides the core functionality for building Databricks applications.
+- [`appkit-ui`](appkit-ui/index.md) - UI components library. Provides a set of UI primitives for building Databricks apps in [React](https://react.dev/).
+
+## Getting started
+
+To learn how to get started with AppKit, see the [getting started guide](../index.md) for AI-assisted and manual quick start options.
+
+## Installation
+
+To install the AppKit packages into your existing JavaScript/TypeScript project, use `npm` or your package manager of choice:
+
+```bash
+npm install @databricks/appkit
+npm install @databricks/appkit-ui
+```
+
diff --git a/docs/docs/core-concepts/principles.md b/docs/docs/core-concepts/principles.md
@@ -1,24 +1,39 @@
 # Principles
 
+Learn about the fundamental concepts and principles behind AppKit.
+
 ## 1. Highly Opinionated
-  AppKit must provide a clear path with best practices for building Databricks
-  applications. We provide strong defaults, with advanced customization when needed.
+
+AppKit must provide a clear path with best practices for building Databricks
+applications. We provide strong defaults, with advanced customization when needed.
+
 ## 2. Built for Application Use Cases
-  This SDK is for application development, not infrastructure management.
-  Databricks' internal implementation details must be abstracted. We're building an
-  application SDK, not a service wrapper.
+
+This SDK is for application development, not infrastructure management.
+Databricks' internal implementation details must be abstracted. We're building an
+application SDK, not a service wrapper.
+
 ## 3. Delightful Developer Experience
-  Every interface, doc, example, tool, and implementation must provide developer joy. Combined with the Highly Opinionated principle, this creates a true plug-and-play experience.
+
+Every interface, doc, example, tool, and implementation must provide developer joy. Combined with the Highly Opinionated principle, this creates a true plug-and-play experience.
+
 ## 4. Zero-Trust Security
-  Minimize exposed surface area, fail safely by default, and validate all inputs.
-  AppKit must always have a zero-trust mindset.
+
+Minimize exposed surface area, fail safely by default, and validate all inputs.
+AppKit must always have a zero-trust mindset.
+
 ## 5. Optimized for Humans and AI
-  Developers and LLMs both use this SDK. Every API must be discoverable,
-  self-documenting, and inferable by both types of users. Test with both.
+
+Developers and LLMs both use this SDK. Every API must be discoverable,
+self-documenting, and inferable by both types of users. Test with both.
+
 ## 6. Production-Ready from Day One
-  Even the smallest feature can be used by enterprise users, so everything
-  shipped must be production-ready. Observability, reliability, and scalability
-  since day one.
+
+Even the smallest feature can be used by enterprise users, so everything
+shipped must be production-ready. Observability, reliability, and scalability
+since day one.
+
 ## 7. Layered Extensibility
+
 AppKit provides high-level plugins, low-level primitives, and extension points for custom plugins. It integrates into any application architecture and never blocks your path forward.
 
diff --git a/docs/docs/index.md b/docs/docs/index.md
@@ -2,12 +2,88 @@
 sidebar_position: 1
 ---
 
-# Getting started
+# Getting Started
 
 ## Introduction
 
-## Installation
+AppKit is a TypeScript SDK for building production-ready Databricks applications with a plugin-based architecture. It provides opinionated defaults, built-in observability, and seamless integration with Databricks services.
 
-## Usage
+AppKit simplifies building data applications on Databricks by providing:
 
-## Deployment
+- **Plugin architecture**: Modular design with built-in server and analytics plugins
+- **Type safety**: End-to-end TypeScript with automatic query type generation
+- **Production-ready features**: Built-in caching, telemetry, retry logic, and error handling
+- **Developer experience**: Remote hot reload, file-based queries, optimized for AI-assisted development
+- **Databricks native**: Seamless integration with SQL Warehouses, Unity Catalog, and other workspace resources
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org)
+- Databricks CLI: install and configure it according to the [official tutorial](https://docs.databricks.com/aws/en/dev-tools/cli/tutorial).
+
+## Quick start options
+
+There are two ways to get started with AppKit:
+
+- **AI-assisted** (recommended): Use an AI coding assistant connected via the Databricks MCP server to explore data, run CLI commands, and scaffold your app interactively.
+- **Manual**: Use the Databricks CLI directly to create, bootstrap, and deploy your app.
+
+Choose the path that best fits your workflow; both approaches produce the same kind of AppKit-based Databricks application.
+
+## AI-first quick start
+
+Databricks AppKit is designed to work with AI coding assistants through the Databricks MCP server.
+
+Install the Databricks MCP server and configure it for use with your preferred AI assistant:
+
+```bash
+databricks experimental apps-mcp install
+```
+
+Once configured for your development environment, you can use your AI assistant to create and deploy new Databricks applications, as well as to iteratively evolve your app’s codebase.
+
+The MCP server exposes the following capabilities:
+
+- **Data exploration**: Query catalogs, schemas, tables, and execute SQL
+- **CLI command execution**: Run bundle, apps, and workspace operations
+- **Workspace resource discovery**: Inspect and navigate workspace resources
+
+## Manual quick start
+
+Learn how to create and deploy a sample Databricks application that uses AppKit with the Databricks CLI.
+
+### Create a new Databricks app
+
+Run the following command to create a new Databricks application:
+
+```sh
+databricks apps create {application-name}
+```
+
+This creates a new Databricks application named `{application-name}` in the current workspace.
+
+### Bootstrap the app codebase with AppKit
+
+Run the following command to bootstrap the app codebase:
+
+```sh
+databricks experimental appkit init
+```
+
+Follow the prompts to bootstrap the app codebase in the current working directory.  
+This creates a complete TypeScript project with Tailwind CSS, React, and AppKit installed out of the box.
+
+### Deploy the app to Databricks
+
+Run the following command to deploy the app to Databricks:
+
+```sh
+databricks experimental appkit deploy .
+```
+
+This deploys the sample app to Databricks.
+
+## Next steps
+
+- **[Core Concepts](./core-concepts/principles)**: Learn about AppKit's design principles and architecture
+- **[API Reference](./api/appkit/)**: Explore the complete API documentation