@uidu/skills 0.5.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uidu/skills",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Agent skills for the uidu SDK — installable via the open agent skills ecosystem (skills.sh).",
   "license": "MIT",
   "author": "uidu",

package/skills/uidu/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: uidu
-description: Use when building on the uidu platform — a public website or an app that runs inside uidu (a custom app in a Space or workspace); reading CMS pages, events, stories, donations, help center, forms; rendering WYSIWYG content; scaffolding projects; OR provisioning/authoring uidu content (create/update/delete) from the terminal via the @uidu/cli (`uidu`). Triggers on any task involving uidu, the @uidu/client SDK, @uidu/react bindings, or the uidu CLI.
+description: Use when building on the uidu platform — a public website or an app that runs inside uidu (a custom app in a Space or workspace); reading CMS pages, events, stories, donations, help center, forms, or the workspace's own data (goals/OKRs, contacts, deals, people); rendering WYSIWYG content; scaffolding projects; OR provisioning/authoring uidu content (create/update/delete) from the terminal via the @uidu/cli (`uidu`). Triggers on any task involving uidu, the @uidu/client SDK, @uidu/react bindings, or the uidu CLI.
 license: MIT
 metadata:
   author: uidu
-  version: "0.5.0"
+  version: '0.6.0'
 ---
 
 # uidu SDK
@@ -13,7 +13,7 @@ The uidu SDK is a TypeScript GraphQL toolkit for building websites and apps powe
 
 - **`@uidu/client`** — framework-agnostic GraphQL client. Safe for server-side use (RSC, route handlers, server actions, scripts).
 - **`@uidu/app-bridge`** — the browser half of a custom app: the handshake with the uidu page that frames it, and its short-lived session token. Only for apps that run inside uidu.
-- **`@uidu/react`** — React hooks (`useUiduClient`, `useQuery`, `useFields`, `toText`, `useUiduApp`) and components (`<UiduAppProvider>`, `<PageBlocks>`, `<BlockRenderer>`, `<RichText>`, `<DynamicForm>`). That list is the **complete** public surface — there is no `useForm`, `usePage` or `useChannel`; for anything else, call a `@uidu/client` function.
+- **`@uidu/react`** — React hooks (`useUiduClient`, `useQuery`, `useFields`, `toText`, `useUiduApp`) and components (`<UiduAppProvider>`, `<PageBlocks>`, `<BlockRenderer>`, `<RichText>`, `<DynamicForm>`). That list is the **complete** public surface — there is no `useForm`, `usePage` or `useChannel`; for anything else, call a `@uidu/client` function. `@uidu/client` has one for each entity uidu already holds (goals, contacts, deals, people, events… — see [Workspace data](#workspace-data)): look there before writing a query or creating a Model.
 
 `@uidu/api.js` is a legacy bridge package and is **deprecated** — use `@uidu/react` directly.
 
@@ -31,12 +31,12 @@ Use this skill when the user is:
 
 ## Package Map
 
-| Package | When to use | Notes |
-|---|---|---|
-| `@uidu/client` | Server-side queries (RSC, server actions, scripts) | Framework-agnostic |
-| `@uidu/react` | React hooks, providers, and components | Some hooks are client-only |
-| `@uidu/app-bridge` | An app that runs inside uidu (custom app) | Browser only; in React use `<UiduAppProvider>` |
-| `@uidu/api.js` | **Do not use for new code.** | Deprecated; re-exports `@uidu/react` |
+| Package            | When to use                                        | Notes                                          |
+| ------------------ | -------------------------------------------------- | ---------------------------------------------- |
+| `@uidu/client`     | Server-side queries (RSC, server actions, scripts) | Framework-agnostic                             |
+| `@uidu/react`      | React hooks, providers, and components             | Some hooks are client-only                     |
+| `@uidu/app-bridge` | An app that runs inside uidu (custom app)          | Browser only; in React use `<UiduAppProvider>` |
+| `@uidu/api.js`     | **Do not use for new code.**                       | Deprecated; re-exports `@uidu/react`           |
 
 Install:
 
@@ -72,22 +72,62 @@ uidu workspace credentials --json                  # api key + secret
 uidu create my-app -t events                       # delegates to create-uidu-app
 ```
 
-Entities: `events, stories, donations, courses, forms, contacts, deals, employees,
-bookings, calls, campaigns, kb-collections, kb-articles, channel` (read) and
-`tasks, notes, spaces` (write-only). Not every verb exists for every entity — the CLI
-reports `does not support <verb>` when it doesn't. Config resolves **flags → env
-(`UIDU_*`) → `~/.uidu/config.json`** (written by `uidu login`).
+Entities and the verbs each supports (generated from the CLI's registry — a verb marked `—`
+fails with `does not support <verb>`):
+
+<!-- BEGIN sdk:cli-resources — generated by scripts/sdk-manifest.mjs, do not edit -->
+
+| Entity                | list | get | create | update | delete |
+| --------------------- | :--: | :-: | :----: | :----: | :----: |
+| `events`              |  ✓   |  ✓  |   ✓    |   ✓    |   —    |
+| `attendances`         |  —   |  —  |   ✓    |   —    |   —    |
+| `stories`             |  ✓   |  ✓  |   ✓    |   ✓    |   —    |
+| `donations`           |  ✓   |  ✓  |   ✓    |   ✓    |   ✓    |
+| `courses`             |  ✓   |  ✓  |   ✓    |   ✓    |   ✓    |
+| `forms`               |  ✓   |  ✓  |   ✓    |   ✓    |   ✓    |
+| `contacts`            |  ✓   |  ✓  |   ✓    |   —    |   ✓    |
+| `deals`               |  ✓   |  ✓  |   ✓    |   ✓    |   —    |
+| `goals`               |  ✓   |  ✓  |   —    |   ✓    |   —    |
+| `timeframes`          |  ✓   |  —  |   —    |   —    |   —    |
+| `employees`           |  ✓   |  —  |   ✓    |   ✓    |   —    |
+| `employments`         |  —   |  —  |   ✓    |   ✓    |   ✓    |
+| `offices`             |  ✓   |  —  |   —    |   —    |   —    |
+| `roles`               |  ✓   |  —  |   —    |   —    |   —    |
+| `ccnls`               |  ✓   |  —  |   ✓    |   —    |   —    |
+| `bookings`            |  ✓   |  ✓  |   —    |   —    |   —    |
+| `calls`               |  ✓   |  ✓  |   —    |   —    |   —    |
+| `jobs`                |  ✓   |  ✓  |   —    |   —    |   —    |
+| `applications`        |  ✓   |  —  |   ✓    |   —    |   —    |
+| `campaigns`           |  ✓   |  ✓  |   —    |   —    |   —    |
+| `kb-collections`      |  ✓   |  ✓  |   ✓    |   ✓    |   ✓    |
+| `kb-articles`         |  ✓   |  ✓  |   ✓    |   ✓    |   ✓    |
+| `channel`             |  ✓   |  ✓  |   ✓    |   ✓    |   ✓    |
+| `time-clocks`         |  —   |  —  |   ✓    |   —    |   —    |
+| `compensations`       |  —   |  —  |   ✓    |   ✓    |   ✓    |
+| `tasks`               |  —   |  —  |   ✓    |   ✓    |   ✓    |
+| `benefits`            |  —   |  —  |   ✓    |   —    |   —    |
+| `benefit-enrollments` |  —   |  —  |   ✓    |   —    |   —    |
+| `notes`               |  —   |  —  |   ✓    |   ✓    |   ✓    |
+| `projects`            |  ✓   |  —  |   —    |   —    |   —    |
+| `sites`               |  —   |  —  |   ✓    |   —    |   —    |
+| `spaces`              |  —   |  —  |   ✓    |   ✓    |   ✓    |
+
+<!-- END sdk:cli-resources -->
+
+Anything the backend exposes as a tool-flagged action but the CLI has no noun for yet:
+`uidu tools call <ActionKey> --attributes '<json>'` (associations as GlobalIDs). Config resolves
+**flags → env (`UIDU_*`) → `~/.uidu/config.json`** (written by `uidu login`).
 
 ## Who the app acts for — one rule
 
-What an app *looks like* (landing page, blog, dashboard, booking tool) changes nothing.
+What an app _looks like_ (landing page, blog, dashboard, booking tool) changes nothing.
 What changes the code is **who the request acts for**:
 
-| Operation | Auth | Where it runs |
-|---|---|---|
-| **Reads** for anyone (`get*` / `list*`, `<entity> list/get`) | `publicToken` | anywhere — server, CLI, **and the browser** |
-| **Writes** as the workspace (`create*` / `update*` / `delete*`, `<entity> create/update/delete`) | account **Bearer** (`apiKey`) | CLI and **server-side** only |
-| **Anything as the signed-in member**, inside uidu (a custom app) | session token from the host, over `@uidu/app-bridge` | **the browser only** |
+| Operation                                                                                        | Auth                                                 | Where it runs                               |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------- |
+| **Reads** for anyone (`get*` / `list*`, `<entity> list/get`)                                     | `publicToken`                                        | anywhere — server, CLI, **and the browser** |
+| **Writes** as the workspace (`create*` / `update*` / `delete*`, `<entity> create/update/delete`) | account **Bearer** (`apiKey`)                        | CLI and **server-side** only                |
+| **Anything as the signed-in member**, inside uidu (a custom app)                                 | session token from the host, over `@uidu/app-bridge` | **the browser only**                        |
 
 The write functions live in `@uidu/client`, so anything the CLI provisions you can also do
 from a Next.js server action / route handler / RSC. **Never put the account Bearer token in a
@@ -111,10 +151,13 @@ that person can do, and no more. It changes five things:
    needs a server credential uidu doesn't issue yet.
 3. **Treat the token as opaque.** Never decode it. The expiry comes with it, the bridge refreshes
    it, and `graphqlUrl` comes with it too: never build `https://<workspace>.uidu.org` from a slug.
-4. **Data goes in the app's own Models.** The session reaches the app's own Models, fields and
-   items through `node(id:)`, and the data-engine mutations. Everything else in the workspace comes
-   back as an error. Keep your data there rather than in a database of your own: it stays
-   searchable and permissioned in uidu.
+4. **Read what the workspace already has; keep only new data in the app's own Models.** The
+   session reaches the app's own Models, fields and items (`node(id:)` and the data-engine
+   mutations) and, read-only, the workspace's **goals and timeframes** (`listGoals`, `getGoal`,
+   `listTimeframes`) — those of the workspace and of the Space the app sits in. Everything else in
+   the workspace comes back as an error for now: see [Workspace data](#workspace-data) for which
+   entity is reachable from where. Keep the app's own data in Models rather than in a database of
+   your own: it stays searchable and permissioned in uidu.
    `listModelItems` reads uidu's **search index**, which catches up a moment after a write:
    after `createModelItem` / `deleteModelItem`, update your list from the mutation payload
    instead of re-listing, or the new item is missing. And load models once per app instance
@@ -129,24 +172,39 @@ import { useEffect, useState } from 'react';
 import { UiduAppProvider, useUiduApp } from '@uidu/react';
 import { DEFAULT_HOST_ORIGINS } from '@uidu/app-bridge';
 import {
-  createModelItem, ensureModel, listModelItems, toFieldValuesAttributes,
-  type ModelItem, type UiduClient,
+  createModelItem,
+  ensureModel,
+  listModelItems,
+  toFieldValuesAttributes,
+  type ModelItem,
+  type UiduClient,
 } from '@uidu/client';
 
 export function AppProvider({ children }: { children: React.ReactNode }) {
   // https://*.uidu.org by default; add a local uidu or a custom domain
-  return <UiduAppProvider hostOrigins={[...DEFAULT_HOST_ORIGINS]}>{children}</UiduAppProvider>;
+  return (
+    <UiduAppProvider hostOrigins={[...DEFAULT_HOST_ORIGINS]}>
+      {children}
+    </UiduAppProvider>
+  );
 }
 
 async function loadBookings(client: UiduClient, workspaceAppId: string) {
-  // interim: the app creates its own model on first load (install-time manifest comes later)
+  // interim: the app creates its own model on first load (install-time manifest comes later).
+  // Bookings of a room are data uidu has no place for — hence a Model. Goals, contacts or
+  // people already exist: read them (see Workspace data).
   const model = await ensureModel(client, {
     workspaceAppId,
     name: 'Booking',
     fields: [{ shortname: 'room', name: 'Room', kind: 'string' }],
   });
   await createModelItem(client, {
-    input: { attributes: { modelId: model.id, fieldValuesAttributes: toFieldValuesAttributes(model, { room: 'Blu' }) } },
+    input: {
+      attributes: {
+        modelId: model.id,
+        fieldValuesAttributes: toFieldValuesAttributes(model, { room: 'Blu' }),
+      },
+    },
   });
   return listModelItems(client, { modelId: model.id }); // item.fieldValuesByShortname.room
 }
@@ -156,19 +214,83 @@ export function Bookings() {
   const [items, setItems] = useState<ModelItem[]>([]);
 
   useEffect(() => {
-    if (app.status === 'ready') loadBookings(app.client, app.context.workspaceApp.id).then(setItems);
+    if (app.status === 'ready')
+      loadBookings(app.client, app.context.workspaceApp.id).then(setItems);
   }, [app]);
 
-  if (app.status === 'error') return <p>Open this app from uidu ({app.error.code})</p>; // NOT_EMBEDDED, TIMEOUT…
-  return <ul>{items.map((item) => <li key={item.id}>{item.fieldValuesByShortname?.room}</li>)}</ul>;
+  if (app.status === 'error')
+    return <p>Open this app from uidu ({app.error.code})</p>; // NOT_EMBEDDED, TIMEOUT…
+  return (
+    <ul>
+      {items.map((item) => (
+        <li key={item.id}>{item.fieldValuesByShortname?.room}</li>
+      ))}
+    </ul>
+  );
 }
 ```
 
+Field `kind`s for `ensureModel` (and `public/uidu.app.json`): `string` (one line), `text`
+(several lines), `number`, `currency`, `percent`, `date`, `datetime`, `checkbox`, `email`,
+`phone`, `url`, `rating`, `member` (a person of the workspace). `singleSelect` /
+`multipleSelect` need their options created too (`createFieldOption`) — prefer `string` unless
+the choices matter. uidu knows more (`attachments`, `linkedRecord`, `formula`, `progress`,
+`richText`…); leave them out unless the person asks for one.
+
 `app.context` carries `user`, `space`, `workspaceApp`, `locale`, `theme` and `accent` (the page's colour, to set as `--primary`). Outside React: `connect()` from
 `@uidu/app-bridge`, then `createClient(fromBridge(bridge))` from `@uidu/client`. Start a new
 one with `npm create uidu-app@latest my-app -- -t custom-app`: it declares its Models in
 `public/uidu.app.json` and sets `frame-ancestors` so only uidu can frame it.
 
+## Workspace data
+
+**A uidu workspace is not empty.** It already holds the organisation's goals, contacts, deals,
+people, events, courses… An app that asks for "a dashboard of the OKRs behind schedule" or "our
+open deals" is asking about data uidu has — read it. **Create a Model only for data uidu has no
+place for** (the app's own bookings, a checklist, a log). Copying existing records into a Model
+gives the person a second copy that drifts from the real one.
+
+| The workspace's…                       | Functions (`@uidu/client`)                                                | Inside a custom app        |
+| -------------------------------------- | ------------------------------------------------------------------------- | -------------------------- |
+| Goals / OKRs (key results = subgoals)  | `listGoals`, `getGoal`, `listTimeframes`; `updateGoal`                    | **read** (no `updateGoal`) |
+| Contacts, organisations                | `listContacts`, `getContact`; `createContact`                             | not yet                    |
+| Deals (CRM)                            | `listDeals`, `getDeal`; `createDeal`, `updateDeal`                        | not yet                    |
+| People (employees)                     | `listEmployees`, `getEmployee`, `listOffices`, `listCircles`, `listRoles` | not yet                    |
+| Tasks, notes                           | `updateTask`, `createTask`, `updateNote`, `createNote` (no list)          | not yet                    |
+| Events, courses, bookings, calendars   | `listEvents`, `listCourses`, `listBookings`, `listCalendars`, …           | not yet                    |
+| Forms, donations, stories, help center | see [Patterns by Scope](#patterns-by-scope)                               | not yet                    |
+| The app's own Models                   | `ensureModel`, `listModelItems`, `createModelItem`, …                     | read and write             |
+
+On a server with an account token (`apiKey`) every row works; "not yet" means a custom app's
+session token is refused for it. **When the data exists in uidu but is not reachable from a custom
+app yet, tell the person** — don't rebuild it in a Model. If the functions you need aren't in the
+table, look for `listX` / `getX` in `@uidu/client` before concluding they don't exist.
+
+### Goals (OKRs)
+
+An objective is a `Goal`; its key results are its `subgoals`; the period it runs over is its
+`timeframe` (`startDate`, `endDate`). `metricKind` is `number`, `percentage`, `currency`,
+`checkbox` or `subgoal` (measured by its key results); `status` is the owner's own judgement:
+`on_track`, `needs_attention`, `off_track`, `accomplished`.
+
+**Values are stored x100.** `initialValue`, `currentValue` and `targetValue` never hold the number
+a person typed, and `progress` is percent x100 (10000 = done). Use the helpers, don't divide by hand:
+
+```ts
+import { listGoals, goalValue, goalProgress, isGoalBehind } from '@uidu/client';
+
+const goals = await listGoals(app.client); // all of them, objectives and key results
+const objectives = goals.filter((g) => !g.parentId);
+const behind = objectives.filter((g) => isGoalBehind(g, { tolerance: 0.1 }));
+
+goalValue(goal, goal.targetValue); // 45 for a 45% target, 1200 for €1,200
+goalProgress(goal); // 0.45 — done fraction
+```
+
+`isGoalBehind` compares progress with the share of the timeframe already gone (`goalTimeElapsed`);
+show the goal's `status` next to it, it says something different. `updateGoal` takes raw values:
+`toGoalRaw(45)`. A goal's owner, members and activity are not readable from a custom app.
+
 ## Working transparently
 
 The user often can't tell what you're doing when you drive the CLI. Stay legible:
@@ -215,23 +337,66 @@ import { createClient } from '@uidu/client';
 export const uidu = createClient({
   workspace: process.env.UIDU_WORKSPACE ?? '',
   publicToken: process.env.UIDU_PUBLIC_TOKEN, // safe to expose
-  apiKey: process.env.UIDU_API_KEY,           // server-only secret
+  apiKey: process.env.UIDU_API_KEY, // server-only secret
 });
 ```
 
 Required environment:
 
-| Variable | Required | Notes |
-|---|---|---|
-| `UIDU_WORKSPACE` | yes | Your workspace slug (e.g. `acme`) |
-| `UIDU_PUBLIC_TOKEN` | no | Public read-only token, safe to expose |
-| `UIDU_API_KEY` | no | Server-only secret for privileged ops |
+| Variable            | Required | Notes                                  |
+| ------------------- | -------- | -------------------------------------- |
+| `UIDU_WORKSPACE`    | yes      | Your workspace slug (e.g. `acme`)      |
+| `UIDU_PUBLIC_TOKEN` | no       | Public read-only token, safe to expose |
+| `UIDU_API_KEY`      | no       | Server-only secret for privileged ops  |
 
 ## Patterns by Scope
 
-### CMS Pages
+### CMS Sites (new CMS)
 
-CMS pages are made of `pageBlocks`. Fetch a page server-side, pass blocks to `<PageBlocks>` with a component map keyed by the block's `shortname`:
+uidu has two CMS generations. **Sites** are the new one: a `Site` has page types (page-kind Models), pages (ModelItems of a page type) and, on each page, an ordered list of blocks (ModelItems of a block-kind Model). **Projects** (`getPage`/`listPages`, next section) are the legacy CMS — keep using them only for sites already deployed on a Project. Build new sites on Sites. Every read works with a `publicToken`, in RSC and in the browser.
+
+```tsx
+// src/app/[[...slug]]/page.tsx — Server Component
+import { getPageBySlug, getSiteByDomain, type SiteBlock } from '@uidu/client';
+import { notFound } from 'next/navigation';
+import { uidu } from '@/lib/uidu';
+
+const components: Record<string, React.ComponentType<{ block: SiteBlock }>> = {
+  Hero,
+  FAQ,
+};
+
+export default async function Page({
+  params,
+}: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const { slug = ['home'] } = await params;
+  const site = await getSiteByDomain(uidu, {
+    domain: process.env.SITE_DOMAIN!,
+  });
+  const page =
+    site &&
+    (await getPageBySlug(uidu, { siteId: site.id, slug: slug.join('/') }));
+  if (!page) notFound();
+  return page.blocks.map((block) => {
+    const Component = components[block.model.name ?? ''];
+    return Component ? <Component key={block.id} block={block} /> : null;
+  });
+}
+```
+
+- `getSiteByDomain(client, { domain })` / `getSite(client, { id })` — the Site (by id in previews, where there is no domain)
+- `getPageBySlug(client, { siteId, slug, includeDrafts? })` → `{ id, slug, model, fields, blocks: [{ id, model, fields, position }] }`, published only by default
+- `listSitePages(client, { siteId, pageType?, includeDrafts? })` — nav/sitemaps; published only, singletons excluded; `pageType` = Model id or name
+- `getSingletonBlock(client, { siteId, shortname })` — header/footer/nav
+- `fields` is already a `{ shortname: value }` map — no `useFields` needed.
+- Block kinds have a `shortname`, but `Model.shortname` isn't exposed by the API yet: key component maps on `block.model.name` for now.
+- Don't call the legacy `listPages`/`getPage` with a Site id — they read Projects only.
+
+### CMS Pages (legacy Projects)
+
+Legacy CMS pages are made of `pageBlocks`. Fetch a page server-side, pass blocks to `<PageBlocks>` with a component map keyed by the block's `shortname`:
 
 ```tsx
 // src/app/page.tsx — Server Component
@@ -249,10 +414,7 @@ export default async function HomePage() {
   if (!page) return <div>Not found</div>;
 
   return (
-    <PageBlocks
-      pageBlocks={page.pageBlocks}
-      components={{ Hero, Feature }}
-    />
+    <PageBlocks pageBlocks={page.pageBlocks} components={{ Hero, Feature }} />
   );
 }
 ```
@@ -296,19 +458,19 @@ const event = await getEvent(uidu, { id });
 
 Event fields:
 
-| Field | Notes |
-|---|---|
-| `event.id` | |
-| `event.name` | Display name |
-| `event.body` | WYSIWYG doc — render with `<RichText>` |
-| `event.cover` | Image URL (string) or null |
-| `event.description` | Plain string summary |
-| `event.instance.beginsAt` | ISO datetime of start |
-| `event.instance.finishesAt` | ISO datetime of end |
-| `event.instance.id` | Instance identifier |
-| `event.primaryAddress` | Location data |
-| `event.currentCapacity` | Numeric capacity |
-| `event.isPaidEvent` | Boolean |
+| Field                       | Notes                                  |
+| --------------------------- | -------------------------------------- |
+| `event.id`                  |                                        |
+| `event.name`                | Display name                           |
+| `event.body`                | WYSIWYG doc — render with `<RichText>` |
+| `event.cover`               | Image URL (string) or null             |
+| `event.description`         | Plain string summary                   |
+| `event.instance.beginsAt`   | ISO datetime of start                  |
+| `event.instance.finishesAt` | ISO datetime of end                    |
+| `event.instance.id`         | Instance identifier                    |
+| `event.primaryAddress`      | Location data                          |
+| `event.currentCapacity`     | Numeric capacity                       |
+| `event.isPaidEvent`         | Boolean                                |
 
 ### Stories (Blog)
 
@@ -395,10 +557,12 @@ later throws. `FieldValueAttributes` exposes no `value` key — `content` is the
 
 ```ts
 // ✅ Correct — every answer wrapped
-fieldValuesAttributes: [{ fieldId: 'f1', content: { value: 'hello@example.com' } }]
+fieldValuesAttributes: [
+  { fieldId: 'f1', content: { value: 'hello@example.com' } },
+];
 
 // ❌ Wrong — silently loses the answer
-fieldValuesAttributes: [{ fieldId: 'f1', content: 'hello@example.com' }]
+fieldValuesAttributes: [{ fieldId: 'f1', content: 'hello@example.com' }];
 ```
 
 It holds for **every** field kind, not just strings — `{ value: 42 }`, `{ value: true }`,
@@ -465,7 +629,9 @@ All `body` fields on Event, Story, DonationCampaign, etc. are structured documen
 ```tsx
 import { RichText } from '@uidu/react';
 
-{story.body != null && <RichText doc={story.body} />}
+{
+  story.body != null && <RichText doc={story.body} />;
+}
 ```
 
 The prop is `doc`, not `children`. The component handles paragraphs, headings, lists, links, and inline marks.
@@ -517,12 +683,12 @@ Or pick a template directly:
 npm create uidu-app@latest my-app -- -t events
 ```
 
-| Template | What it builds |
-|---|---|
-| `minimal` | CMS landing page with `PageBlocks` + Hero/Feature blocks |
-| `events` | Event listing + `/event/[id]` detail |
-| `stories` | Blog listing + `/story/[id]` detail (magazine layout) |
-| `donations` | Campaigns listing + `/campaign/[id]` detail with progress bars |
+| Template     | What it builds                                                                                   |
+| ------------ | ------------------------------------------------------------------------------------------------ |
+| `minimal`    | CMS landing page with `PageBlocks` + Hero/Feature blocks                                         |
+| `events`     | Event listing + `/event/[id]` detail                                                             |
+| `stories`    | Blog listing + `/story/[id]` detail (magazine layout)                                            |
+| `donations`  | Campaigns listing + `/campaign/[id]` detail with progress bars                                   |
 | `custom-app` | An app inside a uidu Space: `<UiduAppProvider>`, data in its own Models (`public/uidu.app.json`) |
 
 Every template ships with Next.js 16 App Router, Tailwind v4 and an `.env.example` (the CLI
@@ -530,6 +696,48 @@ offers to fill it in for you). The site templates add a configured `src/lib/uidu
 server-rendered listing + dynamic detail page; `custom-app` has no token to configure and
 reads everything in client components.
 
+## Full API Index
+
+Every `@uidu/client` function, by domain — generated from the source, so if a function isn't
+here it doesn't exist (yet). Domains marked "reads need Bearer" hold private data: a public token
+sees nothing. Per-function auth, signatures and descriptions: https://docs.uidu.org/docs/reference/client.
+
+<!-- BEGIN sdk:domain-index — generated by scripts/sdk-manifest.mjs, do not edit -->
+
+- **Client & utilities** — `createClient`, `fromBridge`, `normalizeFieldValueContent`, `normalizeFieldValuesAttributes`, `paginate`
+- **CMS — Sites** · CLI: `sites` — `createSite`, `getPageBySlug`, `getSingletonBlock`, `getSite`, `getSiteByDomain`, `listSitePages`
+- **CMS — Projects (legacy)** · CLI: `projects` — `createFieldValue`, `createPage`, `createPageBlock`, `createProject`, `getPage`, `getTemplate`, `listPages`, `listProjects`
+- **Models (custom data)** — `createField`, `createFieldOption`, `createModel`, `createModelItem`, `deleteField`, `deleteFieldOption`, `deleteFieldValue`, `deleteModelItem`, `ensureModel`, `getModel`, `getModelItem`, `listModelItems`, `listModels`, `toFieldValuesAttributes`, `updateField`, `updateFieldOption`, `updateFieldValue`, `updateModel`, `updateModelItem`
+- **Forms** · CLI: `forms` — `createForm`, `createFormResponse`, `deleteForm`, `getForm`, `listForms`, `updateForm`, `updateFormResponse`
+- **Events** · CLI: `events`, `attendances` — `createAttendance`, `createEvent`, `getEvent`, `listEvents`, `updateEvent`
+- **Calls** · CLI: `calls` — `getCall`, `listCalls`
+- **Jobs & applications** · CLI: `jobs`, `applications` — `completeApplication`, `createApplication`, `getJob`, `listApplications`, `listJobs`, `updateApplication`
+- **Donations** · CLI: `donations` — `createDonation`, `createDonationCampaign`, `deleteDonationCampaign`, `getDonationCampaign`, `listDonationCampaigns`, `updateDonationCampaign`
+- **Stories** · CLI: `stories` — `createStory`, `getStory`, `listStories`, `updateStory`
+- **Help center** · CLI: `channel` — `createChannel`, `deleteChannel`, `getChannel`, `listChannels`, `updateChannel`
+- **Knowledge base** · CLI: `kb-collections`, `kb-articles` — `createKbArticle`, `createKbCollection`, `deleteKbArticle`, `deleteKbCollection`, `getKbArticle`, `getKbCollection`, `listKbArticles`, `listKbCollections`, `updateKbArticle`, `updateKbCollection`
+- **Search** — `search`
+- **Courses** · CLI: `courses` — `createCourse`, `deleteCourse`, `getCourse`, `getEnrollment`, `getLecture`, `listCourses`, `listEnrollments`, `listLectures`, `updateCourse`
+- **Bookings & calendars** · reads need Bearer · CLI: `bookings` — `getBooking`, `getCalendar`, `getCalendarEvent`, `listBookings`, `listCalendarEvents`, `listCalendars`
+- **Campaigns** · reads need Bearer · CLI: `campaigns` — `getCampaign`, `listCampaigns`, `listEmailCampaigns`
+- **Contacts & deals** · reads need Bearer · CLI: `contacts`, `deals` — `createContact`, `createDeal`, `deleteContact`, `getContact`, `getDeal`, `listContacts`, `listDeals`, `updateDeal`
+- **Goals (OKRs)** · reads need Bearer · CLI: `goals`, `timeframes` — `getGoal`, `goalProgress`, `goalTimeElapsed`, `goalValue`, `isGoalBehind`, `listGoals`, `listTimeframes`, `toGoalRaw`, `updateGoal`
+- **People (HR)** · reads need Bearer · CLI: `employees`, `employments`, `offices`, `roles`, `ccnls`, `time-clocks`, `compensations`, `benefits`, `benefit-enrollments` — `contractEvents`, `createBenefit`, `createBenefitEnrollment`, `createCcnl`, `createCompensation`, `createEmployee`, `createEmployment`, `createTimeClock`, `deleteCompensation`, `deleteEmployment`, `getEmployee`, `listCcnls`, `listCircles`, `listEmployees`, `listEmploymentHistory`, `listKinds`, `listOffices`, `listRoles`, `terminateEmployment`, `updateCompensation`, `updateEmployee`, `updateEmployment`, `weekStartFor`
+- **Spaces, tasks & notes** · CLI: `tasks`, `notes`, `spaces` — `createNote`, `createSpace`, `createTask`, `deleteNote`, `deleteSpace`, `deleteTask`, `updateNote`, `updateSpace`, `updateTask`
+- **Provisioning & actions** — `createWorkspace`, `executeAction`, `generateWorkspaceApiCredentials`
+
+<!-- END sdk:domain-index -->
+
+`@uidu/react`:
+
+<!-- BEGIN sdk:react-surface — generated by scripts/sdk-manifest.mjs, do not edit -->
+
+- **Components:** `BlockRenderer` — Render exactly one block from a page's `pageBlocks` array, by shortname.; `DynamicForm` — Render a uidu form (from `getForm`, `call.form`, …) as HTML inputs and hand the parsed values to your `action`, typically a `createFormResponse` Server Action.; `PageBlocks` — Render a page's blocks in order, each with the component keyed by its shortname in `components`; blocks with no match render `fallback`, or nothing.; `RichText` — Render a Tiptap (ProseMirror) JSON document as React elements.; `UiduAppProvider` — Connects a custom app to the uidu page framing it (`@uidu/app-bridge`) and hands the tree its state through `useUiduApp`. Once connected, the children also sit inside a `<UiduProvider>` with a session-backed client, so `useUiduClient()` works as anywhere else.; `UiduProvider` — Provide a `UiduClient` to the tree, either a `client` you built or one made from `workspace`/`publicToken`/`endpoint`, plus an SWR fetcher backed by it.
+- **Hooks:** `useFields` — Normalize a `fieldValues` array into a `{ shortname: value }` map so blocks can access their fields by name without walking the GraphQL shape.; `useQuery` — Generic client-side data-fetching hook: runs `document` against the `UiduClient` from the nearest `<UiduProvider>` via SWR, so calls are cached and deduplicated by operation name + variables.; `useUidu` — The nearest `UiduProvider`'s `{ client, endpoint }`; throws outside a provider.; `useUiduApp` — The custom app's bridge state: `connecting`, `ready` or `error`.; `useUiduClient` — The `UiduClient` from the nearest `UiduProvider`; throws outside a provider.
+- **Utilities:** `formatSalaryRange` — Format a job's salary range (`salaryMin`/`salaryMax`) into a display string. Returns `null` when the job advertises no salary, so callers can hide the field. Handles open-ended ranges ("From …", "Up to …") and a single figure.; `getBlockShortname` — The shortname a page block is rendered by (its template block's, else its own), or null.; `toText` — Flatten any uidu field-content value into a plain string. Handles raw strings, numbers, Slate-style rich text nodes (`{ type, children }`, `{ text }`), arrays of nodes, and wrapper objects with a `value` field.
+
+<!-- END sdk:react-surface -->
+
 ## See Also
 
 - uidu docs: https://docs.uidu.org
@@ -537,3 +745,4 @@ reads everything in client components.
 - `@uidu/client`: https://github.com/uidu-org/api.js/tree/main/packages/client
 - `@uidu/react`: https://github.com/uidu-org/api.js/tree/main/packages/react
 - `create-uidu-app`: https://github.com/uidu-org/api.js/tree/main/packages/create-uidu-app
+- Machine-readable manifest of the whole SDK (exports, domains, auth, CLI verbs): https://github.com/uidu-org/api.js/blob/main/docs/sdk-manifest.json