feat(appkit-docs): sync via shallow git clone at build time

.github/workflows/ci.yml

@@ -29,6 +29,9 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Sync AppKit docs
+        run: node scripts/sync-appkit-docs.mjs
+
       - name: Format check
         run: bunx prettier -c .
 

.gitignore

@@ -11,6 +11,9 @@ bun.lock
 .cache-loader
 static/llms.txt
 static/raw-docs
+docs/appkit/
+src/components/doc-examples/
+static/appkit-preview/
 
 # Misc
 .DS_Store

.prettierignore

@@ -1,6 +1,13 @@
 dist/
+build/
 .databricks/
+.docusaurus/
 **/dist/
 **/.databricks/
 **/node_modules/
 node_modules/
+
+# Generated at build time by scripts/sync-appkit-docs.mjs
+docs/appkit/
+src/components/doc-examples/
+static/appkit-preview/

.prettierrc

@@ -0,0 +1,4 @@
+{
+  "useTabs": false,
+  "tabWidth": 2
+}

CONTRIBUTING.md

@@ -21,6 +21,8 @@ npm run dev
 
 `npm run dev` starts Docusaurus and the Vercel Functions together at [http://localhost:3000](http://localhost:3000). The site reloads on save.
 
+AppKit reference docs are fetched automatically on first build or dev start via a shallow git clone of the [appkit](https://github.com/databricks/appkit) repository. Run `npm run sync:appkit-docs` to force a re-sync.
+
 You'll also need the [Vercel CLI](https://vercel.com/docs/cli) (for `vercel dev`) and the [Databricks CLI](https://dev.databricks.com/docs/tools/databricks-cli) if you plan to verify end-to-end flows against a real workspace.
 
 ### Feature Flags
@@ -47,7 +49,7 @@ A flag is **enabled only when its value is exactly `"true"`** — any other valu
 | `npm run verify:images`    | Check every image under `static/img/guides/` and `static/img/examples/` matches the 16:9 / ≥1600×900 contract |
 | `npm run build`            | Production build via Docusaurus                                                                               |
 | `npm run test`             | Build + Vitest + Playwright smoke tests (includes sitemap, robots, llms.txt)                                  |
-| `npm run sync:appkit-docs` | Regenerate AppKit reference docs                                                                              |
+| `npm run sync:appkit-docs` | Force re-sync AppKit docs from main (auto-synced on first build)                                              |
 
 ### Pre-Commit Hook
 

package.json

@@ -7,7 +7,7 @@
     "dev": "bash scripts/dev.sh",
     "start": "docusaurus start",
     "build": "docusaurus build",
-    "sync:appkit-docs": "node scripts/sync-appkit-docs.mjs",
+    "sync:appkit-docs": "node scripts/sync-appkit-docs.mjs --force",
     "swizzle": "docusaurus swizzle",
     "deploy": "docusaurus deploy",
     "clear": "docusaurus clear",
@@ -22,7 +22,9 @@
     "test:docs-verify": "vitest run --config vitest.docs-verify.config.ts",
     "verify:images": "node scripts/verify-resource-images.mjs",
     "validate:content": "node scripts/validate-content.mjs",
-    "prepare": "husky"
+    "prepare": "husky",
+    "prebuild": "node scripts/sync-appkit-docs.mjs",
+    "prestart": "node scripts/sync-appkit-docs.mjs"
   },
   "dependencies": {
     "@base-ui/react": "^1.3.0",

scripts/dev.sh

@@ -16,4 +16,7 @@ if [ -f "$ENV_FILE" ]; then
   set +a
 fi
 
+# Sync AppKit docs if not already present
+node scripts/sync-appkit-docs.mjs
+
 exec vercel dev "$@"