@proveanything/smartlinks 2.1.3 → 2.1.4

package/dist/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.3  |  Generated: 2026-10-26T21:00:54.277Z
+Version: 2.1.4  |  Generated: 2026-10-28T12:35:09.709Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2713,6 +2713,7 @@ interface AppFunctionAgentExposure {
   description?: string;
   input?: Record<string, any>;
   approval?: 'auto' | 'require';
+  audience?: Array<'app' | 'public' | 'assistant'>;
 }
 ```
 
@@ -3051,10 +3052,29 @@ interface AppManifest {
   data?: AppDataDeclaration;
   headless?: AppHeadlessDeclaration;
   connector?: AppConnectorDeclaration;
+  assistant?: AppAssistantDeclaration;
   [key: string]: any;
 }
 ```
 
+**AppAssistantFile** (interface)
+```typescript
+interface AppAssistantFile {
+  name: string;
+  description?: string;
+  file: string;
+}
+```
+
+**AppAssistantDeclaration** (interface)
+```typescript
+interface AppAssistantDeclaration {
+  skills?: AppAssistantFile[];
+  knowledge?: AppAssistantFile[];
+  preview?: string;
+}
+```
+
 **ConnectorConnectionField** (interface)
 ```typescript
 interface ConnectorConnectionField {

package/dist/docs/agent-tools.md

@@ -44,7 +44,8 @@ needs to call it — a description and an input schema:
           "title": "Create an FAQ entry",
           "description": "Add a question/answer to this collection's FAQ. Use when the user asks to add or draft an FAQ.",
           "input": { /* JSON Schema for the arguments the agent supplies as event.body */ },
-          "approval": "auto"        // auto | require  (require = human confirmation before the call)
+          "approval": "auto",       // auto | require  (require = human confirmation before the call)
+          "audience": ["app"]       // optional: app | public | assistant — where it is offered (absent = everywhere)
         }
       }
     ]
@@ -103,6 +104,10 @@ Identical to server functions — nothing new to reason about:
 - **`visibility`** — who may call (admin/public).
 - **`authority`** — whose identity `ctx.sl` carries (`caller` vs `collection`).
 - **`capabilities`** — least-privilege, capped even when elevated.
+- **`agent.audience`** — where the tool is offered: `'app'` (the app's own agent runs, admin surface),
+  `'public'` (public assistants), `'assistant'` (the Studio assistant, the admin's agent —
+  [assistant-apps.md](assistant-apps.md)). Absent = everywhere the function's visibility allows. An
+  assistant-only tool declares `["assistant"]` and never joins an in-app or public run.
 - **`agent.approval: "require"`** — the agent must get human confirmation before invoking (use for
   destructive or public-facing actions).
 

package/dist/docs/app-manifest.md

@@ -460,6 +460,30 @@ lists it and draws its connect form and settings, and the integration engine cal
 functions (`testConnection`, `describeTarget`, `sample`, `fetch`, `shape`, `serialize`, `send`). It adapts the provider's format; core does each customer's mapping. The full
 contract is in the **[Connectors guide](connectors.md)**.
 
+#### `assistant`
+
+What the **Studio assistant** (the admin's own agent) knows about this app: skills and knowledge files
+shipped with the build and loaded into its box on demand, and an optional page that renders a planned
+change set before it is applied.
+
+```jsonc
+"assistant": {
+  "skills": [
+    { "name": "theme", "description": "Changing the Hub's colours, fonts or logo", "file": "assistant/skills/theme.md" },
+    { "name": "pages", "description": "Adding, ordering and editing pages and the menu", "file": "assistant/skills/pages.md" }
+  ],
+  "knowledge": [
+    { "name": "settings-schema", "description": "JSON Schema of the hub settings group", "file": "assistant/knowledge/settings.schema.json" }
+  ],
+  "preview": "/admin/preview?changeSet={id}"
+}
+```
+
+The files live under `public/assistant/` and ship with every release like any other static file. The
+assistant sees one line per skill (its description) and reads the file only when the job calls for it,
+so a big app can carry many skills at no cost to the conversation. Full guide, including what a skill
+should say and how the assistant changes config with undo: **[assistant-apps.md](assistant-apps.md)**.
+
 ---
 
 ## `app.admin.json`

package/dist/docs/assistant-apps.md

@@ -0,0 +1,168 @@
+# The Studio assistant and your app
+
+SmartLinks admins have **one assistant**: an agent that works for the signed-in admin on one
+collection, with the admin's own authority, from a chat in Studio. It reads and changes data through
+the SmartLinks API, every write is a **change set** the admin can see and undo, and the things that
+can't be undone (deleting, sending, calling out, publishing, spending) wait for the admin's "Allow".
+
+This page is for app authors: how the assistant learns what your app is, how it is set up, and what it
+can do for the admin — without you building a chat of your own. Your app declares three things:
+
+| What | Where | Status |
+|---|---|---|
+| **Skills and knowledge** — plain-words procedures for the admin side, and the facts they need | `assistant` block in `app.manifest.json`, files under `public/assistant/` | this page |
+| **Tools** — logic the assistant should call rather than reimplement | server functions with an `agent` block (`audience: ["assistant"]` for assistant-only) | [agent-tools.md](agent-tools.md) |
+| **Setup** — questions, config schema, how to save | `app.admin.json` + `ai-guide.md` | [app-manifest.md](app-manifest.md#appadminjson) |
+
+An app with none of these still works with the assistant: it can read the app's records and config
+and change them through change sets. The declarations make it *good* at your app.
+
+## The `assistant` block
+
+```jsonc
+// app.manifest.json
+"assistant": {
+  "skills": [
+    { "name": "setup",  "description": "First-time setup of the FAQ app: categories, tone, who answers", "file": "assistant/skills/setup.md" },
+    { "name": "content", "description": "Adding, editing, ordering and retiring questions and answers",  "file": "assistant/skills/content.md" }
+  ],
+  "knowledge": [
+    { "name": "config-schema", "description": "JSON Schema of the app's config document", "file": "assistant/knowledge/config.schema.json" },
+    { "name": "examples",      "description": "Three worked examples of good FAQ content",   "file": "assistant/knowledge/examples.md" }
+  ],
+  "preview": "/admin/preview?changeSet={id}"
+}
+```
+
+The files sit in `public/assistant/` in your project and ship with every release like any other static
+file (they are read from the release's CDN folder, on the channel the collection runs your app on).
+
+### How they are loaded
+
+When an admin opens a chat, the assistant's box gets the **index** of every installed app's skills: one
+line each, the description. Nothing else. A skill's body, and the knowledge files it names, are read
+only when the assistant decides the job needs them. Twenty apps with three skills each cost the
+conversation about sixty lines. So: write several focused skills rather than one long one, and spend
+care on the description — it is how the assistant decides to open the file.
+
+### Writing a skill
+
+A skill is a markdown file: what this area of your app is for, what each setting means, how to read and
+change it, what a good result looks like, what to check afterwards. Write it for a capable colleague who
+has never seen your app. The assistant works through the SmartLinks API with a small CLI (`sl`), so say
+things in those terms:
+
+```markdown
+---
+name: faq-content
+description: Adding, editing, ordering and retiring questions and answers in the FAQ app
+---
+# FAQ content
+
+Questions live as app records of type `question` (`sl get app/faq/records recordType=question`).
+Fields: `data.question`, `data.answer` (markdown), `data.category` (one of the categories in the app's
+config, `sl get app/faq` → `categories[]`), `data.order` (ascending), `status` (`published` | `draft`).
+
+## Adding questions
+Plan one change set per batch: items `{ "op": "create", "entity": "record", "appId": "faq",
+"data": { "recordType": "question", "data": { … }, "status": "draft" } }`. Match on `data.question`
+(case-insensitive) before creating, so a re-run updates instead of duplicating.
+
+## A good answer
+Two to five sentences, plain words, no marketing. Link to a product page when one exists
+(`/p/<collectionId>/<productId>`). Never invent policy: if the answer depends on something the admin
+hasn't said (returns window, delivery areas), ask.
+
+## Check afterwards
+`sl get app/faq/records recordType=question status=draft` — read three back and make sure the
+category is one that exists.
+```
+
+The frontmatter is optional; when it is missing, the manifest entry's `name` and `description` are used.
+Keep a skill under a few hundred lines; put long reference material in knowledge files and name them.
+
+### Knowledge
+
+Knowledge files are what the skills refer to: the schema of your config document, record shapes, worked
+examples, a glossary of your app's words. The assistant reads them when a skill points at them (each
+skill is told where the app's knowledge files are).
+
+**Generate the schema, don't write it.** If your config is typed (a TypeScript interface, a zod schema),
+produce the JSON Schema at build time (`ts-json-schema-generator`, `zod-to-json-schema`) into
+`public/assistant/knowledge/`. A hand-written schema drifts the first week.
+
+## Tools: when a skill is not enough
+
+Nearly every admin action is a read or a patch of config or records, and the assistant does those
+itself. Give it a **tool** only when a step can't be an API call it makes on its own:
+
+- logic that lives in your code (validate a layout, render a page from a design direction, compute
+  something from your data model),
+- a write that must be atomic across several objects,
+- anything that needs your app's secrets.
+
+A tool is an http server function with an `agent` block
+([agent-tools.md](agent-tools.md)); the assistant calls it as
+`sl post app/<appId>/functions/<name> '{ … }'`, under the function's own visibility, authority and
+capabilities. Set `"audience": ["assistant"]` to keep an assistant-only tool out of your in-app and
+public agent runs:
+
+```jsonc
+{
+  "name": "applyDesignDirection",
+  "trigger": { "type": "http" },
+  "visibility": "admin",
+  "authority": "caller",
+  "capabilities": ["sl:settings:write"],
+  "agent": {
+    "tool": true,
+    "title": "Apply a design direction",
+    "description": "Rewrites the theme, fonts and layout of the hub to match a named direction.",
+    "input": { "type": "object", "properties": { "direction": { "type": "string" } }, "required": ["direction"] },
+    "audience": ["assistant"]
+  }
+}
+```
+
+A tool that changes config should **return the patch, not apply it**, so the assistant can put it in a
+change set and the admin keeps undo. Tools that act directly are fine for reads and computations.
+
+## How the assistant changes your config
+
+Your config document (`SL.appConfiguration`, `sl get app/<appId>`) and the collection's settings
+groups (`sl get settings/<group>`) are changed through change-set items:
+
+```jsonc
+{ "op": "update", "entity": "appConfig", "id": "<appId>", "data": { "theme": { "accent": "#0a7" } } }
+{ "op": "update", "entity": "appConfig", "id": "<appId>", "scope": { "productId": "p1" }, "data": { … } }
+{ "op": "update", "entity": "settings",  "id": "hub", "data": { "pages": { "about": { … } } } }
+```
+
+Saves deep-merge, as your own admin UI's saves do (nested objects merge, arrays replace). The whole
+document before the change is kept, so **undo puts it back exactly**. Say in your skills which keys
+are arrays, so the assistant sends the whole array when it changes one element.
+
+### Preview before apply
+
+A planned change set can be rendered before it is applied. The API gives, for every document a set
+touches, the live document and the document as it would become:
+
+```
+GET /admin/collection/:collectionId/assistant/changesets/:id/preview
+→ { id, status, targets: [ { entity, id, scope?, before, after, ops } ] }
+```
+
+Declare `assistant.preview` — a page of your admin surface that takes `{id}`, calls that endpoint
+with the admin's session, and renders `targets[].after` as your app would render the live config. The
+Studio panel then shows "Preview" on the change set, and the admin sees the result before saying yes.
+
+## Checklist
+
+- `assistant.skills[]`: several focused skills with descriptions that say when they apply.
+- `assistant.knowledge[]`: the config schema generated from your types; record shapes; examples.
+- Every skill says which fields are arrays, what to match on before creating, what to check after.
+- Logic the assistant can't reproduce: a server function with `agent.tool` and `audience: ["assistant"]`,
+  returning a patch for config changes.
+- `assistant.preview` when your app has a visual surface worth seeing before a change lands.
+- `ai-guide.md` still describes first-time setup for the setup wizard; the assistant reads it too when
+  an app declares no skills.

package/dist/openapi.yaml

@@ -20138,6 +20138,14 @@ components:
           enum:
             - auto
             - require
+        audience:
+          type: array
+          items:
+            type: string
+            enum:
+              - app
+              - public
+              - assistant
       required:
         - tool
     AppManifestFunctions:
@@ -20635,6 +20643,8 @@ components:
           $ref: "#/components/schemas/AppHeadlessDeclaration"
         connector:
           $ref: "#/components/schemas/AppConnectorDeclaration"
+        assistant:
+          $ref: "#/components/schemas/AppAssistantDeclaration"
       required:
         - name
         - version
@@ -20642,6 +20652,31 @@ components:
         - function
         - files
         - components
+    AppAssistantFile:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        file:
+          type: string
+      required:
+        - name
+        - file
+    AppAssistantDeclaration:
+      type: object
+      properties:
+        skills:
+          type: array
+          items:
+            $ref: "#/components/schemas/AppAssistantFile"
+        knowledge:
+          type: array
+          items:
+            $ref: "#/components/schemas/AppAssistantFile"
+        preview:
+          type: string
     ConnectorConnectionField:
       type: object
       properties:

package/dist/types/appManifest.d.ts

@@ -349,6 +349,13 @@ export interface AppFunctionAgentExposure {
      * the autonomous server-side loop (they'd otherwise run unconfirmed).
      */
     approval?: 'auto' | 'require';
+    /**
+     * Where the tool is offered. `'app'` = the app's own agent runs (admin surface), `'public'` = public
+     * assistants, `'assistant'` = the Studio assistant (the admin's agent, docs/assistant-apps.md).
+     * Absent = everywhere the function's visibility allows. An assistant-only tool (logic the assistant
+     * needs that lives in your code) declares `['assistant']` and never shows in an in-app or public run.
+     */
+    audience?: Array<'app' | 'public' | 'assistant'>;
 }
 /** The `functions` block in `app.manifest.json`. Presence means the app ships server functions. */
 export interface AppManifestFunctions {
@@ -941,8 +948,52 @@ export interface AppManifest {
      * @see AppConnectorDeclaration · docs/connectors.md
      */
     connector?: AppConnectorDeclaration;
+    /**
+     * What the Studio assistant (the admin's agent) knows about this app: skills and knowledge files
+     * shipped with the build and loaded into its box on demand, and an optional page that renders a
+     * planned change set. See docs/assistant-apps.md. @see AppAssistantDeclaration
+     */
+    assistant?: AppAssistantDeclaration;
     [key: string]: any;
 }
+/** One skill or knowledge file the app ships for the assistant. */
+export interface AppAssistantFile {
+    /** Short id, unique within the app (`theme`, `pages`, `settings-schema`). */
+    name: string;
+    /**
+     * One line: what it covers and when to reach for it. For a skill this is what the assistant sees
+     * before deciding to read the file, so say when it applies ("Changing the Hub's colours, fonts or
+     * logo"). A knowledge file's description says what is in it.
+     */
+    description?: string;
+    /**
+     * Path of the file in the published build, relative to the app's root (`public/` in the project):
+     * `assistant/skills/theme.md`. Markdown for skills; markdown or JSON (a JSON Schema) for knowledge.
+     */
+    file: string;
+}
+/** The `assistant` block in `app.manifest.json`. */
+export interface AppAssistantDeclaration {
+    /**
+     * Skills: plain-words procedures for one area of the app's admin side — what the settings mean,
+     * which calls read and change them, what a good result looks like, what to check. Several for a big
+     * app (identity and theme; pages and navigation; domains and SEO). A skill file may start with
+     * YAML frontmatter (`name`, `description`); if it doesn't, these entries supply it.
+     */
+    skills?: AppAssistantFile[];
+    /**
+     * Knowledge the skills refer to: the settings schema (generate it from your config types — never
+     * by hand), object definitions, worked examples, a glossary. Loaded only when a skill reaches for it.
+     */
+    knowledge?: AppAssistantFile[];
+    /**
+     * A page of the app that renders a PLANNED change set over the live config, so the admin can see a
+     * change before it is applied. `{id}` is replaced with the change-set id; the page reads
+     * `GET /admin/collection/:cid/assistant/changesets/:id/preview` and renders `targets[].after`.
+     * Relative to the app's admin surface, e.g. `"/admin/preview?changeSet={id}"`.
+     */
+    preview?: string;
+}
 /** One field of a connector's "Connect" form. */
 export interface ConnectorConnectionField {
     /** Key in the installation's connection settings (non-secret fields) — `name` for a secret too. */

package/docs/API_SUMMARY.md

@@ -1,6 +1,6 @@
 # Smartlinks API Summary
 
-Version: 2.1.3  |  Generated: 2026-10-26T21:00:54.277Z
+Version: 2.1.4  |  Generated: 2026-10-28T12:35:09.709Z
 
 This is a concise summary of all available API functions and types.
 
@@ -2713,6 +2713,7 @@ interface AppFunctionAgentExposure {
   description?: string;
   input?: Record<string, any>;
   approval?: 'auto' | 'require';
+  audience?: Array<'app' | 'public' | 'assistant'>;
 }
 ```
 
@@ -3051,10 +3052,29 @@ interface AppManifest {
   data?: AppDataDeclaration;
   headless?: AppHeadlessDeclaration;
   connector?: AppConnectorDeclaration;
+  assistant?: AppAssistantDeclaration;
   [key: string]: any;
 }
 ```
 
+**AppAssistantFile** (interface)
+```typescript
+interface AppAssistantFile {
+  name: string;
+  description?: string;
+  file: string;
+}
+```
+
+**AppAssistantDeclaration** (interface)
+```typescript
+interface AppAssistantDeclaration {
+  skills?: AppAssistantFile[];
+  knowledge?: AppAssistantFile[];
+  preview?: string;
+}
+```
+
 **ConnectorConnectionField** (interface)
 ```typescript
 interface ConnectorConnectionField {

package/docs/agent-tools.md

@@ -44,7 +44,8 @@ needs to call it — a description and an input schema:
           "title": "Create an FAQ entry",
           "description": "Add a question/answer to this collection's FAQ. Use when the user asks to add or draft an FAQ.",
           "input": { /* JSON Schema for the arguments the agent supplies as event.body */ },
-          "approval": "auto"        // auto | require  (require = human confirmation before the call)
+          "approval": "auto",       // auto | require  (require = human confirmation before the call)
+          "audience": ["app"]       // optional: app | public | assistant — where it is offered (absent = everywhere)
         }
       }
     ]
@@ -103,6 +104,10 @@ Identical to server functions — nothing new to reason about:
 - **`visibility`** — who may call (admin/public).
 - **`authority`** — whose identity `ctx.sl` carries (`caller` vs `collection`).
 - **`capabilities`** — least-privilege, capped even when elevated.
+- **`agent.audience`** — where the tool is offered: `'app'` (the app's own agent runs, admin surface),
+  `'public'` (public assistants), `'assistant'` (the Studio assistant, the admin's agent —
+  [assistant-apps.md](assistant-apps.md)). Absent = everywhere the function's visibility allows. An
+  assistant-only tool declares `["assistant"]` and never joins an in-app or public run.
 - **`agent.approval: "require"`** — the agent must get human confirmation before invoking (use for
   destructive or public-facing actions).
 

package/docs/app-manifest.md

@@ -460,6 +460,30 @@ lists it and draws its connect form and settings, and the integration engine cal
 functions (`testConnection`, `describeTarget`, `sample`, `fetch`, `shape`, `serialize`, `send`). It adapts the provider's format; core does each customer's mapping. The full
 contract is in the **[Connectors guide](connectors.md)**.
 
+#### `assistant`
+
+What the **Studio assistant** (the admin's own agent) knows about this app: skills and knowledge files
+shipped with the build and loaded into its box on demand, and an optional page that renders a planned
+change set before it is applied.
+
+```jsonc
+"assistant": {
+  "skills": [
+    { "name": "theme", "description": "Changing the Hub's colours, fonts or logo", "file": "assistant/skills/theme.md" },
+    { "name": "pages", "description": "Adding, ordering and editing pages and the menu", "file": "assistant/skills/pages.md" }
+  ],
+  "knowledge": [
+    { "name": "settings-schema", "description": "JSON Schema of the hub settings group", "file": "assistant/knowledge/settings.schema.json" }
+  ],
+  "preview": "/admin/preview?changeSet={id}"
+}
+```
+
+The files live under `public/assistant/` and ship with every release like any other static file. The
+assistant sees one line per skill (its description) and reads the file only when the job calls for it,
+so a big app can carry many skills at no cost to the conversation. Full guide, including what a skill
+should say and how the assistant changes config with undo: **[assistant-apps.md](assistant-apps.md)**.
+
 ---
 
 ## `app.admin.json`

package/docs/assistant-apps.md

@@ -0,0 +1,168 @@
+# The Studio assistant and your app
+
+SmartLinks admins have **one assistant**: an agent that works for the signed-in admin on one
+collection, with the admin's own authority, from a chat in Studio. It reads and changes data through
+the SmartLinks API, every write is a **change set** the admin can see and undo, and the things that
+can't be undone (deleting, sending, calling out, publishing, spending) wait for the admin's "Allow".
+
+This page is for app authors: how the assistant learns what your app is, how it is set up, and what it
+can do for the admin — without you building a chat of your own. Your app declares three things:
+
+| What | Where | Status |
+|---|---|---|
+| **Skills and knowledge** — plain-words procedures for the admin side, and the facts they need | `assistant` block in `app.manifest.json`, files under `public/assistant/` | this page |
+| **Tools** — logic the assistant should call rather than reimplement | server functions with an `agent` block (`audience: ["assistant"]` for assistant-only) | [agent-tools.md](agent-tools.md) |
+| **Setup** — questions, config schema, how to save | `app.admin.json` + `ai-guide.md` | [app-manifest.md](app-manifest.md#appadminjson) |
+
+An app with none of these still works with the assistant: it can read the app's records and config
+and change them through change sets. The declarations make it *good* at your app.
+
+## The `assistant` block
+
+```jsonc
+// app.manifest.json
+"assistant": {
+  "skills": [
+    { "name": "setup",  "description": "First-time setup of the FAQ app: categories, tone, who answers", "file": "assistant/skills/setup.md" },
+    { "name": "content", "description": "Adding, editing, ordering and retiring questions and answers",  "file": "assistant/skills/content.md" }
+  ],
+  "knowledge": [
+    { "name": "config-schema", "description": "JSON Schema of the app's config document", "file": "assistant/knowledge/config.schema.json" },
+    { "name": "examples",      "description": "Three worked examples of good FAQ content",   "file": "assistant/knowledge/examples.md" }
+  ],
+  "preview": "/admin/preview?changeSet={id}"
+}
+```
+
+The files sit in `public/assistant/` in your project and ship with every release like any other static
+file (they are read from the release's CDN folder, on the channel the collection runs your app on).
+
+### How they are loaded
+
+When an admin opens a chat, the assistant's box gets the **index** of every installed app's skills: one
+line each, the description. Nothing else. A skill's body, and the knowledge files it names, are read
+only when the assistant decides the job needs them. Twenty apps with three skills each cost the
+conversation about sixty lines. So: write several focused skills rather than one long one, and spend
+care on the description — it is how the assistant decides to open the file.
+
+### Writing a skill
+
+A skill is a markdown file: what this area of your app is for, what each setting means, how to read and
+change it, what a good result looks like, what to check afterwards. Write it for a capable colleague who
+has never seen your app. The assistant works through the SmartLinks API with a small CLI (`sl`), so say
+things in those terms:
+
+```markdown
+---
+name: faq-content
+description: Adding, editing, ordering and retiring questions and answers in the FAQ app
+---
+# FAQ content
+
+Questions live as app records of type `question` (`sl get app/faq/records recordType=question`).
+Fields: `data.question`, `data.answer` (markdown), `data.category` (one of the categories in the app's
+config, `sl get app/faq` → `categories[]`), `data.order` (ascending), `status` (`published` | `draft`).
+
+## Adding questions
+Plan one change set per batch: items `{ "op": "create", "entity": "record", "appId": "faq",
+"data": { "recordType": "question", "data": { … }, "status": "draft" } }`. Match on `data.question`
+(case-insensitive) before creating, so a re-run updates instead of duplicating.
+
+## A good answer
+Two to five sentences, plain words, no marketing. Link to a product page when one exists
+(`/p/<collectionId>/<productId>`). Never invent policy: if the answer depends on something the admin
+hasn't said (returns window, delivery areas), ask.
+
+## Check afterwards
+`sl get app/faq/records recordType=question status=draft` — read three back and make sure the
+category is one that exists.
+```
+
+The frontmatter is optional; when it is missing, the manifest entry's `name` and `description` are used.
+Keep a skill under a few hundred lines; put long reference material in knowledge files and name them.
+
+### Knowledge
+
+Knowledge files are what the skills refer to: the schema of your config document, record shapes, worked
+examples, a glossary of your app's words. The assistant reads them when a skill points at them (each
+skill is told where the app's knowledge files are).
+
+**Generate the schema, don't write it.** If your config is typed (a TypeScript interface, a zod schema),
+produce the JSON Schema at build time (`ts-json-schema-generator`, `zod-to-json-schema`) into
+`public/assistant/knowledge/`. A hand-written schema drifts the first week.
+
+## Tools: when a skill is not enough
+
+Nearly every admin action is a read or a patch of config or records, and the assistant does those
+itself. Give it a **tool** only when a step can't be an API call it makes on its own:
+
+- logic that lives in your code (validate a layout, render a page from a design direction, compute
+  something from your data model),
+- a write that must be atomic across several objects,
+- anything that needs your app's secrets.
+
+A tool is an http server function with an `agent` block
+([agent-tools.md](agent-tools.md)); the assistant calls it as
+`sl post app/<appId>/functions/<name> '{ … }'`, under the function's own visibility, authority and
+capabilities. Set `"audience": ["assistant"]` to keep an assistant-only tool out of your in-app and
+public agent runs:
+
+```jsonc
+{
+  "name": "applyDesignDirection",
+  "trigger": { "type": "http" },
+  "visibility": "admin",
+  "authority": "caller",
+  "capabilities": ["sl:settings:write"],
+  "agent": {
+    "tool": true,
+    "title": "Apply a design direction",
+    "description": "Rewrites the theme, fonts and layout of the hub to match a named direction.",
+    "input": { "type": "object", "properties": { "direction": { "type": "string" } }, "required": ["direction"] },
+    "audience": ["assistant"]
+  }
+}
+```
+
+A tool that changes config should **return the patch, not apply it**, so the assistant can put it in a
+change set and the admin keeps undo. Tools that act directly are fine for reads and computations.
+
+## How the assistant changes your config
+
+Your config document (`SL.appConfiguration`, `sl get app/<appId>`) and the collection's settings
+groups (`sl get settings/<group>`) are changed through change-set items:
+
+```jsonc
+{ "op": "update", "entity": "appConfig", "id": "<appId>", "data": { "theme": { "accent": "#0a7" } } }
+{ "op": "update", "entity": "appConfig", "id": "<appId>", "scope": { "productId": "p1" }, "data": { … } }
+{ "op": "update", "entity": "settings",  "id": "hub", "data": { "pages": { "about": { … } } } }
+```
+
+Saves deep-merge, as your own admin UI's saves do (nested objects merge, arrays replace). The whole
+document before the change is kept, so **undo puts it back exactly**. Say in your skills which keys
+are arrays, so the assistant sends the whole array when it changes one element.
+
+### Preview before apply
+
+A planned change set can be rendered before it is applied. The API gives, for every document a set
+touches, the live document and the document as it would become:
+
+```
+GET /admin/collection/:collectionId/assistant/changesets/:id/preview
+→ { id, status, targets: [ { entity, id, scope?, before, after, ops } ] }
+```
+
+Declare `assistant.preview` — a page of your admin surface that takes `{id}`, calls that endpoint
+with the admin's session, and renders `targets[].after` as your app would render the live config. The
+Studio panel then shows "Preview" on the change set, and the admin sees the result before saying yes.
+
+## Checklist
+
+- `assistant.skills[]`: several focused skills with descriptions that say when they apply.
+- `assistant.knowledge[]`: the config schema generated from your types; record shapes; examples.
+- Every skill says which fields are arrays, what to match on before creating, what to check after.
+- Logic the assistant can't reproduce: a server function with `agent.tool` and `audience: ["assistant"]`,
+  returning a patch for config changes.
+- `assistant.preview` when your app has a visual surface worth seeing before a change lands.
+- `ai-guide.md` still describes first-time setup for the setup wizard; the assistant reads it too when
+  an app declares no skills.

package/openapi.yaml

@@ -20138,6 +20138,14 @@ components:
           enum:
             - auto
             - require
+        audience:
+          type: array
+          items:
+            type: string
+            enum:
+              - app
+              - public
+              - assistant
       required:
         - tool
     AppManifestFunctions:
@@ -20635,6 +20643,8 @@ components:
           $ref: "#/components/schemas/AppHeadlessDeclaration"
         connector:
           $ref: "#/components/schemas/AppConnectorDeclaration"
+        assistant:
+          $ref: "#/components/schemas/AppAssistantDeclaration"
       required:
         - name
         - version
@@ -20642,6 +20652,31 @@ components:
         - function
         - files
         - components
+    AppAssistantFile:
+      type: object
+      properties:
+        name:
+          type: string
+        description:
+          type: string
+        file:
+          type: string
+      required:
+        - name
+        - file
+    AppAssistantDeclaration:
+      type: object
+      properties:
+        skills:
+          type: array
+          items:
+            $ref: "#/components/schemas/AppAssistantFile"
+        knowledge:
+          type: array
+          items:
+            $ref: "#/components/schemas/AppAssistantFile"
+        preview:
+          type: string
     ConnectorConnectionField:
       type: object
       properties:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",