@collective-intelligence/extensions-sdk-frontend 0.3.2 → 0.3.4
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.
- package/docs/guide/ai/index.md +36 -17
- package/docs/guide/ai/studio.md +245 -0
- package/docs/guide/data/connectors.md +81 -18
- package/docs/guide/data/datasets.md +6 -17
- package/docs/guide/data/documents.md +235 -0
- package/docs/guide/data/index.md +62 -0
- package/docs/guide/data/knowledge.md +21 -18
- package/docs/guide/develop/extensions.md +68 -15
- package/docs/guide/develop/external-apps.md +48 -14
- package/docs/guide/develop/infrastructure.md +135 -0
- package/docs/guide/develop/sdks.md +2 -2
- package/docs/guide/index.md +12 -8
- package/docs/guide/platform/access.md +82 -17
- package/docs/guide/platform/architecture.md +27 -18
- package/docs/guide/platform/entrypoints.md +128 -47
- package/docs/guide/scenarios/index.md +69 -46
- package/docs/guide/template/index.md +22 -9
- package/docs/guide/template/state-machines.md +1 -1
- package/package.json +3 -3
|
@@ -44,11 +44,31 @@ A grant change takes effect within 60 seconds. Every Organization-scoped respons
|
|
|
44
44
|
|
|
45
45
|
An Organization membership links one user to one Organization and has one kind, `member` or `guest`. An external app usually creates guests. The membership itself gives no access, because access comes only from grants. Every former role is now a grant of the matching built-in profile, such as `core.profiles.organization-admin` or `core.profiles.knowledge-reader`.
|
|
46
46
|
|
|
47
|
-
Groups
|
|
47
|
+
## Groups
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
Groups are the usual way to hand out grants. A Group is a named set of accounts in one Organization: users, and service principals that a package places in its own Groups. Groups form a tree in which each Group has at most one parent, and an Organization allows at most five levels.
|
|
50
|
+
|
|
51
|
+
A grant to a Group has one recipient, the Group, and CI applies it to every account that it reaches. The grant's `coverage` decides which accounts these are:
|
|
52
|
+
|
|
53
|
+
- With `coverage: "direct"`, the grant reaches the members of that Group only.
|
|
54
|
+
- With `coverage: "inherited"`, it also reaches the members of every Group below it, at any depth.
|
|
55
|
+
|
|
56
|
+
Inheritance goes down the tree only. A grant to a parent Group can reach the members of its subgroups, and a grant to a subgroup never reaches the members of its parent. Every grant must state its `coverage`. In a Resource Audience, a Group entry without `coverage` counts as `inherited`.
|
|
57
|
+
|
|
58
|
+
The template shows both directions. It grants the Sales rep profile to Sales and the Sales manager profile to Sales managers, both with `inherited` coverage:
|
|
59
|
+
|
|
60
|
+
```mermaid
|
|
61
|
+
flowchart TD
|
|
62
|
+
S["Sales<br/>grant: Sales rep, inherited"] --> M["Sales managers<br/>grant: Sales manager, inherited"]
|
|
63
|
+
```
|
|
50
64
|
|
|
51
|
-
A
|
|
65
|
+
A member of Sales managers holds both profiles, because Sales is an ancestor of their Group. A member who is only in Sales holds Sales rep and nothing from the managers grant.
|
|
66
|
+
|
|
67
|
+
CI stores the grants that reach each account and recalculates them in the same write that adds or removes a Group member, moves a Group or changes a grant. A request reads that stored result and does not walk the tree. A workflow also reads the current Groups of its run identity at every tool call, so a person you remove from a Group loses that access at the next call. Clients see the change within 60 seconds.
|
|
68
|
+
|
|
69
|
+
### Declared Groups and Dashboard Groups
|
|
70
|
+
|
|
71
|
+
A package declares a Group tree with `declareOrganizationGroup`, and every Group in the tree has an FQN. A subgroup has no handle of its own, so a grant names it by its FQN, which is the parent FQN, a dot and the subgroup key:
|
|
52
72
|
|
|
53
73
|
```ts
|
|
54
74
|
export const salesGroupFqn = "acme.app.groups.sales"
|
|
@@ -75,9 +95,18 @@ export const salesGroup = declareOrganizationGroup({
|
|
|
75
95
|
})
|
|
76
96
|
```
|
|
77
97
|
|
|
78
|
-
|
|
98
|
+
A Group that someone creates in the Dashboard, or with `ci.access.groups.create` from a server, has no FQN. Package grants and the server SDK name a Group only by its FQN, so a Group without one can get grants only in the Dashboard.
|
|
99
|
+
|
|
100
|
+
Declared Groups follow these rules:
|
|
101
|
+
|
|
102
|
+
- Only the package that first declared a Group FQN can declare it again. FQNs that start with `core.groups.` belong to the platform, and a package install that uses one fails.
|
|
103
|
+
- With `upsert`, each deploy writes the declared name, description and parent again. With `init_only`, CI keeps a Group that already exists as it is.
|
|
104
|
+
- The package never fills its Groups. After install, an Organization admin adds people to Sales or Sales managers. The one exception is a service principal that the same package declares with `groups`, which the install places in those Groups.
|
|
105
|
+
- When a release drops a Group, CI deletes it only when nothing uses it, and keeps it otherwise. A Group that holds an Access Grant cannot be deleted.
|
|
106
|
+
|
|
107
|
+
## Declared and runtime grants
|
|
79
108
|
|
|
80
|
-
|
|
109
|
+
A package can declare capabilities, profiles, policies, Max Privileges and grants, and the install creates them in the Organization. The lifecycle of each grant decides who owns it after install. The template's Sales grant uses `deployMode: "init_only"` with `readonly: false`, so an Organization admin can revoke it and a package update does not write it again. The managers grant uses `upsert` with `readonly: true`, so the package keeps it in place.
|
|
81
110
|
|
|
82
111
|
Runtime grants come from the Dashboard, invitations, SSO defaults and the provisioning API. An app's server manages them through `ci.access` in the server SDK. `sync` makes the runtime grants under one namespace match the list exactly:
|
|
83
112
|
|
|
@@ -96,7 +125,7 @@ await ci.access.grants.sync({
|
|
|
96
125
|
// result = { created, updated, deleted, unchanged }: Access Grant FQNs.
|
|
97
126
|
```
|
|
98
127
|
|
|
99
|
-
The app's server acts only with the grants an
|
|
128
|
+
The app's server acts only with the grants that an Organization admin gave to it as `{ applicationServer }`. It creates and changes only its own guests, reads Groups without writing them, sends no invitations, and never touches a package-declared grant.
|
|
100
129
|
|
|
101
130
|
## Data policies narrow records
|
|
102
131
|
|
|
@@ -168,7 +197,7 @@ Consent is a separate setting. `applicationConsent` (`inherit`, `ask` or `skip`)
|
|
|
168
197
|
|
|
169
198
|
## API keys and service principals
|
|
170
199
|
|
|
171
|
-
A service principal is a non-human identity, declared with `servicePrincipal({ fqn, groups, name, version })`. It holds only the grants that name it with `grantee: { servicePrincipal }`. The template's `convertLeadRunner` is a service principal with no Groups
|
|
200
|
+
A service principal is a non-human identity, declared with `servicePrincipal({ fqn, groups, name, version })`. It holds only the grants that name it with `grantee: { servicePrincipal }`. The template's `convertLeadRunner` is a service principal with no Groups. The convert-lead workflow selects it with `runIdentity: { mode: "service_principal", servicePrincipal: convertLeadRunnerFqn }`. In this mode, a production run that a person starts from Studio or the Dashboard, and a run that no person starts, act as `convertLeadRunner`. A call from the web app with a user's delegated token still acts as that user, so when a signed-in user clicks Convert, the run acts as that user. [AI primitives](../ai/index.md) lists every case.
|
|
172
201
|
|
|
173
202
|
An API key belongs to a service principal and is created with a Max Privileges template:
|
|
174
203
|
|
|
@@ -178,12 +207,13 @@ ci api-keys upsert --principal <fqn> --name <name> --max-privileges <template-fq
|
|
|
178
207
|
|
|
179
208
|
The template sets the ceiling, and the principal's grants decide what the key may do below it. A key without a template uses no capability, and no API key can manage API keys. CI shows the secret once.
|
|
180
209
|
|
|
181
|
-
> **Warning:** A run as a service principal asks no questions and decides no approvals.
|
|
182
|
-
> approval gates do not stop it: CI approves unattended
|
|
183
|
-
> records
|
|
184
|
-
>
|
|
210
|
+
> **Warning:** A run as a service principal asks no questions and decides no approvals. In an
|
|
211
|
+
> Agent run, tool approval gates do not stop it: CI approves the unattended call
|
|
212
|
+
> by default and records it without an actor. A workflow Approval node still
|
|
213
|
+
> pauses the run until a person decides, and that reviewer never becomes the
|
|
214
|
+
> run's identity. Plan for this before a demo drives an agent with an API key.
|
|
185
215
|
|
|
186
|
-
The template's server also reads Leads with the app's own
|
|
216
|
+
The template's server also reads Leads with the app's own Server Credential (the Read Port on the [External apps](../develop/external-apps.md) page). The package declares no `{ applicationServer }` grant for it, so an Organization admin must give the app server read access to Leads after install.
|
|
187
217
|
|
|
188
218
|
## Hide in the UI, check on the server
|
|
189
219
|
|
|
@@ -214,16 +244,51 @@ The template's CRM page has a Convert action that starts the convert-lead workfl
|
|
|
214
244
|
|
|
215
245
|
1. Check what the template does today. `convertLeadRequirement` is `{ mode: "on", requires: "platform.workflows" }`. Only the Sales manager profile allows `core.platform.workflows`, so today only members of Sales managers see Convert and can run it. A member who is only in Sales gets no button, and the BFF route answers 403.
|
|
216
246
|
2. Add `allow(core.platform.workflows)` to `repProfile` in the organization package. The app's Max Privileges already allow `platform.workflows`, so they need no change. Bump `VERSION`, then build, publish, promote and install the package.
|
|
217
|
-
3.
|
|
218
|
-
4. Sign in as a user who is only in Sales. The CRM page now shows Convert, and `POST /api/leads/:id/convert` answers `{ runId }`.
|
|
247
|
+
3. Know who the run acts as. The BFF route starts the workflow with the signed-in user's delegated token, so the run acts as that user, with the user's current grants, and not as `convertLeadRunner`. The workflow's only node sets a run variable (`converted: true`) and writes no Lead record, so no Knowledge write policy takes part. Confirm it with one trial run as a rep before the demo.
|
|
248
|
+
4. Sign in as a user who is only in Sales. The CRM page now shows Convert, and `POST /api/leads/:id/convert` answers `{ runId }`. In the Dashboard Check access tab, choose that user and `platform.workflows` to see which grant gives it. Allow up to 60 seconds after a grant change, or wait for the realtime access event to refresh the page.
|
|
219
249
|
|
|
220
|
-
For a one-off demo you can skip the package change. An
|
|
250
|
+
For a one-off demo you can skip the package change. An Organization admin grants the Sales manager profile to a single user in the Dashboard, which creates a runtime grant. The package stays the source of truth for the Sales tree, so remove the runtime grant when the demo ends.
|
|
221
251
|
|
|
222
252
|
## Debug and test access
|
|
223
253
|
|
|
224
|
-
To answer "why can or can't this user do this?",
|
|
254
|
+
To answer "why can or can't this user do this?", use the access check. It lists the principal's grants and how each one reaches it: directly, through a Group, or through an ancestor Group. For a capability, it names the grants that hold it. For one Knowledge record, it lists each policy of the schema and why the policy admits the record or not. You can reach the same check in three ways, and each one needs `admin.grants` at read. The built-in Organization admin and Organization operator profiles hold it, and the Studio user profile does not.
|
|
255
|
+
|
|
256
|
+
The short path for a person is the Dashboard. Open the Organization admin Access page and its Check access tab, then choose who and a capability or a Knowledge record. On a member's page, the Effective access tab lists every capability with a Why? or Why not? button that opens Check access with the member and the capability filled in.
|
|
257
|
+
|
|
258
|
+
From an MCP client, call the `explain_access` tool. Its `request` takes the principal, the target and, optionally, the credential whose Max Privileges CI must apply. On `/mcp`, name the Organization with `organization_id`; on `/mcp/o/<organizationId>` you can leave it out.
|
|
259
|
+
|
|
260
|
+
```json
|
|
261
|
+
{
|
|
262
|
+
"name": "explain_access",
|
|
263
|
+
"arguments": {
|
|
264
|
+
"organization_id": "<organization id>",
|
|
265
|
+
"request": {
|
|
266
|
+
"principal": { "kind": "user", "userId": "<user id>" },
|
|
267
|
+
"target": {
|
|
268
|
+
"kind": "capability",
|
|
269
|
+
"code": "platform.workflows",
|
|
270
|
+
"mode": "on"
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
}
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
From server code, call `ci.access.explain` in the server SDK with the same request. Add a `credential` of kind `application_token` to see the access through the app, after the Max Privileges cut:
|
|
278
|
+
|
|
279
|
+
```ts
|
|
280
|
+
const why = await ci.access.explain({
|
|
281
|
+
organizationId,
|
|
282
|
+
principal: { kind: "user", userId },
|
|
283
|
+
target: { kind: "capability", code: "platform.workflows", mode: "on" },
|
|
284
|
+
credential: { kind: "application_token", applicationId }
|
|
285
|
+
})
|
|
286
|
+
// why.target.allowed and why.target.holders, why.grants with their path, why.cut
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
The template's app server holds no grant with `admin.grants`, so this call answers 403 from the template's server as installed. Use the Dashboard or the MCP tool there.
|
|
225
290
|
|
|
226
|
-
When a user installed the package and still cannot sign in to the app, check three things in order. The user must be in Sales or Sales managers, the grant for that Group must hold the app gate, and
|
|
291
|
+
When a user installed the package and still cannot sign in to the app, check three things in order. The user must be in Sales or Sales managers, the grant for that Group must hold the app gate, and the app's client secret must have been rotated with `ci apps rotate-secret <application-id>`. Install adds no members to the Groups and does not rotate the secret. A package that declares grants also needs an install with a user's management token, because a system install fails with `installer_required`.
|
|
227
292
|
|
|
228
293
|
You can test policies and profiles without a running CI. `accessTest` from `@collective-intelligence/extensions-sdk-backend` loads your packages and answers questions as a given user:
|
|
229
294
|
|
|
@@ -1,34 +1,38 @@
|
|
|
1
1
|
# Platform architecture
|
|
2
2
|
|
|
3
|
-
The parts of Collective Intelligence, the three integration models, and how a
|
|
3
|
+
The parts of Collective Intelligence, the three integration models, and how a package moves from build to install.
|
|
4
4
|
|
|
5
|
-
A
|
|
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
|
|
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
|
|
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
|
|
18
|
-
|
|
|
19
|
-
| Dashboard
|
|
20
|
-
| Studio
|
|
21
|
-
| Backend API
|
|
22
|
-
| Workers
|
|
23
|
-
| Compute
|
|
24
|
-
| Media
|
|
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
|
|
30
|
-
>
|
|
31
|
-
>
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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["
|
|
12
|
-
user["
|
|
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
|
|
35
|
-
| --------------------- |
|
|
36
|
-
| Dashboard |
|
|
37
|
-
| Studio |
|
|
38
|
-
| CLI (`ci`) | Developers and pipelines
|
|
39
|
-
| HTTP API | Scripts and unattended runs
|
|
40
|
-
| External applications | Your web app's server
|
|
41
|
-
| MCP | AI clients and assistants
|
|
42
|
-
| Workflow triggers | Other systems, the clock, apps, record changes
|
|
43
|
-
| Realtime | Your browser, through your BFF
|
|
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
|
-
|
|
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
|
-
|
|
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,13 @@ 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,
|
|
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.
|
|
89
|
+
|
|
90
|
+
When a command fails, the CLI prints one block: what failed, the Cause, the fix steps with the exact commands to run, whether a retry can help, and a reference with the Operation ID and Diagnostic ID. `ci diagnostics show <diagnostic-id>` reads the full failure when you may read it. [Extensions](../develop/extensions.md#when-a-deploy-fails) explains each line and who can read the full failure.
|
|
70
91
|
|
|
71
92
|
### HTTP API and API keys
|
|
72
93
|
|
|
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.
|
|
94
|
+
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
95
|
|
|
75
96
|
- `/application/v1/*`, the Application API for external applications
|
|
76
97
|
- `/oauth/*`, the authorization server for app sign-in
|
|
@@ -80,21 +101,11 @@ The backend publishes its OpenAPI document at `/openapi.json`. Its wire schemas
|
|
|
80
101
|
|
|
81
102
|
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
103
|
|
|
83
|
-
|
|
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 |
|
|
104
|
+
An unexpected server error answers HTTP 500 with the body `{"_tag":"InternalServerError"}` and the Diagnostic ID in the `x-diagnostic-id` header, which browsers can read. Log that ID in your app. `ci diagnostics show <diagnostic-id>` reads the full failure. For a request in an Organization, a reader needs `organization:self_manage` in that Organization or `tenant:manage`; for any other request, only `tenant:manage`.
|
|
93
105
|
|
|
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:
|
|
106
|
+
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
107
|
|
|
96
108
|
```bash
|
|
97
|
-
ci apps credentials upsert <app-fqn-or-id> --name pipeline --env-file .env.server
|
|
98
109
|
ci api-keys upsert --principal <principal-fqn> --name pipeline \
|
|
99
110
|
--max-privileges <template-fqn> --env-file .env.pipeline
|
|
100
111
|
```
|
|
@@ -110,15 +121,31 @@ A service principal key can run Studio agent conversations without a person. It
|
|
|
110
121
|
|
|
111
122
|
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
123
|
|
|
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.
|
|
124
|
+
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.
|
|
125
|
+
|
|
126
|
+
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:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
ci apps credentials upsert <app-fqn-or-id> --name server --env-file .env.server
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
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
133
|
|
|
115
134
|
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
135
|
|
|
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.
|
|
136
|
+
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.
|
|
137
|
+
|
|
138
|
+
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
139
|
|
|
119
140
|
### MCP
|
|
120
141
|
|
|
121
|
-
The backend serves MCP at `/mcp` and at `/mcp/o/<organizationId>`. Every MCP request needs a valid Bearer
|
|
142
|
+
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:
|
|
143
|
+
|
|
144
|
+
1. A CI session token or an API key. The call acts as that person or that service principal.
|
|
145
|
+
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.
|
|
146
|
+
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.
|
|
147
|
+
|
|
148
|
+
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
149
|
|
|
123
150
|
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
151
|
|
|
@@ -126,20 +153,22 @@ A workflow becomes visible to MCP clients through an MCP operation trigger. The
|
|
|
126
153
|
|
|
127
154
|
A trigger is the entrypoint of a workflow. The core workflows package ships these triggers:
|
|
128
155
|
|
|
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
|
|
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
|
|
156
|
+
| Trigger | Starts a run when |
|
|
157
|
+
| -------------------- | -------------------------------------- |
|
|
158
|
+
| On demand | A user starts the workflow explicitly |
|
|
159
|
+
| Schedule | A cron expression fires |
|
|
160
|
+
| Webhook | Another system sends an HTTP `POST` |
|
|
161
|
+
| External application | A bound external application starts it |
|
|
162
|
+
| MCP operation | An MCP client invokes it |
|
|
163
|
+
| Entity created | A Knowledge record is created |
|
|
164
|
+
| Entity updated | A Knowledge record changes |
|
|
165
|
+
| Entity deleted | A Knowledge record is deleted |
|
|
139
166
|
|
|
140
167
|
Integration packages add message and file triggers for Slack, Microsoft 365 email, Teams and Drive, Telegram, WhatsApp, Twilio SMS and WhatsApp, and Notion.
|
|
141
168
|
|
|
142
|
-
A
|
|
169
|
+
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.
|
|
170
|
+
|
|
171
|
+
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
172
|
|
|
144
173
|
### Realtime
|
|
145
174
|
|
|
@@ -163,15 +192,66 @@ On a reset, the client drops its local view and refetches every query that a sub
|
|
|
163
192
|
|
|
164
193
|
### When CI calls you
|
|
165
194
|
|
|
166
|
-
A Gateway reverses the direction. You register a Gateway connection with an HTTPS endpoint and a setup credential, and
|
|
195
|
+
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.
|
|
196
|
+
|
|
197
|
+
### Credentials
|
|
198
|
+
|
|
199
|
+
Each credential is a separate authority. The tables group them by who holds them.
|
|
200
|
+
|
|
201
|
+
#### Held by people
|
|
202
|
+
|
|
203
|
+
| Credential | Type | Lifetime or rotation | Used for |
|
|
204
|
+
| ----------- | ------------------------------------ | ------------------------------------ | ---------------------------------------------------------------------------- |
|
|
205
|
+
| 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` |
|
|
206
|
+
| 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` |
|
|
207
|
+
|
|
208
|
+
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.
|
|
209
|
+
|
|
210
|
+
#### Held by pipelines and scripts
|
|
211
|
+
|
|
212
|
+
| Credential | Type | Lifetime or rotation | Used for |
|
|
213
|
+
| ------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
214
|
+
| 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 |
|
|
215
|
+
| `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 |
|
|
216
|
+
| 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 |
|
|
217
|
+
|
|
218
|
+
#### Held by your external app
|
|
219
|
+
|
|
220
|
+
| Credential | Type | Lifetime or rotation | Used for |
|
|
221
|
+
| ------------------ | ------------------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------- |
|
|
222
|
+
| Client id | Public OAuth identifier | Fixed for the app | Sign-in; safe in the browser |
|
|
223
|
+
| Client secret | Opaque secret, confidential apps only | Until rotated; a rotation replaces it at once | Sign-in, token renewal and member-session exchange |
|
|
224
|
+
| 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 |
|
|
225
|
+
| User access token | ES256 token, kept on the server | 300 seconds | Application API calls as the signed-in user |
|
|
226
|
+
| 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 |
|
|
227
|
+
| 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 |
|
|
228
|
+
|
|
229
|
+
The browser holds only the sealed cookie and the application id. The access token and the renewal credential stay on the server.
|
|
230
|
+
|
|
231
|
+
#### Held by AI clients
|
|
232
|
+
|
|
233
|
+
| Credential | Type | Lifetime or rotation | Used for |
|
|
234
|
+
| ----------------- | ----------------------------------- | ----------------------------------------- | ----------------------------------------------- |
|
|
235
|
+
| 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 |
|
|
236
|
+
| MCP Profile token | Opaque machine token | Until an Organization admin revokes it | MCP calls limited to one MCP Profile |
|
|
237
|
+
|
|
238
|
+
#### Between CI and outside systems
|
|
239
|
+
|
|
240
|
+
| Credential | Type | Lifetime or rotation | Used for |
|
|
241
|
+
| ------------------------ | ------------------------------------------- | ------------------------------------------- | ------------------------------------------------ |
|
|
242
|
+
| Gateway caller token | ES256 token that CI signs | 60 seconds by default, 300 at most; one use | CI calls to your Gateway |
|
|
243
|
+
| Gateway setup credential | Secret that you choose | You rotate it; CI reads it at each setup | Gateway discovery and enrollment only |
|
|
244
|
+
| 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 |
|
|
245
|
+
|
|
246
|
+
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
247
|
|
|
168
248
|
## Code entrypoints
|
|
169
249
|
|
|
170
|
-
|
|
250
|
+
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
251
|
|
|
172
252
|
### SDK subpaths
|
|
173
253
|
|
|
174
|
-
The SDKs split by where the code runs. [SDKs](../develop/sdks.md) has the full map; these are the subpaths
|
|
254
|
+
The SDKs split by where the code runs. [SDKs](../develop/sdks.md) has the full map; these are the subpaths you meet most.
|
|
175
255
|
|
|
176
256
|
| Package | Runs | Holds | Main subpaths |
|
|
177
257
|
| --------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------- |
|
|
@@ -230,6 +310,7 @@ Inside CI, a Studio or Dashboard widget enters through a hosted contribution. Yo
|
|
|
230
310
|
## Related pages
|
|
231
311
|
|
|
232
312
|
- [Platform architecture](architecture.md): Tenants, Organizations, surfaces and the package lifecycle.
|
|
313
|
+
- [Studio](../ai/studio.md): What Organization members do in Studio.
|
|
233
314
|
- [Access](access.md): Access Profiles, Access Grants and Max Privileges.
|
|
234
315
|
- [SDKs](../develop/sdks.md): Every CI package and its subpaths.
|
|
235
316
|
- [External apps](../develop/external-apps.md): The BFF, sign-in and the Gateway.
|