@collective-intelligence/extensions-sdk-backend 0.3.1 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,34 +1,38 @@
1
1
  # Platform architecture
2
2
 
3
- The parts of Collective Intelligence, the three integration models, and how a demo package moves from build to install.
3
+ The parts of Collective Intelligence, the three integration models, and how a package moves from build to install.
4
4
 
5
- A demo built on Collective Intelligence (CI) produces two artifacts and points both at a CI deployment that already runs. The first is an extension package that CI installs into an Organization. The second is a web app that runs on your own host and calls CI. Your team does not run the backend, its workers, Compute, Media, the Dashboard or Studio; the CI deployment provides all of them.
5
+ A customer solution built on Collective Intelligence (CI) usually produces two artifacts and points both at a CI deployment that already runs. The first is an extension package that CI installs into an Organization. The second is a web app that runs on your own host and calls CI. Your team does not run the backend, its workers, Compute, Media, the Dashboard or Studio; the CI deployment provides all of them.
6
6
 
7
7
  ## Tenant and Organization
8
8
 
9
- A tenant is one CI deployment and its top-level security boundary, so one installation of CI has exactly one tenant. An Organization is a data and access partition inside a tenant, and each Organization belongs to one tenant. For a demo, the customer is almost always an Organization inside an existing tenant. Do not use "tenant" as another word for the customer.
9
+ A tenant is one CI deployment and its top-level security boundary, so each CI deployment has exactly one tenant. An Organization is a data and access partition inside a tenant, and each Organization belongs to one tenant. The customer is almost always an Organization inside an existing tenant. Do not use "tenant" as another word for the customer.
10
10
 
11
- Platform-wide choices live at tenant scope: tenant users, oversight of Organizations, feature flags, AI model availability and defaults, maintenance and monitoring. Most of what a demo touches lives at Organization scope: users and Groups, installed packages, connector instances, Knowledge, tools, Skills, workflows and Studio apps.
11
+ Platform-wide choices live at tenant scope: tenant users, oversight of Organizations, feature flags, AI model availability and defaults, maintenance and monitoring. Most of what a customer solution touches lives at Organization scope: users and Groups, installed packages, connector instances, Knowledge, tools, Skills, workflows and Studio apps.
12
+
13
+ The Organizations of one tenant share the CI deployment: its processes, its core database, its queues and, by default, its file storage. CI keeps their data apart by Organization. Every record, file and job of an Organization carries its Organization, and the backend checks that Organization on each operation. Some stores also give each Organization its own storage area. Managed Datasets live in a separate database with one schema per Organization, and the vectors that search uses sit in one partition per Organization. Files get one storage prefix per Organization, and a Tenant admin can point an Organization at its own bucket or container.
14
+
15
+ Each scope has its own admin. A Tenant admin runs the CI deployment: the Tenant admin creates Organizations, manages tenant users, AI models and the file storage of each Organization, and turns feature flags on per Organization. CI gives a Tenant admin the tenant profile in every Organization, so a Tenant admin can also configure any Organization. An Organization admin runs one Organization: the Organization admin installs packages, invites users, adds them to Groups and grants them any Access Profile except the tenant profiles. An account with a tenant role is never a member of an Organization, and a member of an Organization never holds a tenant role. [Access](access.md) explains Access Profiles and Access Grants.
12
16
 
13
17
  CI never infers either scope. Code installed inside CI receives the tenant and Organization from CI on each call. An external application names the tenant URL in its configuration and the Organization in each data operation.
14
18
 
15
19
  ## Surfaces
16
20
 
17
- | Surface | Who uses it | What it does for a demo |
18
- | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
19
- | Dashboard | Administrators | Configures the Organization: users, Groups, access, packages, connectors, Knowledge schemas, agents, Skills, tools, workflows, external applications and MCP. |
20
- | Studio | End users | Desktop app where people chat with agents, open Studio apps, fill agent forms and read Documents. Each tenant has an install page with a Connect Studio button, so nobody types a backend URL. |
21
- | Backend API | Dashboard, Studio, CLI, your app | Serves every HTTP route. Its OpenAPI document is the authority that the SDKs and the CLI are generated from. |
22
- | Workers | The backend | Background workers run long jobs, and interactive workers run the agent and tool work that users wait for. |
23
- | Compute | The backend | Runs transcription, transcoding and conversion from a queue. Each capability has its own slots, so a long transcode does not block transcription. |
24
- | Media | Browsers | Serves file bytes and image transforms from URLs that the backend signs. No file byte passes through a backend endpoint. |
21
+ | Surface | Who uses it | What it does |
22
+ | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
23
+ | Dashboard | Organization admins, and Tenant admins for the tenant area | Configures the Organization: users, Groups, access, packages, connectors, Knowledge schemas, agents, Skills, tools, workflows, external applications and MCP. Its tenant area configures the CI deployment: tenant users, Organizations, AI models, Studio releases, maintenance and monitoring. |
24
+ | [Studio](../ai/studio.md) | End users | Desktop app where people chat with agents, open Studio apps, fill agent forms and read Documents. Each Organization has an install page with a Connect Studio button, so nobody types a backend URL. |
25
+ | Backend API | Dashboard, Studio, CLI, your app | Serves every HTTP route. Its OpenAPI document is the authority that the SDKs and the CLI are generated from. |
26
+ | Workers | The backend | Background workers run long jobs, and interactive workers run the agent and tool work that users wait for. |
27
+ | Compute | The backend | Runs transcription, transcoding and conversion from a queue. Each capability has its own slots, so a long transcode does not block transcription. |
28
+ | Media | Browsers | Serves file bytes and image transforms from URLs that the backend signs. No file byte passes through a backend endpoint. |
25
29
 
26
- Your code never calls Compute. For files, the backend decides who can see each one and signs its URL, and Media only checks the signature. A principal can fetch a file if, and only if, it can see the item the file is attached to.
30
+ Your code never calls Compute. For files, the backend decides who can see each one and signs its URL, and Media only checks the signature. A principal can fetch a file if, and only if, it can see the item the file is attached to. [Infrastructure](../develop/infrastructure.md) lists the runtime resources behind these surfaces and the deployment blueprints.
27
31
 
28
32
  > **Note:** Some Dashboard areas, such as Organization onboarding, Knowledge setup and
29
- > apps setup, start disabled. A tenant administrator turns them on per
30
- > Organization with feature flags. If a demo Organization lacks a menu item,
31
- > check the tenant feature flags first.
33
+ > apps setup, start disabled. A Tenant admin turns them on per Organization with
34
+ > feature flags. If an Organization lacks a menu item, check the tenant feature
35
+ > flags first.
32
36
 
33
37
  ## Three ways to integrate
34
38
 
@@ -69,10 +73,14 @@ Choose the direction by asking who owns the records. When CI owns them, as with
69
73
 
70
74
  A package in CI distributes platform capabilities, and code is only one part of it. One package can carry Knowledge domains and schemas, connectors, tools, Skills, agents, workflows, Studio apps and widgets, Groups, Access Profiles and external application registrations. A customer solution package usually holds the shared pieces for one Organization's initiative. One package per Organization is a convention, and CI does not enforce it.
71
75
 
72
- CI's own built-in features ship as packages with the same manifest, bundle and runtime contracts, so a demo package uses the same mechanism as the platform's core packages.
76
+ CI's own built-in features ship as packages with the same manifest, bundle and runtime contracts, so a customer solution package uses the same mechanism as the platform's core packages.
73
77
 
74
78
  Items that a package declares belong to the package installation. A Declared Studio App, for example, is read-only in the Studio builder and changes only when you deploy a new release of its package. Ordinary saves in the Dashboard never install or change packages.
75
79
 
80
+ Each declared item sets a lifecycle with two fields. With `deployMode: "upsert"`, every deploy writes the declared state again, so a Dashboard edit returns to the declared value on the next deploy. With `deployMode: "init_only"`, CI creates the item when it is absent and keeps later edits. With `readonly: true`, the Dashboard shows the item and refuses edits, and it tells the user to update the package instead. Where possible, declare items with `{ deployMode: "upsert", readonly: true }` and use the Dashboard only to view them. The package then stays the one source of the Organization's setup, and a deploy to a new Organization creates the same setup. CI declares its own built-in Access Profiles this way. Use `init_only` with `readonly: false` only for an item that an Organization admin must change after install. The template does this for the grant to its Sales reps and for its convert-lead workflow.
81
+
82
+ Some setup stays outside a package. A package declares Groups but never their members, and it creates no Organization memberships, so an Organization admin adds users after install. A Tenant admin creates the Organization itself. If you need to configure something that a package cannot declare yet, ask the Collective team to add the declaration, and avoid configuring it by hand in the Dashboard.
83
+
76
84
  ### Package lifecycle
77
85
 
78
86
  ```mermaid
@@ -131,7 +139,7 @@ The Overview and Lead intake pages of the template work with no CI at all, becau
131
139
 
132
140
  ## Where data lives
133
141
 
134
- Knowledge holds durable business concepts such as customers, leads and assets as records that follow declared schemas, and it is what agents, Skills, workflows and Studio apps query. Datasets hold typed, high-volume records such as financial measures or sensor readings, which Knowledge does not fit. Documents are a separate surface for files and Document Collections, with their own page in Studio. Read [Knowledge](../data/knowledge.md), [Datasets](../data/datasets.md) and [Connectors](../data/connectors.md) for the details.
142
+ CI has three kinds of Data resources: Knowledge holds durable business records that follow declared schemas, Datasets hold typed, high-volume records, and Documents holds files in Document Collections. The [Data resources overview](../data/index.md) compares them, and [Knowledge](../data/knowledge.md), [Datasets](../data/datasets.md), [Documents](../data/documents.md) and [Connectors](../data/connectors.md) give the details.
135
143
 
136
144
  ## Next pages
137
145
 
@@ -139,4 +147,5 @@ Knowledge holds durable business concepts such as customers, leads and assets as
139
147
  - [Access](access.md): Access Profiles, Access Grants and Max Privileges.
140
148
  - [Extensions](../develop/extensions.md): Write the package that CI installs.
141
149
  - [External apps](../develop/external-apps.md): Build the web app that calls CI.
150
+ - [Infrastructure](../develop/infrastructure.md): The runtime resources of a CI deployment and its deployment blueprints.
142
151
  - [Template](../template/index.md): Start from the `next-effect-app` template.
@@ -1,15 +1,15 @@
1
1
  # Entrypoints
2
2
 
3
- The ways people, apps and agents enter CI at runtime, and the package subpaths that demo code imports.
3
+ The ways people, apps and agents enter CI at runtime, and the package subpaths that your code imports.
4
4
 
5
- In this guide, "entrypoint" has two meanings. Runtime entrypoints are the ways people, apps and agents enter CI: the Dashboard, Studio, the CLI, the HTTP API, MCP, workflow triggers and Realtime. Code entrypoints are the package subpaths that demo code imports, both from the CI SDKs and from the template's own packages.
5
+ In this guide, "entrypoint" has two meanings. Runtime entrypoints are the ways people, apps and agents enter CI: the Dashboard, Studio, the CLI, the HTTP API, MCP, workflow triggers and Realtime. Code entrypoints are the package subpaths that your code imports, both from the CI SDKs and from the template's own packages.
6
6
 
7
7
  ## Runtime entrypoints
8
8
 
9
9
  ```mermaid
10
10
  flowchart LR
11
- admin["Administrator"] --> dashboard["Dashboard"]
12
- user["End user"] --> studio["Studio"]
11
+ admin["Organization or Tenant admin"] --> dashboard["Dashboard"]
12
+ user["Organization member"] --> studio["Studio"]
13
13
  dev["Developer or pipeline"] --> cli["ci CLI"]
14
14
  script["Script with an API key"] --> http["HTTP API"]
15
15
  browser["Your browser code"] --> bff["Your BFF"]
@@ -31,22 +31,41 @@ flowchart LR
31
31
  http -->|"signed calls"| gateway["Your Gateway"]
32
32
  ```
33
33
 
34
- | Entrypoint | Who uses it | Authenticates with | Typical demo use |
35
- | --------------------- | ---------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- |
36
- | Dashboard | Administrators | Organization sign-in, including SSO | Install the package, add users to Groups, manage access, rotate an app secret |
37
- | Studio | End users | CI sign-in through the tenant's Connect Studio link | Chat with agents, open a Studio app, use a widget |
38
- | CLI (`ci`) | Developers and pipelines | CLI Session from `ci login`, or `CI_MANAGEMENT_TOKEN` | Build and deploy the package, create API keys |
39
- | HTTP API | Scripts and unattended runs | API key of a service principal, limited by Max Privileges | Script demo setup, run agent conversations without a person |
40
- | External applications | Your web app's server | OAuth client credentials, member tokens, server credentials | The template's CRM pages and lead conversion |
41
- | MCP | AI clients and assistants | Bearer session token or API key | Let an assistant run Skills and workflows |
42
- | Workflow triggers | Other systems, the clock, apps, record changes | Depends on the trigger; the webhook trigger uses an API key | Start a workflow from a webhook or on a schedule |
43
- | Realtime | Your browser, through your BFF | Single-use ticket that your server requests | Refresh lists when a record changes |
34
+ | Entrypoint | Who uses it | Authenticates with | Typical use |
35
+ | --------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
36
+ | Dashboard | Organization admins, Tenant admins and Organization operators | Organization sign-in, including SSO | Install the package, add users to Groups, manage access, rotate an app secret |
37
+ | Studio | Organization members who hold Studio access | Password, one-time code or the Organization's SSO | Chat with agents, open a Studio app, use a widget |
38
+ | CLI (`ci`) | Developers and pipelines | CLI Session from `ci login`, or `CI_MANAGEMENT_TOKEN` | Build and deploy the package, create API keys |
39
+ | HTTP API | Scripts and unattended runs | API key of a service principal, limited by Max Privileges | Script demo setup, run agent conversations without a person |
40
+ | External applications | Your web app's server | Client secret for sign-in, user access tokens, a Server Credential | The template's CRM pages and lead conversion |
41
+ | MCP | AI clients and assistants | Session token or API key, CI OAuth token, or MCP Profile token | Let an assistant run Skills and workflows |
42
+ | Workflow triggers | Other systems, the clock, apps, record changes | Depends on the trigger | Start a workflow from a webhook or on a schedule |
43
+ | Realtime | Your browser, through your BFF | Single-use ticket that your server requests | Refresh lists when a record changes |
44
+
45
+ The [credentials](#credentials) section lists every credential, who holds it and how long it lasts.
44
46
 
45
47
  ### Dashboard and Studio
46
48
 
47
- Administrators configure an Organization in the Dashboard. Its Organization admin area holds accounts, Groups, Access Profiles, capabilities, Max Privileges, access explanations, packages and a Developers area; separate areas hold AI (agents, Skills, tools, workflows, approvals), Apps (Studio, external applications, MCP), datasets and Documents. The Developers area has tabs for the CLI, connections, service principals and variables, and its CLI tab shows the exact `ci login` command for the Organization.
49
+ Each surface has one entry capability: `dashboard` for the Dashboard, `studio` for Studio and `mcp` for MCP. A person who does not hold a surface's entry capability cannot open that surface, whatever else they hold. Every Organization stores six built-in, read-only Access Profiles, and the Dashboard shows them as roles:
50
+
51
+ | Built-in profile | Dashboard | Studio and MCP | Data |
52
+ | --------------------- | ---------------------------------------------------------- | -------------- | ------------------------------------------------------ |
53
+ | Organization admin | Every page; changes everything | Yes | Reads and writes where the core default policy applies |
54
+ | Organization operator | Every page except onboarding and transfer; changes nothing | Yes | Reads Knowledge where the core default policy applies |
55
+ | Studio user | No entry | Yes | Only what a policy or another profile opens |
56
+ | Knowledge reader | No entry by itself | No by itself | Reads Knowledge where no package policy applies |
57
+ | Tenant admin | Every page, plus the tenant area | Yes | Reads and writes every schema |
58
+ | Tenant operator | Every page and the tenant area; changes nothing | No | Reads every schema |
59
+
60
+ A view-only role depends on the surface. In the Dashboard it is the Organization operator, who reads every page and changes nothing. In Studio it is the Studio user, who chats with agents and uses Studio apps but cannot open the Dashboard. Knowledge reader is an add-on: give it next to another profile when that person must read Knowledge records.
61
+
62
+ An Organization admin manages one Organization and can grant every profile except the two tenant profiles. A Tenant admin holds the tenant profile in every Organization. Only a Tenant admin opens the tenant area (Organizations, users, AI models, maintenance, monitoring and tenant settings), creates Organizations, grants the tenant profiles and acts in any Organization. A Tenant operator reads the same pages and changes nothing.
48
63
 
49
- End users work in Studio. They chat with agents, open Studio apps, fill agent forms and read Documents. A package can ship a whole Studio app, which CI creates and publishes on install; the template's Sales desk is one. A Studio widget never holds CI credentials. It calls CI through the Studio API client from `@collective-intelligence/extensions-sdk-frontend-react/studio-api`, which Studio binds to its own signed-in transport, so each request runs with the current user's permissions.
64
+ Entering Studio opens no data by itself. A Studio user reads no Knowledge record and no Document until a package policy, the Knowledge reader profile or a custom profile opens it. An Organization operator already reads Knowledge records through the core administration policy, on every schema where a package has not replaced that policy, and reads no Document until a policy opens it. [Access](access.md) explains policies and grants, and [Studio](../ai/studio.md) covers what members do there.
65
+
66
+ The Dashboard shows each section only to a person who holds its administration capability at read. An Organization admin sees the Organization admin area with accounts, Groups, Access Profiles, capabilities, Max Privileges, access explanations, packages and a Developers area; separate areas hold AI (agents, Skills, tools, workflows, approvals), Apps (Studio, external applications, MCP), datasets and Documents. The Developers area has tabs for the CLI, connections, service principals and variables; only a Tenant admin can change a variable, and its CLI tab shows the exact `ci login` command for the Organization.
67
+
68
+ Organization members work in Studio. They chat with agents, open Studio apps, fill agent forms and read Documents. Building a Studio app is Dashboard work for an Organization admin. A package can also ship a whole Studio app, which CI creates and publishes on install; the template's Sales desk is one. A Studio widget never holds CI credentials. It calls CI through the Studio API client from `@collective-intelligence/extensions-sdk-frontend-react/studio-api`, which Studio binds to its own signed-in transport, so each request runs with the current user's permissions.
50
69
 
51
70
  ### CLI
52
71
 
@@ -66,11 +85,11 @@ ci whoami
66
85
 
67
86
  The CLI takes credentials from a flag first, then from the environment (`CI_BACKEND_URL`, `CI_MANAGEMENT_TOKEN`), then from the stored profile. Developers at a terminal use `ci login`, and pipelines set `CI_MANAGEMENT_TOKEN`. Publishing reads `CI_PUBLISHER_TOKEN` from the environment only.
68
87
 
69
- For a package, a demo uses `ci package build`, `validate`, `publish`, `promote` and `install`, or the single `ci deploy` command, which publishes only when the release is absent, promotes only when needed, and then installs or updates. `ci package dev` runs a development session that serves your package modules from your machine to real Dashboard and Studio hosts. `ci package codegen` generates TypeScript types from the package schemas, and `ci doctor` checks discovery, signing keys, Organization access and redirect URIs.
88
+ For a package, you use `ci package build`, `validate`, `publish`, `promote` and `install`, or the single `ci deploy` command, which publishes only when the release is absent, promotes only when needed, and then installs or updates. `ci package dev` runs a development session that serves your package modules from your machine to real Dashboard and Studio hosts. `ci package codegen` generates TypeScript types from the package schemas, and `ci doctor` checks discovery, signing keys, Organization access and redirect URIs.
70
89
 
71
90
  ### HTTP API and API keys
72
91
 
73
- The backend publishes its OpenAPI document at `/openapi.json`. Its wire schemas are the authority, and the SDKs and the CLI are generated from them. A demo meets these public route families:
92
+ The backend publishes its OpenAPI document at `/openapi.json`. Its wire schemas are the authority, and the SDKs and the CLI are generated from them. An external app meets these public route families:
74
93
 
75
94
  - `/application/v1/*`, the Application API for external applications
76
95
  - `/oauth/*`, the authorization server for app sign-in
@@ -80,21 +99,9 @@ The backend publishes its OpenAPI document at `/openapi.json`. Its wire schemas
80
99
 
81
100
  Other route families serve the Dashboard and Studio. A generated operation is not safe for a client just because it exists in the OpenAPI document.
82
101
 
83
- Each credential is a separate authority:
84
-
85
- | Credential | Held by | Used for |
86
- | ------------------------------------------- | -------------------------------- | -------------------------------------------------------------------------------- |
87
- | CLI Session | A person | Interactive CLI work for 30 days, from device approval |
88
- | Management token (`CI_MANAGEMENT_TOKEN`) | A pipeline | CLI work with an Organization API key or a session token |
89
- | Publisher credential (`CI_PUBLISHER_TOKEN`) | A release pipeline | Publish and promote for one package only |
90
- | Client id and client secret | An external application | OAuth sign-in; only a confidential app has a secret |
91
- | Server credential | An external application's server | Calls that act with the app's own grants |
92
- | API key | A service principal | Calls that act with the principal's grants, limited by a Max Privileges template |
93
-
94
- API keys have no scopes. A key never acts beyond its Max Privileges template, and creating, rotating or revoking a key needs manage access to API keys, which no API key has:
102
+ An API key belongs to a service principal and acts with that principal's grants. API keys have no scopes. A key never acts beyond its Max Privileges template, and creating, rotating or revoking a key needs a person's session with manage access to API keys, which no API key has. You manage keys in the Dashboard under Developers > Service principals, or with the CLI:
95
103
 
96
104
  ```bash
97
- ci apps credentials upsert <app-fqn-or-id> --name pipeline --env-file .env.server
98
105
  ci api-keys upsert --principal <principal-fqn> --name pipeline \
99
106
  --max-privileges <template-fqn> --env-file .env.pipeline
100
107
  ```
@@ -110,15 +117,31 @@ A service principal key can run Studio agent conversations without a person. It
110
117
 
111
118
  An external application signs users in with the OAuth authorization code flow and S256 PKCE, through `/oauth/authorize` and `/oauth/token`. The Dashboard shows the sign-in and consent page with the Organization's branding and login methods, including SSO. CI publishes OAuth 2.0 authorization server metadata and is not an OpenID Connect provider.
112
119
 
113
- A public client runs only in the browser and has a client id without a secret. A confidential client is a backend that keeps a client secret. Access tokens last 300 seconds, and only a confidential app can renew one without a browser redirect or exchange a member session for a token. The template's app is confidential. Because its package declares the app, you take the client id from the Dashboard and rotate the secret there to get the client secret.
120
+ A public client runs only in the browser and has a client id without a secret. A confidential client is a backend that keeps a client secret. Access tokens last 300 seconds, and only a confidential app can renew one without a browser redirect or exchange a member session for a token. The template's app is confidential.
121
+
122
+ A confidential app uses two different secrets. The client secret signs users in, renews their tokens and exchanges member sessions. A Server Credential authorizes the server's own calls to CI in service mode, with the grants that an admin gave the app's server. CI refuses the client secret on a server call, so keep the two secrets in separate env files:
123
+
124
+ ```bash
125
+ ci apps credentials upsert <app-fqn-or-id> --name server --env-file .env.server
126
+ ```
127
+
128
+ The template's package declares its app, so `ci apps enroll` refuses it. Read its values with `ci apps env <application-id-or-fqn> --env-file apps/web/.env.local`, then issue the client secret with `ci apps rotate-secret <application-id>`. CI shows each secret only once.
114
129
 
115
130
  In the template, the browser calls only same-origin `/api/*` routes. The BFF behind them, built with `createExternalApplicationBffNextHandlers` from the server SDK, signs users in with a sealed cookie, forwards Resource calls per entity contract, requests Realtime tickets and forwards capabilities. Only `NEXT_PUBLIC_APPLICATION_ID` is visible to the browser.
116
131
 
117
- An app can start only a workflow whose active External application trigger names that app. The template's `POST /api/leads/{id}/convert` route uses `createFixedWorkflowRoute`, which starts exactly one workflow that the server configures (`acme.app.workflows.convert-lead`) with the idempotency key `convert-lead:{leadId}`. The route rejects a workflow name or key in browser input. A call on behalf of a user runs as that user; a service call runs as the service principal that the workflow selects.
132
+ An app can start only a workflow whose active External application trigger names that app. The template's `POST /api/leads/{id}/convert` route uses `createFixedWorkflowRoute`, which starts exactly one workflow that the server configures (`acme.app.workflows.convert-lead`) with the idempotency key `convert-lead:{leadId}`. The route rejects a workflow name or key in browser input.
133
+
134
+ Every tool call in a run uses the current grants of the identity that the run acts as. A call with a user's delegated token acts as that user. The convert-lead route sends the signed-in user's delegated token, so the run acts as that user. When an app starts a workflow in service mode or with `runAsApplication`, no person starts it, so the run acts as the workflow's run-as service principal. [AI primitives](../ai/index.md) lists every case.
118
135
 
119
136
  ### MCP
120
137
 
121
- The backend serves MCP at `/mcp` and at `/mcp/o/<organizationId>`. Every MCP request needs a valid Bearer session token or API key, including `initialize` and `tools/list`. The server exposes these tools: `list_memberships`, `list_skills`, `run_skill`, `get_skill_run`, `list_operations`, `invoke_operation`, `get_operation`, `cancel_operation` and `explain_access`. `run_skill` runs in the background, so a client polls `get_skill_run` for the result.
138
+ The backend serves MCP at `/mcp` and at `/mcp/o/<organizationId>`. Every MCP request needs a valid Bearer token, including `initialize` and `tools/list`. CI accepts three kinds of token:
139
+
140
+ 1. A CI session token or an API key. The call acts as that person or that service principal.
141
+ 2. An OAuth access token that the AI client gets from CI's authorization server after a person approves it. Without a valid token, CI answers `401` with a pointer to its protected-resource metadata, so the client can start that sign-in. The token acts as the person who approved it.
142
+ 3. An MCP Profile token that an Organization admin issues on one MCP Profile. It is a machine credential that never acts as a person, and it reaches only what its profile allows.
143
+
144
+ The server exposes these tools: `list_memberships`, `list_skills`, `run_skill`, `get_skill_run`, `list_operations`, `invoke_operation`, `get_operation`, `cancel_operation` and `explain_access`. `run_skill` runs in the background, so a client polls `get_skill_run` for the result.
122
145
 
123
146
  A workflow becomes visible to MCP clients through an MCP operation trigger. The caller gets an opaque handle and reads the result with `get_operation`. An MCP Profile, managed in the Dashboard under Apps > MCP, defines what an MCP principal can see and do, and it denies everything by default. The built-in Studio user profile grants Studio and MCP use.
124
147
 
@@ -126,20 +149,22 @@ A workflow becomes visible to MCP clients through an MCP operation trigger. The
126
149
 
127
150
  A trigger is the entrypoint of a workflow. The core workflows package ships these triggers:
128
151
 
129
- | Trigger | Starts a run when |
130
- | -------------------- | ------------------------------------------------- |
131
- | On demand | A user starts the workflow explicitly |
132
- | Schedule | A cron expression fires |
133
- | Webhook | Another system sends an authenticated HTTP `POST` |
134
- | External application | A bound external application starts it |
135
- | MCP operation | An MCP client invokes it |
136
- | Entity created | A Knowledge record is created |
137
- | Entity updated | A Knowledge record changes |
138
- | Entity deleted | A Knowledge record is deleted |
152
+ | Trigger | Starts a run when |
153
+ | -------------------- | -------------------------------------- |
154
+ | On demand | A user starts the workflow explicitly |
155
+ | Schedule | A cron expression fires |
156
+ | Webhook | Another system sends an HTTP `POST` |
157
+ | External application | A bound external application starts it |
158
+ | MCP operation | An MCP client invokes it |
159
+ | Entity created | A Knowledge record is created |
160
+ | Entity updated | A Knowledge record changes |
161
+ | Entity deleted | A Knowledge record is deleted |
139
162
 
140
163
  Integration packages add message and file triggers for Slack, Microsoft 365 email, Teams and Drive, Telegram, WhatsApp, Twilio SMS and WhatsApp, and Notion.
141
164
 
142
- A webhook trigger authenticates the caller with an API key, accepts `POST`, and returns JSON. The caller waits for the workflow's response until a deadline and then receives `202` with the run id. CI binds event triggers when it publishes the workflow, and it refuses to publish an enabled trigger with an invalid activation declaration. In the template, the convert-lead workflow is declared in the package, and its trigger names the app's FQN, which install resolves to the app id.
165
+ A run that a person starts on demand acts as that person, unless the workflow's `runIdentity` is `service_principal`; then a production run acts as the workflow's run-as service principal, and only an editor test run keeps the person. A schedule, a webhook, a record event or an MCP operation starts a run with no person, so the run acts as the workflow's run-as service principal, and such a workflow must name one. An approval reviewer never becomes the run's identity, and child workflows and delegated agents keep the identity of the root run.
166
+
167
+ A webhook trigger accepts `POST` and returns JSON. The caller waits for the workflow's response until a deadline and then receives `202` with the run id. CI binds event triggers when it publishes the workflow, and it refuses to publish an enabled trigger with an invalid activation declaration. In the template, the convert-lead workflow is declared in the package, and its trigger names the app's FQN, which install resolves to the app id.
143
168
 
144
169
  ### Realtime
145
170
 
@@ -163,15 +188,66 @@ On a reset, the client drops its local view and refetches every query that a sub
163
188
 
164
189
  ### When CI calls you
165
190
 
166
- A Gateway reverses the direction. You register a Gateway connection with an HTTPS endpoint and a setup credential, and after enrollment CI calls your server with short-lived ES256 tokens and a replay check. Your operations then become CI tools for chat, Skills and workflows. [External apps](../develop/external-apps.md) covers the setup.
191
+ A Gateway reverses the direction. You register a Gateway connection with an HTTPS endpoint and a setup credential, and CI uses that credential only for discovery and enrollment. After enrollment CI signs each call to your server with an ES256 token that lives 60 seconds by default and 300 seconds at most, and your server accepts each token only once. Your server holds no CI secret for these calls; it trusts the CI issuer that you configure. Your operations then become CI tools for chat, Skills and workflows. [External apps](../develop/external-apps.md) covers the setup.
192
+
193
+ ### Credentials
194
+
195
+ Each credential is a separate authority. The tables group them by who holds them.
196
+
197
+ #### Held by people
198
+
199
+ | Credential | Type | Lifetime or rotation | Used for |
200
+ | ----------- | ------------------------------------ | ------------------------------------ | ---------------------------------------------------------------------------- |
201
+ | CI session | Opaque session token | 30 days by default; ends at sign-out | Dashboard and Studio work; also accepted by MCP and as `CI_MANAGEMENT_TOKEN` |
202
+ | CLI Session | The same session, made by `ci login` | 30 days; `ci logout` ends it | Interactive `ci` commands, stored in your user profile with mode `0600` |
203
+
204
+ The Connect Studio link that the Dashboard shows only tells the Studio desktop app which CI and Organization to use. The person then signs in with a password, a one-time code or SSO.
205
+
206
+ #### Held by pipelines and scripts
207
+
208
+ | Credential | Type | Lifetime or rotation | Used for |
209
+ | ------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
210
+ | API key | Opaque secret with the prefix `dpk_` | No expiry at creation; a rotation keeps the old secret 24 hours; a revocation ends both | Calls with a service principal's grants, cut to a Max Privileges template |
211
+ | `CI_MANAGEMENT_TOKEN` | Environment variable with an API key or a session token | That of the token it holds | Unattended `ci` commands; an API key fixes the Organization |
212
+ | Publisher credential (`CI_PUBLISHER_TOKEN`) | Opaque secret for one exact package name | Optional expiry; a revocation stops it at once | Publish and promote for that package only |
213
+
214
+ #### Held by your external app
215
+
216
+ | Credential | Type | Lifetime or rotation | Used for |
217
+ | ------------------ | ------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------- |
218
+ | Client id | Public OAuth identifier | Fixed for the app | Sign-in; safe in the browser |
219
+ | Client secret | Opaque secret, confidential apps only | Until rotated; a rotation replaces it at once | Sign-in, token renewal and member-session exchange |
220
+ | Server Credential | Opaque secret with the prefix `dsc_` | A rotation keeps the old secret 24 hours; a revocation ends both | The server's own calls to CI in service mode |
221
+ | User access token | ES256 token, kept on the server | 300 seconds | Application API calls as the signed-in user |
222
+ | Renewal credential | Opaque secret, confidential apps only | At most 7 days from sign-in, never past the user's CI session | New access tokens without a browser redirect |
223
+ | Session cookie | Cookie sealed with `SESSION_SECRETS` | `sessionTtlSeconds`: 1 day by default, from 300 seconds to 7 days | The browser's same-origin `/api/*` calls to your BFF |
224
+
225
+ The browser holds only the sealed cookie and the application id. The access token and the renewal credential stay on the server.
226
+
227
+ #### Held by AI clients
228
+
229
+ | Credential | Type | Lifetime or rotation | Used for |
230
+ | ----------------- | ----------------------------------- | ----------------------------------------- | ----------------------------------------------- |
231
+ | MCP OAuth token | Access token from CI's OAuth server | 30 days by default; no renewal credential | MCP calls as the person who approved the client |
232
+ | MCP Profile token | Opaque machine token | Until an Organization admin revokes it | MCP calls limited to one MCP Profile |
233
+
234
+ #### Between CI and outside systems
235
+
236
+ | Credential | Type | Lifetime or rotation | Used for |
237
+ | ------------------------ | ------------------------------------------- | ------------------------------------------- | ------------------------------------------------ |
238
+ | Gateway caller token | ES256 token that CI signs | 60 seconds by default, 300 at most; one use | CI calls to your Gateway |
239
+ | Gateway setup credential | Secret that you choose | You rotate it; CI reads it at each setup | Gateway discovery and enrollment only |
240
+ | Connection credentials | Fields of a connection template, kept in CI | As long as the outside system accepts them | Connectors and tools that call an outside system |
241
+
242
+ A connection keeps every field that its template marks secret as a secret. A package supplies such a value through a `secret` package variable, which deploys only as a link to an Organization variable, never inline. Your external app never sees connection credentials, and CI never sends a management or publisher token to a Gateway.
167
243
 
168
244
  ## Code entrypoints
169
245
 
170
- Demo code imports CI packages and its own workspaces by package name and exported subpath, for example `@acme/lead/views`, and never by relative path. Each subpath has one folder under `src/` with one `index.ts` and one `exports` entry in `package.json`.
246
+ Code in the template imports CI packages and its own workspaces by package name and exported subpath, for example `@acme/lead/views`, and never by relative path. Each subpath has one folder under `src/` with one `index.ts` and one `exports` entry in `package.json`.
171
247
 
172
248
  ### SDK subpaths
173
249
 
174
- The SDKs split by where the code runs. [SDKs](../develop/sdks.md) has the full map; these are the subpaths a demo meets most.
250
+ The SDKs split by where the code runs. [SDKs](../develop/sdks.md) has the full map; these are the subpaths you meet most.
175
251
 
176
252
  | Package | Runs | Holds | Main subpaths |
177
253
  | --------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------- |
@@ -230,6 +306,7 @@ Inside CI, a Studio or Dashboard widget enters through a hosted contribution. Yo
230
306
  ## Related pages
231
307
 
232
308
  - [Platform architecture](architecture.md): Tenants, Organizations, surfaces and the package lifecycle.
309
+ - [Studio](../ai/studio.md): What Organization members do in Studio.
233
310
  - [Access](access.md): Access Profiles, Access Grants and Max Privileges.
234
311
  - [SDKs](../develop/sdks.md): Every CI package and its subpaths.
235
312
  - [External apps](../develop/external-apps.md): The BFF, sign-in and the Gateway.
@@ -8,58 +8,80 @@ Some screens need no primitive at all. The template's public intake form posts t
8
8
 
9
9
  ## Decision path
10
10
 
11
+ A scenario raises three separate questions: where its data lives, what kind of work it needs, and who uses its screens. Answer each one with its own chart and combine the results.
12
+
13
+ ### Where the data lives
14
+
15
+ The first question is who keeps the authoritative copy of the data. [Data resources](../data/index.md) compares Knowledge, datasets and Documents in more depth.
16
+
17
+ ```mermaid
18
+ flowchart TD
19
+ D{Who keeps the authoritative copy?}
20
+ D -->|CI| M{What shape is the data?}
21
+ M -->|Records that people and agents edit| K[Knowledge schema]
22
+ M -->|Rows to read and aggregate| MD[Managed dataset]
23
+ M -->|Files that people browse and agents search| DOC[Documents]
24
+ D -->|An outside system| X{How does CI reach it?}
25
+ X -->|Live queries on a warehouse| XD[External dataset]
26
+ X -->|Records and actions in the customer app| GW[Gateway]
27
+ X -->|A copy in CI kept in sync| CON[Knowledge connector]
28
+ D -->|Only the app| APP[App-owned storage]
29
+ ```
30
+
31
+ A Knowledge connector turns the outside records into connected records in Knowledge. When agents need only a few fields of an app database, put a projection of those fields into a Knowledge schema and keep personal data in the app.
32
+
33
+ ### What kind of work it needs
34
+
35
+ ```mermaid
36
+ flowchart TD
37
+ W{What kind of work is it?}
38
+ W -->|A rule with one right answer| T[Tool]
39
+ W -->|Fixed steps in a fixed order| WF[Workflow]
40
+ W -->|A path that depends on what it finds| AG[Agent with a Skill]
41
+ W -->|Logic that an existing backend already runs| RT[Gateway with a remote tool collection]
42
+ WF --> A{Must a person approve a side effect?}
43
+ AG --> A
44
+ A -->|Inside the workflow| AN[Workflow approval node]
45
+ A -->|In chat or a Skill form| TA[Tool binding with approval]
46
+ ```
47
+
48
+ A file that feeds one extraction step goes to a workflow as its input. [Workflow, agent or tool](index.md#workflow-agent-or-tool) and [Approvals depend on the caller](index.md#approvals-depend-on-the-caller) below explain the hard cases.
49
+
50
+ ### Who uses the screens
51
+
11
52
  ```mermaid
12
53
  flowchart TD
13
- S[Demo scenario] --> Q1{Where does the data live?}
14
- Q1 -->|In CI| Q2{Who edits it?}
15
- Q2 -->|People, agents and workflows| K[Knowledge schema]
16
- Q2 -->|Nobody, rows are read and aggregated| MD[Managed dataset]
17
- Q1 -->|Customer database or warehouse| Q3{Must it stay there?}
18
- Q3 -->|Yes| XD[External dataset or Gateway]
19
- Q3 -->|Agents need a few fields| K
20
- Q1 -->|Only the app needs it| APP[App-owned storage]
21
- S --> Q4{Is it files?}
22
- Q4 -->|People browse, agents search| DOC[Documents]
23
- Q4 -->|One extraction step| WF[Workflow]
24
- S --> Q5{Does it come from a SaaS?}
25
- Q5 -->|Recurring import| CON[Connector]
26
- S --> Q6{Deterministic or open-ended?}
27
- Q6 -->|Fixed steps| WF
28
- Q6 -->|Open-ended| AG["Agent + Skill"]
29
- Q6 -->|One fixed rule| T[Tool]
30
- S --> Q7{Does a side effect need approval?}
31
- Q7 -->|In chat or a Skill form| TA[Tool with approval]
32
- Q7 -->|Inside a process| AN[Workflow approval node]
33
- S --> Q8{Who uses the UI?}
34
- Q8 -->|Customers outside CI| EA[External app]
35
- Q8 -->|Staff inside Studio| SA[Studio app]
36
- S --> Q9{Must agents call existing backend logic?}
37
- Q9 -->|Yes| GW["Gateway + remote tool collection"]
54
+ U{Who uses the screen?}
55
+ U -->|Customers or members outside CI| EA[External app with a BFF]
56
+ U -->|Staff in Studio| S{Do the built-in views show it?}
57
+ S -->|Yes| BV[Studio app with built-in views]
58
+ S -->|No| CW[Studio app with a custom widget]
59
+ U -->|Nobody yet, a first visual pitch| MOCK[Mock screens with simulated saves]
38
60
  ```
39
61
 
40
- The questions are independent, so one scenario answers several of them and the demo combines the results. The sales CRM answers the data question with Knowledge schemas, the work question with a workflow and an agent, and the UI question twice: customers use the external app and staff use the Studio app.
62
+ The sales CRM answers the data chart with Knowledge schemas and the work chart with a workflow, an agent and a tool. It answers the screen chart twice: customers use the external app, and staff use a Studio app that places a built-in list view and a custom widget on one page.
41
63
 
42
64
  ## Criteria
43
65
 
44
- | Signal in the scenario | Primitive | Why | Watch out for |
45
- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
46
- | People in the app or Studio, agents and workflows all read and edit the records | [Knowledge schema](../data/knowledge.md) | One typed record per real thing, with relations, search and data policies that every surface shares | Measurements, events and other high-volume rows belong in a dataset, so do not create one record per row |
47
- | Rows that people read and aggregate, such as a CSV or Excel export with trends | [Managed dataset](../data/datasets.md) | CI stores the typed rows and answers records, aggregate and time-series queries | A dataset declared with no data policy grants access to nobody, and deploy does not import the file |
48
- | A warehouse such as Microsoft Fabric or Databricks holds the data, and it must stay there | [External dataset](../data/datasets.md) | CI queries the source live and keeps no copy | Queries take no SQL, and a provider outage fails the query with no fallback |
49
- | The customer's own app and database keep the records | [Gateway](../develop/external-apps.md) | CI reaches the resources, dataset queries and operations that the customer server declares | The Gateway exposes only what its definition lists and never creates CI schemas |
50
- | The app database is the authority, but agents need some of its fields | [Knowledge schema](../data/knowledge.md) with a projection | Only the needed, non-personal fields leave the app | Decide field by field what may leave; personal data stays in the app database |
51
- | Files that people browse and agents search | [Documents](../data/knowledge.md#documents-and-knowledge) in a Document Collection | Collections hold folders, versions and permissions per path, and a connected collection stays in sync with a drive | A [Documents connector](../data/connectors.md) sync creates no Knowledge records, and new files become searchable only after indexing |
52
- | A file that feeds one extraction step and nothing else | Stored file passed to a [workflow](../ai/index.md) | The workflow takes the file as `storageFileId` and returns extracted values | Use Documents instead when people must find the file later |
53
- | A SaaS tool or SQL database that the demo imports from on a schedule | [Knowledge connector](../data/connectors.md) | A connector instance maps source fields to Knowledge schemas and runs full or delta imports | Installing the instance imports nothing until a schedule or a manual trigger runs, and SQL delta imports need a watermark column |
54
- | A fixed sequence such as extract, check, create and notify | [Workflow](../ai/index.md) | A graph of steps with triggers, approvals and typed output, where a prompt node covers one bounded AI step | Every triggered workflow needs a service principal as its run-as identity |
55
- | Open-ended work such as answering questions, finding matches or qualifying | [Agent with a Skill](../ai/index.md) | The agent picks its path from what it finds and returns typed output inside stated boundaries | A Skill can use only tools that its agent also allows, so the agent lists the Skill's tools again |
56
- | A rule that must give the same answer every time | [Tool](../ai/index.md) | Code computes the result, and the agent explains it | An agent can call the tool only when its `usageScopes` include `"automation"` |
57
- | A side effect that a person must approve | [Tool binding with approval](../ai/index.md), or a workflow approval node | `approval: "always"` or a named rule pauses the call until someone decides | A named rule must exist in the Organization before install, and an unattended agent run approves by default |
58
- | Customers or members use the UI outside CI | [External application](../develop/external-apps.md) | The web app keeps its own UI and reaches CI through its BFF with a sealed-cookie session | The app takes no OAuth scopes; its app gate and Max Privileges limit what users can do |
59
- | Staff work inside Studio | [Studio app](../develop/extensions.md) | Built-in views show schema records without code, and custom widgets cover what they cannot show | A Declared Studio App is read-only in the Studio builder and changes only with a new package release |
60
- | Agents must call logic that an existing backend already implements | [Gateway with a remote tool collection](../develop/external-apps.md) | The logic stays in the customer service and reaches agents as tools | CI signs a short-lived token for every Gateway call, and browser cookies never authorize one |
61
- | Some people may see or do things that others may not | [Access Profiles and Access Grants](../platform/access.md) | Capabilities and Knowledge data policies decide actions and visible records, and grants give them to Groups | Knowledge data policies do not cover datasets, which list their principals in their own policy |
62
- | Logs, counters or sessions that only the app needs | App-owned storage behind the app API | No CI user or agent reads this data | A staff page that shows it needs its own credential in the app |
66
+ | Signal in the scenario | Primitive | Why | Watch out for |
67
+ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
68
+ | People in the app or Studio, agents and workflows all read and edit the records | [Knowledge schema](../data/knowledge.md) | One typed record per real thing, with relations, search and data policies that every surface shares | Measurements, events and other high-volume rows belong in a dataset, so do not create one record per row |
69
+ | Rows that people read and aggregate, such as a CSV or Excel export with trends | [Managed dataset](../data/datasets.md) | CI stores the typed rows and answers records, aggregate and time-series queries | A dataset declared with no data policy grants access to nobody, and deploy does not import the file |
70
+ | A warehouse such as Microsoft Fabric or Databricks holds the data, and it must stay there | [External dataset](../data/datasets.md) | CI queries the source live and keeps no copy | Queries take no SQL, and a provider outage fails the query with no fallback |
71
+ | The customer's own app and database keep the records | [Gateway](../develop/external-apps.md) | CI reaches the resources, dataset queries and operations that the customer server declares | The Gateway exposes only what its definition lists and never creates CI schemas |
72
+ | The app database is the authority, but agents need some of its fields | [Knowledge schema](../data/knowledge.md) with a projection | Only the needed, non-personal fields leave the app | Decide field by field what may leave; personal data stays in the app database |
73
+ | Files that people browse and agents search | [Documents](../data/documents.md) in a Document Collection | Collections hold folders, versions and permissions per path, and a connected collection stays in sync with a drive | A [Documents connector](../data/connectors.md) sync creates no Knowledge records, and new files become searchable only after indexing |
74
+ | A file that feeds one extraction step and nothing else | Stored file passed to a [workflow](../ai/index.md) | The workflow takes the file as `storageFileId` and returns extracted values | Use Documents instead when people must find the file later |
75
+ | A SaaS tool or SQL database that the demo imports from on a schedule | [Knowledge connector](../data/connectors.md) | A connector instance maps source fields to Knowledge schemas and runs full or delta imports | Installing the instance imports nothing until a schedule or a manual trigger runs, and SQL delta imports need a watermark column |
76
+ | A fixed sequence such as extract, check, create and notify | [Workflow](../ai/index.md) | A graph of steps with triggers, approvals and typed output, where a prompt node covers one bounded AI step | Every triggered workflow needs a service principal as its run-as identity |
77
+ | Open-ended work such as answering questions, finding matches or qualifying | [Agent with a Skill](../ai/index.md) | The agent picks its path from what it finds and returns typed output inside stated boundaries | A Skill can use only tools that its agent also allows, so the agent lists the Skill's tools again |
78
+ | A rule that must give the same answer every time | [Tool](../ai/index.md) | Code computes the result, and the agent explains it | An agent can call the tool only when its `usageScopes` include `"automation"` |
79
+ | A side effect that a person must approve | [Tool binding with approval](../ai/index.md), or a workflow approval node | `approval: "always"` or a named rule pauses the call until someone decides | A named rule must exist in the Organization before install, and an unattended agent run approves by default |
80
+ | Customers or members use the UI outside CI | [External application](../develop/external-apps.md) | The web app keeps its own UI and reaches CI through its BFF with a sealed-cookie session | The app takes no OAuth scopes; its app gate and Max Privileges limit what users can do |
81
+ | Staff work inside Studio | [Studio app](../develop/extensions.md) | Built-in views show schema records without code, and custom widgets cover what they cannot show | A Declared Studio App is read-only in the Studio builder and changes only with a new package release |
82
+ | Agents must call logic that an existing backend already implements | [Gateway with a remote tool collection](../develop/external-apps.md) | The logic stays in the customer service and reaches agents as tools | CI signs a short-lived token for every Gateway call, and browser cookies never authorize one |
83
+ | Some people may see or do things that others may not | [Access Profiles and Access Grants](../platform/access.md) | Capabilities and Knowledge data policies decide actions and visible records, and grants give them to Groups | Knowledge data policies do not cover datasets, which list their principals in their own policy |
84
+ | Logs, counters or sessions that only the app needs | App-owned storage behind the app API | No CI user or agent reads this data | A staff page that shows it needs its own credential in the app |
63
85
 
64
86
  ## Workflow, agent or tool
65
87
 
@@ -67,7 +89,7 @@ A workflow prompt node and an agent both call a model, which makes this the choi
67
89
 
68
90
  An agent that must not change data says so in `behavioralBoundaries`. The lead qualifier declares "Never change a Lead or create an Opportunity". When an agent should help with a change, let it propose the change and let the person apply it with a button in the app.
69
91
 
70
- A workflow's trigger follows from who or what starts the work. A `schedule` trigger runs it on a clock, `entity-created` and `entity-updated` react to Knowledge changes, `external-application` lets the web app start it, and `on-demand` lets staff start it from Studio. The template's convert-lead workflow uses the `external-application` trigger and runs as the `convert-lead-runner` service principal. See [AI](../ai/index.md) for the full comparison of tools, Skills, agents and workflows.
92
+ A workflow's trigger follows from who or what starts the work. A `schedule` trigger runs it on a clock, `entity-created` and `entity-updated` react to Knowledge changes, `external-application` lets the web app start it, and `on-demand` lets staff start it from Studio. A run acts as the identity that started it: by default a person who starts it runs it as themselves, a workflow in `service_principal` run identity mode runs as its run-as service principal, and a start with no person, such as a schedule or a record event, needs that mode. The template's convert-lead workflow uses the `external-application` trigger, runs as the signed-in user when the web app starts it with the user's token, and names `convert-lead-runner` as its run-as service principal. See [AI](../ai/index.md) for the full comparison of tools, Skills, agents and workflows.
71
93
 
72
94
  ## Approvals depend on the caller
73
95
 
@@ -99,6 +121,7 @@ Demos built from the template started with Knowledge schemas, access and an exte
99
121
 
100
122
  - [Knowledge](../data/knowledge.md)
101
123
  - [Datasets](../data/datasets.md)
124
+ - [Documents](../data/documents.md)
102
125
  - [Connectors](../data/connectors.md)
103
126
  - [AI](../ai/index.md)
104
127
  - [External apps](../develop/external-apps.md)