@@ -1,39 +1,59 @@
 # AppKit
 
-Build Databricks Apps faster with our brand-new Node.js + React SDK. Built for humans and AI.
+Build Databricks Apps faster with a Node.js + React SDK. Built for humans and AI.
 
-## Introduction
+AppKit is a TypeScript SDK for building production-ready Databricks applications with a plugin-based architecture. It gives you opinionated defaults, built-in observability, and first-class integration with Databricks services — so you spend time on your app, not the plumbing.
 
-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.
+- **Plugin architecture** — Compose your app from focused plugins; a base server plus analytics, Genie, files, and more.
+- **Type safety** — End-to-end TypeScript with automatic query type generation.
+- **Production-ready** — Built-in caching, telemetry, retries, and error handling.
+- **Great DX** — Hot reload, file-based queries, and a workflow tuned for AI-assisted development.
+- **Databricks native** — SQL Warehouses, Unity Catalog, Lakebase, and other workspace resources out of the box.
 
-AppKit simplifies building data applications on Databricks by providing:
+## Quickstart
 
-- **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
+Requires the Databricks CLI and Node.js.
 
-## Plugins
+**AI-assisted (recommended)** — scaffold and evolve your app by prompting an AI assistant. Install the Agent Skills once:
 
-AppKit's power comes from its plugin system. Each plugin adds a focused capability to your app with minimal configuration.
+```sh
+databricks aitools install
+```
 
-- **Analytics Plugin** — Query your Lakehouse data directly from your app. Define SQL queries as files, execute them against Databricks SQL Warehouses, and get automatic caching, parameterization, and on-behalf-of user execution out of the box.
-- **Genie Plugin** — Conversational AI interface powered by Databricks AI/BI Genie. Let users ask natural language questions against your data and get answers with automatic chart inference and visualization.
-- **Files Plugin** — Browse, upload, and manage files in Unity Catalog Volumes. Supports multiple volumes, content type validation, and on-behalf-of user access.
-- **Lakebase Plugin** — OLTP database operations against Databricks Lakebase with automatic OAuth token management. Returns a standard `pg.Pool` compatible with Prisma, Drizzle, TypeORM, and other ORMs.
+Then ask your assistant to build the app, e.g. _"Create a Databricks app that shows a dashboard of the NYC taxi trips dataset."_ See the [AI-assisted development](https://developers.databricks.com/docs/appkit/v0/development/ai-assisted-development) guide.
 
-> Missing a plugin? [Open an issue](https://github.com/databricks/appkit/issues/new) and tell us what you need — community input directly shapes the roadmap.
+**Manual** — scaffold and deploy with the CLI directly:
+
+```sh
+databricks apps init      # scaffold the app + install dependencies (follow the prompts)
+databricks apps deploy     # deploy to your workspace
+```
+
+## What an app looks like
+
+Every app is a set of plugins hosted by `server()`:
 
-## Getting started
+```ts
+import { createApp, server, analytics } from '@databricks/appkit';
 
-Follow the [Getting Started](https://developers.databricks.com/docs/appkit/v0/) guide to get started with AppKit.
+createApp({
+  plugins: [server(), analytics()],
+});
+```
 
-🤖 For AI/code assistants, see the [AI-assisted development](https://developers.databricks.com/docs/appkit/v0/development/ai-assisted-development) guide.
+With `analytics()`, drop a `.sql` file in `config/queries/` and it's served at `POST /api/analytics/query/<query_key>` — parameterized, cached, and (with a `.obo.sql` name) executed on behalf of the signed-in user.
+
+## Plugins
+
+AppKit's power comes from its plugin system. Each plugin adds a focused capability — analytics, genie, files, and more — with minimal configuration. See the [plugins documentation](https://developers.databricks.com/docs/appkit/v0/plugins) for the full list and API.
+
+> Missing a plugin? [Open an issue](https://github.com/databricks/appkit/issues/new) and tell us what you need — community input directly shapes the roadmap.
 
 ## Documentation
 
-📖 For full AppKit documentation, visit the [AppKit Documentation](https://developers.databricks.com/docs/appkit/v0/) website.
+- **[AppKit documentation](https://developers.databricks.com/docs/appkit/v0/)** — getting started, guides, and full API reference.
+- **[AI-assisted development](https://developers.databricks.com/docs/appkit/v0/development/ai-assisted-development)** — build and evolve apps with an AI assistant.
+- New to the Databricks Apps platform? Start with the [Apps quickstart](https://developers.databricks.com/docs/apps/quickstart).
 
 ## Contributing