docs(apps): codegen quality guidelines — AppKit API, type casts, version pinning (LKB-12428, LKB-12465, LKB-12614) (#69)

## Summary

Three codegen-quality guidelines for the `databricks-apps` skill, each
addressing a distinct regression observed in apps-mcp-evals nightlies:

1. **AppKit API surface** (LKB-12465): run `npx @databricks/appkit docs
<section>` before writing server code. Training data has stale shapes; a
single invented signature fails `tsc --noEmit`.
2. **TypeScript casts** (LKB-12428): never use `as unknown as <T>` —
`appkit lint` enforces `no-double-type-assertion`. Use Zod, type guards,
or mapper functions.
3. **AppKit version pinning** (LKB-12614): never override
`@databricks/appkit` version in `package.json` — `databricks apps init`
sets the correct version. Agent was writing stale versions from training
data (0.11.0 when latest is 0.31.0).

Plus: smoke-test selector guidance (use Playwright locator APIs, not
React Testing Library), data-size cap for analytics payloads.

Supersedes PR #65 (which covered only the TypeScript-casts bullet).
Mario Cadenas's review feedback from #65 is incorporated (auto-gen
queryKey files carve-out, warehouse-unavailable `unknown` case).

## Documentation safety checklist

- [x] Examples use least-privilege permissions
- [x] Elevated permissions explicitly called out where required
- [x] Sensitive values are obfuscated
- [x] No insecure patterns introduced

Co-authored-by: Isaac

Author: keugenek

skills/databricks-apps/SKILL.md

@@ -38,6 +38,7 @@ Build apps that deploy to Databricks Apps platform.
 - **Smoke tests** (AppKit only): ALWAYS update `tests/smoke.spec.ts` selectors BEFORE running validation. Default template checks for "Minimal Databricks App" heading and "hello world" text — these WILL fail in your custom app. See [testing guide](references/testing.md).
 - **Smoke test selectors**: use only Playwright locator APIs — `getByRole`, `getByText`, `getByPlaceholder`, `getByLabel`. `getByLabelText` does not exist in Playwright (it is a React Testing Library method) and throws `TypeError` at runtime. See [testing guide](references/testing.md) or `npx playwright codegen`.
 - **Smoke test data**: keep result sets under the 1 MB analytics-event payload cap. Queries returning thousands of rows cause `INVALID_REQUEST: Event exceeds max size of 1048576 bytes` and `net::ERR_ABORTED`, leaving every asserted UI element absent. Use `LIMIT` or an aggregated query (e.g. `COUNT(*) GROUP BY status`) — never raw row dumps.
+- **AppKit version**: never override the `@databricks/appkit` or `@databricks/appkit-ui` version in `package.json` — `databricks apps init` sets the correct version. Do not run `npm install @databricks/appkit@<version>` unless explicitly asked by the user. If you need a different version, re-scaffold with `databricks apps init --version <version>`.
 - **Authentication**: covered by parent `databricks-core` skill.
 - **AppKit API surface**: before writing code that calls AppKit APIs (`createApp`, plugin shapes, `useAnalyticsQuery`, etc.), run `npx @databricks/appkit docs <section>` and use the actual signature. Training data has stale shapes; a single invented signature fails `tsc --noEmit` during validate. The docs ship with the installed AppKit and are the authoritative source.
 - **TypeScript casts**: never use `as unknown as <T>` double-assertions — `appkit lint` enforces `no-double-type-assertion` and one violation fails the entire validate step. Instead: narrow with Zod (`z.infer<typeof schema>`), use a runtime type guard, or write a typed mapper function. If a query result needs reshaping, type the row schema via queryKey types rather than casting.