@proveanything/smartlinks 1.9.20 → 1.9.22

package/dist/docs/ui-utils.md

@@ -0,0 +1,294 @@
+# SmartLinks UI Utils (`@proveanything/smartlinks-utils-ui`)
+
+> Companion React component library for the SmartLinks SDK. Ships the heavy, opinionated admin UI pieces that almost every SmartLinks microapp ends up needing — built once, theme-able, tree-shakeable, and wired straight into the SmartLinks SDK.
+>
+> Package: `@proveanything/smartlinks-utils-ui`  
+> Tracks: `@proveanything/smartlinks ≥ 1.9`
+
+---
+
+## What is this module for?
+
+`@proveanything/smartlinks-utils-ui` sits on top of `@proveanything/smartlinks`. The core SDK handles data — records, configurations, interactions. This module handles **UI** — the shared React components, hooks, and admin shells that translate SDK data into consistent admin interfaces.
+
+**When do you need it?**
+
+- You are building an admin UI for a records-based microapp (see [records-admin-pattern.md](records-admin-pattern.md))
+- You need a media asset picker, icon picker, or font picker in an admin panel
+- You need a recursive rule/conditions editor for targeting or audience logic
+- You want the standard inheritance/override editor for scoped records
+- You need the `useResolvedRecord` hook on the public widget side
+
+You do **not** need it for apps that only use `appConfiguration`, basic widgets without scoped data, or executor bundles.
+
+> **Admin-only**: all components call the SDK with `admin: true`. Do not render them in public-facing views.
+
+---
+
+## Install
+
+```bash
+npm install @proveanything/smartlinks-utils-ui
+```
+
+Peer dependencies (you already have these in a SmartLinks app):
+
+```bash
+npm install react react-dom @proveanything/smartlinks
+# Recommended — enables caching and pagination in Records Admin Shell:
+npm install @tanstack/react-query
+```
+
+Import the compiled styles **once** in your app entry (e.g. `main.tsx`):
+
+```tsx
+import '@proveanything/smartlinks-utils-ui/styles.css';
+```
+
+Components inherit your shadcn-compatible CSS variables (`--primary`, `--background`, `--border`, …) so they pick up your theme automatically.
+
+---
+
+## What's in the box
+
+| Module | What it is | When to reach for it |
+|--------|------------|----------------------|
+| [Records Admin Shell](#records-admin-shell) | Full admin UI for `app.records` with scope inheritance | Per-product / per-variant / per-batch / per-facet config tools |
+| [Asset Picker](#asset-picker) | Browse / upload / paste / URL-import images and files | Any time the admin needs to pick or upload media |
+| [Icon Picker](#icon-picker) | Searchable Font Awesome 7 Pro picker | Configurable buttons, badges, menus, tiles |
+| [Font Picker](#font-picker) | Google Fonts + custom uploaded fonts | Theme editors, brand customisation panels |
+| [Conditions Editor](#conditions-editor) | Recursive AND/OR rule builder for 12 condition types | Targeting, gating, audience rules, segmentation |
+
+---
+
+## Records Admin Shell
+
+The primary export. A complete admin UI for managing `app.records` — typed JSON blobs attached to facets, products, variants, and batches — with scope inheritance built in. You provide the form for one record; the shell handles everything else.
+
+```tsx
+import {
+  RecordsAdminShell,
+  InheritanceMarker,
+  type EditorContext,
+} from '@proveanything/smartlinks-utils-ui/records-admin';
+import * as SL from '@proveanything/smartlinks';
+
+<RecordsAdminShell<NutritionData>
+  SL={SL}
+  collectionId={collectionId}
+  appId={appId}
+  recordType="nutrition"
+  label="Nutrition info"
+  scopes={['facet', 'product', 'variant', 'batch']}
+  contextScope={{ productId, variantId, batchId }}   // from iframe URL — optional
+  defaultData={() => ({})}
+  csvSchema={{ columns: [/* ... */] }}
+  renderEditor={(ctx) => <NutritionForm ctx={ctx} />}
+  renderPreview={({ resolved }) => <pre>{JSON.stringify(resolved, null, 2)}</pre>}
+/>
+```
+
+**What it handles:**
+
+- **Browser pane** with scope tabs (Facet / Product / Variant / Batch), search, and status filter pills (All / Configured / Partial / Empty)
+- **Editor pane** with sticky save / discard / delete footer
+- **Per-field `<InheritanceMarker>`** showing whether a value is the record's own or inherited from a parent scope, with one-click revert-to-inherited
+- **Inheritance resolver** walks `batch → variant → product → facet` and returns both the resolved and parent values
+- **Collection-aware tabs**: calls `collection.get` and hides Variants / Batches tabs unless `collection.variants` / `collection.batches` are true — no flicker
+- **Server-side pagination** via `useInfiniteQuery` — handles thousands of products with a "Load more" button
+- **Context-aware**: pass `contextScope` from your iframe URL (`productId` / `variantId` / `batchId`) and the browser is constrained to that subtree with the right tab auto-selected
+- **CSV import / export** with a schema you define; failed rows come back as an annotated CSV
+- **Bulk actions menu** (apply-to-many, copy-from, clear) via `bulkUpsert` / `bulkDelete`
+- **Telemetry hook** (`onTelemetry`) emits typed events for save, delete, scope change, CSV import/export, bulk apply
+- **i18n strings** fully overridable
+
+> Requires a `<QueryClientProvider>` from `@tanstack/react-query` somewhere up the tree.
+
+### Lower-level pieces (advanced use)
+
+```tsx
+import {
+  // Hooks
+  useRecordList, useRecordEditor, useResolvedRecord, useScopeProbe,
+  // Data helpers
+  parseRef, buildRef, resolutionChain,
+  listRecords, getRecordByRef, upsertRecord, deleteRecord,
+  bulkUpsert, bulkDelete,
+  exportCsv, importCsv, downloadBlob,
+  // UI pieces
+  RecordBrowser, RecordEditor, ScopeBreadcrumb,
+  InheritanceMarker, ResolvedPreview, BulkActionsMenu,
+} from '@proveanything/smartlinks-utils-ui/records-admin';
+```
+
+### `useResolvedRecord` hook
+
+```ts
+import { useResolvedRecord } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const { data, source, isLoading } = useResolvedRecord({
+  SL,
+  appId,
+  recordType: 'nutrition',
+  collectionId,
+  productId,
+  variantId,   // optional
+  batchId,     // optional
+  proofId,     // optional
+});
+// source: 'proof' | 'batch' | 'variant' | 'product' | 'facet' | 'default' | null
+```
+
+Walks the resolution chain defined in [records-admin-pattern.md §4](records-admin-pattern.md#4-resolution-order-required). Use this on the **public widget side** to read the correct value for a given context.
+
+### `parseRef` / `buildRef` utilities
+
+```ts
+import { parseRef, buildRef } from '@proveanything/smartlinks-utils-ui/records-admin';
+
+const parsed = parseRef('variant:prod_abc:var_500ml');
+// → { kind: 'variant', productId: 'prod_abc', variantId: 'var_500ml' }
+
+const ref = buildRef({ kind: 'facet', facetKey: 'bread_type', valueKey: 'sourdough' });
+// → 'facet:bread_type:sourdough'
+```
+
+See [records-admin-pattern.md Appendix A](records-admin-pattern.md#appendix-a--ref-parser-reference) for the full `ParsedRef` type.
+
+---
+
+## Asset Picker
+
+```tsx
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui/asset-picker';
+
+<AssetPicker
+  scope={{ type: 'collection', collectionId: 'abc123' }}
+  mode="dialog"               // or "inline"
+  allowUpload
+  accept={['image/*']}        // MIME filtering
+  onSelect={(asset) => setHeroUrl(asset.url)}
+  trigger={<Button>Choose image</Button>}
+/>
+```
+
+**What it does:**
+- Browses assets at **collection** or **product** scope (dual-scope tabs)
+- Four ingest paths: file upload, URL import, clipboard paste (with rename preview), and selection from existing assets
+- Inline mode for embedding in a panel; dialog mode for modal pickers
+- Double-click a tile to confirm instantly
+
+---
+
+## Icon Picker
+
+```tsx
+import { IconPicker } from '@proveanything/smartlinks-utils-ui/icon-picker';
+
+<IconPicker
+  mode="dialog"
+  value="fa-solid fa-heart"
+  onSelect={(icon) => setIcon(icon.name)}
+  trigger={<Button>Pick icon</Button>}
+/>
+```
+
+**What it does:**
+- Searches **Font Awesome 7 Pro** (uses the shared kit `75493b59b3`)
+- Family hierarchy: Classic (Solid / Regular / Light), Duotone, and Brands
+- Search-first with a background catalogue crawler — first results appear instantly, the full index fills in behind
+- Auto-switches families intelligently (e.g. brand searches surface brand icons even when "Classic" is selected)
+
+> Requires the FA kit script to be present on the host page.
+
+---
+
+## Font Picker
+
+```tsx
+import { FontPicker } from '@proveanything/smartlinks-utils-ui/font-picker';
+
+<FontPicker
+  mode="dialog"
+  value="Inter"
+  showPreview
+  onSelect={(font) => {
+    console.log(font.family);        // "Inter"
+    console.log(font.cssFontFamily); // "'Inter', ui-sans-serif, system-ui, sans-serif"
+    console.log(font.loadSnippet);   // <link href="..." rel="stylesheet">
+  }}
+/>
+
+{/* With custom fonts uploaded into the collection */}
+<FontPicker
+  mode="dialog"
+  showCustomFonts
+  scope={{ collectionId: 'abc123' }}
+  onSelect={(font) => /* ... */}
+/>
+```
+
+**What it does:**
+- Full **Google Fonts** catalogue plus any **custom fonts** uploaded for the brand (stored via `appConfiguration` under `customFonts`)
+- Upload zone auto-detects weight/style from the filename (e.g. `MyFont-BoldItalic.woff2`)
+- Returns a `FontSelection` with `family`, `cssFontFamily`, and a ready-to-inject `loadSnippet` (`<link>` for Google fonts, `@font-face` CSS for custom uploads)
+- Lazy-loads previews via `IntersectionObserver`; includes a management UI for editing custom font definitions
+
+---
+
+## Conditions Editor
+
+```tsx
+import { ConditionsEditor } from '@proveanything/smartlinks-utils-ui/conditions-editor';
+
+<ConditionsEditor
+  value={rules}
+  onChange={setRules}
+  collectionId={collectionId}     // auto-loads facet definitions
+  versions={[{ title: 'Default', value: '' }]}
+  tags={['featured', 'new']}
+/>
+```
+
+**What it does:**
+- Recursive AND / OR group builder — nest conditions to any depth
+- **12 condition types:** Version, Country, Value, User, Date, Device, Tag, Facet, Geofence, Product, Item Status, Condition Reference
+- **Facet condition** auto-fetches definitions from `facets.publicList(collectionId, { includeValues: true })` when only `collectionId` is passed (SDK ≥ 1.9.20)
+- **Country picker** is a searchable multi-select with removable ISO 3166-1 chips and a "Use regions" toggle
+- Renders correctly inside iframe contexts — avoids `overflow-hidden` so dropdowns escape their cards
+
+---
+
+## Tree shaking
+
+Each component has its own subpath export:
+
+```tsx
+// Bundles only the Asset Picker
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui/asset-picker';
+
+// Barrel import — bundler tree-shakes the rest
+import { AssetPicker } from '@proveanything/smartlinks-utils-ui';
+```
+
+If you use subpath imports, import `styles.css` separately — subpaths do not pull it in automatically.
+
+---
+
+## Relationship to the core SDK
+
+```
+@proveanything/smartlinks            ← data layer (records, config, interactions, …)
+        ↑
+@proveanything/smartlinks-utils-ui   ← UI layer (components, hooks, admin shells)
+        ↑
+your microapp                        ← domain logic and custom forms
+```
+
+---
+
+## Further reading
+
+- [records-admin-pattern.md](records-admin-pattern.md) — the data contract that `RecordsAdminShell` implements
+- [building-react-components.md](building-react-components.md) — dual-mode rendering rules that apply to all components
+- [app-manifest.md](app-manifest.md) — the `records` manifest block that drives tab generation

package/dist/openapi.yaml

@@ -17134,6 +17134,10 @@ components:
           type: string
         allowAutoGenerateClaims:
           type: boolean
+        variants:
+          type: boolean
+        batches:
+          type: boolean
         defaultAuthKitId:
           type: string
       required:
@@ -17159,6 +17163,8 @@ components:
         - supported
         - roles
         - shortId
+        - variants
+        - batches
         - defaultAuthKitId
     AppConfig:
       type: object

package/dist/types/collection.d.ts

@@ -69,6 +69,8 @@ export interface Collection {
     portalUrl?: string;
     /** Allow users to claim products without providing a proof ID (auto-generates serial on-demand) */
     allowAutoGenerateClaims?: boolean;
+    variants: boolean;
+    batches: boolean;
     defaultAuthKitId: string;
 }
 export type CollectionResponse = Collection;

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 1.9.20  |  Generated: 2026-04-17T10:13:30.466Z
+Version: 1.9.22  |  Generated: 2026-04-25T11:11:00.344Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2994,6 +2994,8 @@ interface Collection {
   secondaryColor?: string
   portalUrl?: string // URL for the collection's portal (if applicable)
   allowAutoGenerateClaims?: boolean
+  variants: boolean // does this collection support variants?
+  batches: boolean // does this collection support batches?
   defaultAuthKitId: string // default auth kit for this collection, used for auth
 }
 ```

package/docs/app-manifest.md

@@ -95,7 +95,20 @@ The manifest is loaded automatically by the platform for every collection page.
     { "title": "Home",     "path": "/" },
     { "title": "Gallery",  "path": "/gallery" },
     { "title": "Settings", "path": "/settings", "params": { "tab": "advanced" } }
-  ]
+  ],
+
+  "records": {
+    "nutrition": {
+      "scopes": ["product", "facet", "batch"],
+      "defaultScope": "facet",
+      "label": "Nutrition info"
+    },
+    "cooking_steps": {
+      "scopes": ["product", "facet"],
+      "defaultScope": "product",
+      "label": "Cooking steps"
+    }
+  }
 }
 ```
 
@@ -188,6 +201,30 @@ See the [Deep Link Discovery guide](deep-link-discovery.md) for the full dual-so
 | `path` | string | ❌ | Hash route within the app (defaults to `"/"` if omitted) |
 | `params` | object | ❌ | App-specific query params appended to the URL — do **not** include platform params (`collectionId`, `productId`, etc.) |
 
+#### `records`
+
+Declares which `app.records` record types the app stores, and which scopes each type supports. Required for any app that follows the [Records-Based Admin Pattern](records-admin-pattern.md). Omit if the app does not use scoped records.
+
+The platform and the `<RecordsAdminShell>` from `@proveanything/ui-utils` read this block to render only the relevant tabs and affordances.
+
+```json
+"records": {
+  "<recordType>": {
+    "scopes": ["product", "facet", "batch"],
+    "defaultScope": "facet",
+    "label": "Human-readable label"
+  }
+}
+```
+
+| Field          | Type     | Required | Description |
+|----------------|----------|----------|-------------|
+| `scopes`       | string[] | ✅ | Allowed scope kinds in resolution order. Valid values: `"product"`, `"variant"`, `"batch"`, `"facet"`, `"proof"`, `"default"`. |
+| `defaultScope` | string   | ✅ | The scope the "Create new" button targets in the admin shell. Must be one of the declared `scopes`. |
+| `label`        | string   | ✅ | Human-readable label for the record type, used in headings and tabs. |
+
+An app may declare multiple record types under different keys (e.g. `"nutrition"` and `"cooking_steps"`).
+
 #### `executor`
 
 Declares the executor bundle — a standalone JS library for programmatic configuration, server-side SEO, and LLM content generation. Omit if the app has no executor.

package/docs/auth-kit.md

@@ -0,0 +1,162 @@
+# SmartLinks Auth Kit (`@proveanything/smartlinks` — `authKit` namespace)
+
+> End-user authentication flows for SmartLinks microapps. Covers email/password, magic links, phone OTP, Google OAuth, profile management, and password/email change flows.
+>
+> **This is part of the core SDK** — no separate install required. Import from `@proveanything/smartlinks`.
+
+---
+
+## What is Auth Kit for?
+
+Auth Kit is the **end-user identity layer** for microapps that need users to sign in. It is distinct from the admin/platform authentication (Bearer tokens) used to call admin endpoints.
+
+Use Auth Kit when:
+- Your app has a login/register screen for end users (not collection admins)
+- You need to gate features behind a verified user identity
+- You want to store user-specific data with the `userAppData` API (see [app-data-storage.md](app-data-storage.md))
+
+Do **not** use Auth Kit for:
+- Admin-side API calls (those use Bearer tokens set by the platform shell)
+- Claiming proofs (see proof claiming methods)
+
+---
+
+## Setup: creating an Auth Kit client
+
+Each app requires an Auth Kit configuration, created by a collection admin:
+
+```ts
+// Admin setup (one-time, done in admin console)
+import { authKit } from '@proveanything/smartlinks';
+
+// Returns an authKitId to store in your app config
+const config = await authKit.create(collectionId, {
+  name: 'My App Auth',
+  loginMethods: ['email', 'google', 'magic_link'],
+  redirectUrl: 'https://myapp.example.com/auth/callback',
+});
+```
+
+---
+
+## Key flows
+
+### Email / password
+
+```ts
+import { authKit } from '@proveanything/smartlinks';
+
+// Register
+const session = await authKit.register(clientId, {
+  email: 'user@example.com',
+  password: 'securePassword123',
+  displayName: 'Alice',
+});
+
+// Login
+const session = await authKit.login(clientId, 'user@example.com', 'securePassword123');
+
+// session.token — store this; pass to initializeApi for subsequent calls
+```
+
+### Magic link (passwordless email)
+
+```ts
+await authKit.sendMagicLink(clientId, {
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.example.com/auth/verify',
+});
+
+// On callback page, extract token from URL and verify
+const session = await authKit.verifyMagicLink(clientId, tokenFromUrl);
+```
+
+### Phone OTP
+
+```ts
+await authKit.sendPhoneCode(clientId, '+61400000000');
+const session = await authKit.verifyPhoneCode(clientId, '+61400000000', '123456');
+```
+
+### Google OAuth
+
+```ts
+// After Google sign-in, pass the id_token to Auth Kit
+const session = await authKit.googleLogin(clientId, googleIdToken);
+```
+
+---
+
+## Profile management
+
+```ts
+import { authKit } from '@proveanything/smartlinks';
+
+// Get current user's profile
+const profile = await authKit.getProfile(clientId);
+
+// Update profile
+await authKit.updateProfile(clientId, { displayName: 'Alice B.', avatarUrl: '...' });
+
+// Change password
+await authKit.changePassword(clientId, 'currentPass', 'newPass');
+
+// Change email (triggers verification)
+await authKit.changeEmail(clientId, 'newemail@example.com', 'password', redirectUrl);
+
+// Delete account
+await authKit.deleteAccount(clientId, 'password', 'DELETE');
+```
+
+---
+
+## Email verification
+
+Auth Kit can send and verify email addresses after registration:
+
+```ts
+await authKit.sendEmailVerification(clientId, {
+  userId,
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.example.com/auth/verified',
+});
+
+// On callback page
+await authKit.verifyEmail(clientId, tokenFromUrl);
+```
+
+---
+
+## Password reset
+
+```ts
+await authKit.requestPasswordReset(clientId, {
+  email: 'user@example.com',
+  redirectUrl: 'https://myapp.example.com/auth/reset',
+  clientName: 'My App',
+});
+
+// On reset page — verify token is still valid before showing the form
+await authKit.verifyResetToken(clientId, tokenFromUrl);
+
+// Complete reset
+await authKit.completePasswordReset(clientId, tokenFromUrl, 'newSecurePassword');
+```
+
+---
+
+## Relationship to other parts of the SDK
+
+| Concern | Where it lives |
+|---------|---------------|
+| End-user sign-in / register | `authKit` namespace (this doc) |
+| Admin Bearer token auth | Platform shell — not set by your app |
+| Per-user data storage | `userAppData` namespace — see [app-data-storage.md](app-data-storage.md) |
+| User identity in analytics | `userId` field on `analytics` and `interactions` calls |
+
+---
+
+## Further reading
+
+- [app-data-storage.md](app-data-storage.md) — storing user-specific data after login
+- [app-manifest.md](app-manifest.md) — `app.admin.json` setup questions for configuring `clientId`

package/docs/forms.md

@@ -0,0 +1,113 @@
+# SmartLinks Forms
+
+> Platform-managed form definitions and submissions. Covers the `form` data API (core SDK) and the `@proveanything/ui-forms` React package for schema-driven form UIs.
+
+---
+
+## Two layers
+
+| Layer | Package | What it does |
+|-------|---------|--------------|
+| **Forms data API** | `@proveanything/smartlinks` (`form` namespace) | CRUD for form definitions; stores submission schema |
+| **Forms UI** | `@proveanything/ui-forms` | React components that render a form definition, validate input, and submit |
+
+You can use the data API without the UI package (e.g. in an executor), but the UI package requires both.
+
+---
+
+## Forms data API (`form` namespace)
+
+The `form` namespace in the core SDK manages **form definitions** — the schema that describes fields, validation rules, and submission behaviour. This is an admin-side API.
+
+```ts
+import { form } from '@proveanything/smartlinks';
+
+// List all forms in a collection
+const forms = await form.list(collectionId, /* admin= */ true);
+
+// Get a specific form
+const myForm = await form.get(collectionId, formId);
+
+// Create a form (admin)
+const created = await form.create(collectionId, {
+  name: 'Warranty Registration',
+  fields: [
+    { id: 'name',    type: 'text',  label: 'Full name',       required: true },
+    { id: 'email',   type: 'email', label: 'Email address',   required: true },
+    { id: 'serial',  type: 'text',  label: 'Serial number',   required: true },
+    { id: 'receipt', type: 'file',  label: 'Proof of purchase' },
+  ],
+});
+
+// Update a form (admin)
+await form.update(collectionId, formId, { name: 'Warranty Registration v2' });
+
+// Delete a form (admin)
+await form.remove(collectionId, formId);
+```
+
+Form definitions are stored per-collection and referenced by `formId`.
+
+---
+
+## Forms UI (`@proveanything/ui-forms`)
+
+`@proveanything/ui-forms` provides React components that consume a form definition from the API and render a complete, accessible, validated form.
+
+Install: `npm install @proveanything/ui-forms`
+
+### Rendering a form
+
+```tsx
+import { SmartForm } from '@proveanything/ui-forms';
+
+// Fetches the form definition and renders it
+<SmartForm
+  collectionId={collectionId}
+  formId={formId}
+  onSubmit={async (values) => {
+    // handle submission — e.g. create an app.records entry or send via comms
+  }}
+/>
+```
+
+### Headless usage
+
+```tsx
+import { useFormDefinition, FormRenderer } from '@proveanything/ui-forms';
+
+const { fields, isLoading } = useFormDefinition(collectionId, formId);
+
+// Render fields yourself using the definition
+```
+
+---
+
+## Common patterns
+
+### Warranty / registration forms
+
+Define the form in `app.admin.json` setup or via the admin API. On the public widget, render with `<SmartForm>` and on submit create an `app.records` entry:
+
+```ts
+onSubmit={async (values) => {
+  await app.records.create(collectionId, appId, {
+    recordType: 'warranty_registration',
+    ref: `proof:${proofId}`,
+    data: values,
+  });
+}}
+```
+
+### Competition / feedback forms
+
+Same pattern — use `<SmartForm>` for capture and write to `app.records` or trigger an `interactions.appendEvent` on submit.
+
+---
+
+## Further reading
+
+- [app-objects.md](app-objects.md) — `app.records` for storing submissions
+- [app-data-storage.md](app-data-storage.md) — choosing the right storage model
+- [interactions.md](interactions.md) — firing events on form submission
+- [comms.md](comms.md) — sending confirmation emails after submission

package/docs/overview.md

@@ -64,6 +64,10 @@ The SmartLinks SDK (`@proveanything/smartlinks`) includes comprehensive document
 | **Liquid Templates** | `docs/liquid-templates.md` | Dynamic content rendering with LiquidJS |
 | **Iframe Responder** | `docs/iframe-responder.md` | Iframe communication and proxy mode internals |
 | **AI Guide Template** | `docs/ai-guide-template.md` | Template for creating `public/ai-guide.md` — customise per app |
+| **Forms** | `docs/forms.md` | Form definitions, schema-driven rendering, submission patterns |
+| **Auth Kit** | `docs/auth-kit.md` | End-user sign-in: email/password, magic links, phone OTP, Google OAuth |
+| **Records Admin Pattern** | `docs/records-admin-pattern.md` | Standard pattern for per-product/facet/variant/batch admin UIs |
+| **UI Utils** | `docs/ui-utils.md` | `@proveanything/smartlinks-utils-ui` — React shells, hooks, and primitives for records-based apps |
 
 ---