@proveanything/smartlinks 2.1.3 → 2.1.5

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.5  |  Generated: 2026-10-30T13:51:55.292Z
 
 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.5  |  Generated: 2026-10-30T13:51:55.292Z
 
 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.5",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "type": "module",
   "main": "dist/index.js",

package/scripts/publish.mjs

@@ -18,6 +18,7 @@
 
 import { readFileSync, readdirSync, statSync, watch } from 'node:fs'
 import { join, relative, sep } from 'node:path'
+import { createHash } from 'node:crypto'
 
 const args = process.argv.slice(2)
 const flag = (name, def) => { const i = args.indexOf(name); return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : true) : def }
@@ -66,6 +67,69 @@ const BATCH_FILES = 150
 // through an API request, so no single file is ever too large to publish (e.g. a readable dev build).
 const DIRECT_BYTES = 4 * 1024 * 1024
 
+// A large bundle sends only what changed, and straight to storage (POST /publish/plan): the API compares
+// each file's MD5 with what the dev folder already holds and hands out an upload session for the rest, which
+// go up in parallel, never through the API. A site with 1,500 files, mostly images, sent all of them through
+// the API on every publish (about two minutes); a text fix now sends the few files the build changed.
+const PLAN_FILES = 500
+const PARALLEL_UPLOADS = 8
+const md5Of = (buf) => createHash('md5').update(buf).digest('base64')
+
+async function pool(items, size, fn) {
+  let i = 0
+  await Promise.all(Array.from({ length: Math.min(size, items.length) }, async () => {
+    while (i < items.length) { const k = i++; await fn(items[k]) }
+  }))
+}
+
+// PUT one file to its upload session; a failed upload asks for a fresh session and tries again (3 tries).
+async function putFile(path, buf, url, qs) {
+  let at = url
+  for (let attempt = 1; ; attempt++) {
+    const put = await fetch(at, { method: 'PUT', body: buf }).catch((e) => ({ ok: false, status: 0, text: async () => e.message }))
+    if (put.ok) return true
+    const why = `${put.status}: ${(await put.text().catch(() => '')).slice(0, 200)}`
+    if (attempt >= 3) { console.error(`❌ upload of ${path} failed (${why})`); return false }
+    const { res, b } = await post(`/publish/uploads${qs}`, { files: [{ path, size: buf.length }] })
+    if (!res.ok || !b.ok || !b.uploads || !b.uploads[0]) { console.error(`❌ upload of ${path} failed (${why}); no new upload session`); return false }
+    at = b.uploads[0].url
+  }
+}
+
+// → the paths now in the dev folder (unchanged + uploaded), null when this API has no plans yet (an older
+// API: the caller sends batches, as before), or false when an upload failed.
+async function publishByPlan(rest, qs) {
+  // Empty files can't take an upload session: they go in a batch (they cost nothing).
+  const planned = rest.filter(([, buf]) => buf.length > 0)
+  const have = []
+  const uploads = []
+  for (let i = 0; i < planned.length; i += PLAN_FILES) {
+    const part = planned.slice(i, i + PLAN_FILES)
+    const { res, b } = await post(`/publish/plan${qs}`, { files: part.map(([p, buf]) => ({ path: p, size: buf.length, md5: md5Of(buf) })) })
+    if (res.status === 404 && i === 0) return null
+    if (!res.ok || !b.ok) { reportFailure(res, b); return false }
+    have.push(...(b.have || []))
+    uploads.push(...(b.uploads || []))
+  }
+  const bytes = new Map(rest)
+  const sendBytes = uploads.reduce((n, u) => n + (bytes.get(u.path) || []).length, 0)
+  console.log(`📦 ${APP_ID}: ${planned.length} files — ${have.length} unchanged, ${uploads.length} to send (${(sendBytes / 1048576).toFixed(1)} MB, straight to storage)`)
+  let sent = 0
+  let failed = false
+  await pool(uploads, PARALLEL_UPLOADS, async (u) => {
+    if (failed) return
+    if (!(await putFile(u.path, bytes.get(u.path), u.url, qs))) { failed = true; return }
+    if (++sent % 100 === 0 || sent === uploads.length) console.log(`   ↑ ${sent}/${uploads.length}`)
+  })
+  if (failed) return false
+  const empty = rest.filter(([, buf]) => buf.length === 0)
+  if (empty.length) {
+    const { res, b } = await post(`/publish/files${qs}`, { files: toB64(empty) })
+    if (!res.ok || !b.ok) { reportFailure(res, b); return false }
+  }
+  return rest.map(([p]) => p)
+}
+
 // Big files → storage directly. Returns the paths uploaded, or null when the server has no direct
 // uploads yet (an older API: the caller falls back to batches).
 async function uploadDirect(entries, qs) {
@@ -122,37 +186,45 @@ async function publishOnce() {
   if (totalBytes <= BATCH_BYTES && entries.length <= BATCH_FILES) {
     finalBody = { files: toB64(entries) } // small bundle: one request, as before
   } else {
-    // Large bundle: upload everything except the manifest in batches, then send the manifest last —
-    // the server only registers the release once every referenced file is confirmed uploaded.
+    // Large bundle: everything except the manifest first (only what changed, straight to storage; or in
+    // batches on an older API), then the manifest last — the server only registers the release once every
+    // referenced file is confirmed uploaded.
     const rest = entries.filter(([p]) => p !== 'app.manifest.json').sort((a, b) => b[1].length - a[1].length)
-    const big = rest.filter(([, buf]) => buf.length >= DIRECT_BYTES)
-    let direct = []
-    if (big.length) {
-      const done = await uploadDirect(big, qs)
-      if (done === false) { if (WATCH) return false; process.exit(1) }
-      if (done) direct = done
-      else console.warn('   ⚠︎ this SmartLinks API has no direct uploads yet — sending big files in batches')
-    }
-    const viaBatches = rest.filter(([p]) => !direct.includes(p))
-    const batches = []
-    let cur = [], curBytes = 0
-    for (const e of viaBatches) {
-      if (cur.length && (curBytes + e[1].length > BATCH_BYTES || cur.length >= BATCH_FILES)) { batches.push(cur); cur = []; curBytes = 0 }
-      if (e[1].length > BATCH_BYTES) console.warn(`   ⚠︎ ${e[0]} is ${(e[1].length / 1048576).toFixed(1)} MB — larger than one request allows; the server will likely reject it`)
-      cur.push(e); curBytes += e[1].length
-    }
-    if (cur.length) batches.push(cur)
-    console.log(`📦 ${APP_ID}: ${(totalBytes / 1048576).toFixed(1)} MB in ${entries.length} files — ${direct.length ? `${direct.length} sent directly, ` : ''}${batches.length} batch(es)`)
-    for (let i = 0; i < batches.length; i++) {
-      const { res, b } = await post(`/publish/files${qs}`, { files: toB64(batches[i]) })
-      if (!res.ok || !b.ok) {
-        reportFailure(res, b)
-        if (WATCH) return false
-        process.exit(1)
+    const byPlan = await publishByPlan(rest, qs)
+    if (byPlan === false) { if (WATCH) return false; process.exit(1) }
+    if (byPlan) {
+      finalBody = { files: toB64([['app.manifest.json', files['app.manifest.json']]]), uploaded: byPlan }
+    } else {
+      console.warn('   ⚠︎ this SmartLinks API has no publish plans yet — sending every file in batches')
+      const big = rest.filter(([, buf]) => buf.length >= DIRECT_BYTES)
+      let direct = []
+      if (big.length) {
+        const done = await uploadDirect(big, qs)
+        if (done === false) { if (WATCH) return false; process.exit(1) }
+        if (done) direct = done
+        else console.warn('   ⚠︎ this SmartLinks API has no direct uploads yet — sending big files in batches')
+      }
+      const viaBatches = rest.filter(([p]) => !direct.includes(p))
+      const batches = []
+      let cur = [], curBytes = 0
+      for (const e of viaBatches) {
+        if (cur.length && (curBytes + e[1].length > BATCH_BYTES || cur.length >= BATCH_FILES)) { batches.push(cur); cur = []; curBytes = 0 }
+        if (e[1].length > BATCH_BYTES) console.warn(`   ⚠︎ ${e[0]} is ${(e[1].length / 1048576).toFixed(1)} MB — larger than one request allows; the server will likely reject it`)
+        cur.push(e); curBytes += e[1].length
+      }
+      if (cur.length) batches.push(cur)
+      console.log(`📦 ${APP_ID}: ${(totalBytes / 1048576).toFixed(1)} MB in ${entries.length} files — ${direct.length ? `${direct.length} sent directly, ` : ''}${batches.length} batch(es)`)
+      for (let i = 0; i < batches.length; i++) {
+        const { res, b } = await post(`/publish/files${qs}`, { files: toB64(batches[i]) })
+        if (!res.ok || !b.ok) {
+          reportFailure(res, b)
+          if (WATCH) return false
+          process.exit(1)
+        }
+        console.log(`   ↑ batch ${i + 1}/${batches.length} (${batches[i].length} files)`)
       }
-      console.log(`   ↑ batch ${i + 1}/${batches.length} (${batches[i].length} files)`)
+      finalBody = { files: toB64([['app.manifest.json', files['app.manifest.json']]]), uploaded: rest.map(([p]) => p) }
     }
-    finalBody = { files: toB64([['app.manifest.json', files['app.manifest.json']]]), uploaded: rest.map(([p]) => p) }
   }
 
   const { res, b } = await post(`/publish${qs}`, finalBody)