@uidu/skills 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uidu/skills",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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:
 
@@ -80,14 +80,14 @@ reports `does not support <verb>` when it doesn't. Config resolves **flags → e
 
 ## 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 +111,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 +132,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 +174,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 +297,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 +374,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 +418,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 +517,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 +589,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 +643,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