@sentientui/mcp 0.26.0 → 0.28.0

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/AGENTS.md CHANGED
@@ -4,7 +4,33 @@ SentientUI is a UI personalization platform that assigns visitors to variant com
4
4
 
5
5
  ## Key Concepts
6
6
 
7
- **Persona / Cluster** — visitors are clustered by behavior into labeled groups. A `reliability_score` (0–1) measures confidence in the assignment. Low reliability means the engine won't personalize for that session even if a cluster is assigned.
7
+ **Audiences — and what makes each one serve.** When a visitor fits several, the order is declared › retargeting › discovered › campaign › arrival › everyone.
8
+
9
+ - **Everyone** (key `unknown`) — every visitor no other audience claims; usually most of the traffic.
10
+ - **Declared persona** (a bare key such as `developer`) — a role the site already knows, e.g. from sign-in. It serves **only on visits where the site declares it**: the `persona` prop on `<AdaptiveRoot>` / `<AdaptiveProvider>`, `init({ persona })` in `@sentientui/core`, or `window.sentient.persona` on the script tag (a string, or a function read once at start-up). The value must be exactly a key from the dashboard's Audiences → Personas list. Adding a persona there only names it: one the site never sends has no visitors, and versions written for it reach nobody. Undeclared visitors are never guessed into a declared persona — for anonymous traffic use campaigns, arrival types or discovered audiences.
11
+ - **Discovered audience** (`d-…`) — found in real behaviour; it serves only after it is promoted, which needs evidence that it wants something different.
12
+ - **Campaign, arrival type, retargeting group** (`c-…`, `a-…`, `r-…`) — visitors who arrived on a named campaign's link, arrived a certain way, or were moved into a retargeting group after a campaign. A version restricted to one of these ("Show to", `manage_tests` `restrict_versions`) is shown only to them. A declared persona cannot be a "Show to" target.
13
+ - **Behaviour groups** (`get_persona_breakdown` `behaviourGroups`) — visitors whose visit patterns look alike ("Behaviour group 2"). Reporting only: they are **not** personas or audiences, nothing is shown to them, and they are never named after an audience. `get_persona_breakdown` `personas` counts the audience each visit was actually **served as** — the same number as the Matrix share in `get_cell_matrix`.
14
+ - **Names never target.** A version's display name, or a key in code `variants`, does not choose who sees it. To give one audience one version every time, pin it (`manage_approvals` `pin`, or the dashboard's "Always show this to …"). Pinned visitors stop teaching the optimizer for that component.
15
+
16
+ **Hybrid components need Migrate first.** An `<Adaptive>` with children **and** `variants` whose id already ran a variants test keeps serving that old test. Generated or dashboard-written versions for it do not serve — even when approved — until it is migrated (dashboard Components → the component → Migrate…, or `manage_tests` `migrate_component`). Check before you generate for one.
17
+
18
+ **Funnels need a source per step.** A funnel is an ordered list of goal ids, and every step must have something that sends it — a page-visit goal, a click or form goal, `useGoal` in the browser, or `trackServerGoal` from the backend. A step nothing sends never fills, and the funnel reads as broken. Join a component to a funnel with `<Adaptive id="…" funnel="<funnelId>">`.
19
+
20
+ **Server goals — the exact call.** From a route handler, server action or webhook only (it needs the secret key):
21
+
22
+ ```ts
23
+ import { trackServerGoal } from '@sentientui/react/server'; // non-React backend: '@sentientui/core/server'
24
+
25
+ await trackServerGoal({
26
+ serverKey: process.env.SENTIENT_SECRET_KEY!, // the project's sk_ key
27
+ userId: user.id, // the id the site identifies the visitor with, e.g. <AdaptiveRoot userId={user.id}>
28
+ name: 'subscribed', // the goal id, exactly as defined
29
+ dedupeKey: user.id, // your own id for this conversion; a retry counts once
30
+ });
31
+ ```
32
+
33
+ In the visitor's own request, pass `sessionId: readSessionCookie(cookies, publicKey)` (same import) instead of `userId`. It resolves `'recorded'`, `'skipped_no_visitor'` or `'failed'` and never throws. There is no `sentientui.trackServerGoal(name, visitorId)` form.
8
34
 
9
35
  **Variant** — a version of an adaptive component. There are **two kinds**, and the difference matters:
10
36
 
@@ -23,6 +49,17 @@ Only call `create_variant` for the no-code path. If the user is writing (or you
23
49
 
24
50
  **Layout stats** — per-persona section ordering driven by a bandit algorithm. `pulls` = times a layout was applied, `avgReward` = normalized conversion signal (not raw CVR).
25
51
 
52
+ ## Excluding your team and test sites
53
+
54
+ Visits marked **internal** still see your versions — so QA on staging keeps working — but never count in any report (People, conversions, the Matrix share, funnels) and never teach the optimizer. Reports and `get_traffic_breakdown` list them as **Your team / test sites**. They are set up in the dashboard under **Settings → Internal traffic**, four ways:
55
+
56
+ - **Internal sites** — switch on any allowed domain (staging, preview, `localhost`); every visit from it is internal. Only allowed domains can be chosen.
57
+ - **Team emails & domains** — `@example.com` for a whole team, `name@example.com` for one person. They match visitors the site identifies with their email: `identify(userId, { email })` (core, or `useSentient()` in React) or `window.SentientSnippet.identify(userId, { email })` on the script tag. The SDK sends a SHA-256 of the trimmed, lowercased address and its domain — never the address — and exact rules are stored as the same hash and shown masked.
58
+ - **Browser link** — `https://<site>/?sentient_internal=<token>` opened once marks that browser; `?sentient_internal=off` stops it. Rotating the link un-marks every browser.
59
+ - **Code flag** — `<AdaptiveRoot internal={…}>` / `<AdaptiveProvider internal>`, `init({ internal })` in `@sentientui/core`, or `window.sentient.internal` (a boolean, or a function read once at start-up). Example: `internal={user.email.endsWith('@example.com')}` — the email never leaves the site.
60
+
61
+ It applies from when it is turned on: earlier visits can't be separated, because which site a visit came from was not recorded before. A visit marked internal after it already trained (a late identify, a rule added later) drops out of every report on the next read but is not untrained. There is no report filter or IP rule. `get_internal_traffic_rules` reads the rules (read-only; a person changes them in the dashboard).
62
+
26
63
  ## Auth
27
64
 
28
65
  Server keys start with `sk_` — required for the management API, available on every plan including Free. Public keys (`pk_`) are for the React SDK only and will be rejected. An `sk_` key is scoped to **one project**: `list_projects` returns only that project and other project ids are refused. For several projects, connect by URL with an OAuth sign-in. `create_project` needs that OAuth login.
@@ -36,7 +73,7 @@ Every write tool changes what real visitors see or what the project accepts —
36
73
  |------|--------|-------|
37
74
  | `list_projects` | read | Start here to get project IDs (an `sk_` key sees only its own project) |
38
75
  | `create_project` | write | Onboard a new user: creates a project + returns its `pk_` key. Needs an account login (OAuth) — refuses `sk_` project keys and demo tokens. Follow with `get_integration_guide` |
39
- | `get_project_stats` | read | Health status + 24h events and People count. `agentCalls` counts calls to the `/v1/agent` API (all retained history) — not MCP tool calls |
76
+ | `get_project_stats` | read | Health status + 24h events and People count. `agentCalls` counts calls to the `/v1/agent` API (all retained history) — not MCP tool calls. `rejectedOrigins` lists sustained domains being turned away (not allowed; count = minutes with traffic) |
40
77
  | `add_origin` | write | Allow-list a site origin so the SDK's events from it are accepted. Idempotent |
41
78
  | `list_components` | read | Components + variant counts + impression totals |
42
79
  | `get_variant_performance` | read | Per-(component, variant) rate with its n (converting / exposed sessions, range/from/to; default 7d), plus the server's evidence verdict on that windowed rate vs the component's baseline (`verdict`: ahead / behind / unclear; `verdictBasis` says window, or all_time on older APIs) and the all-time verdict as reliability (`evidenceState`, `reliabilityVerdict`). Only ahead/behind is a result; the preceding-window change is an untested descriptor |
@@ -55,8 +92,15 @@ Every write tool changes what real visitors see or what the project accepts —
55
92
  | `list_funnels` | read | Defined multi-step funnels |
56
93
  | `get_funnel_report` | read | Step-by-step funnel drop-off |
57
94
  | `list_guardrail_events` | read | Every variant still paused by a guardrail; `days` narrows to recent pauses |
58
- | `get_persona_breakdown` | read | Cluster distribution + avg reliability per cluster (all retained sessions, not windowed) |
95
+ | `get_persona_breakdown` | read | Visitors per audience they were served as (30 days, the Matrix share) + behaviour groups (not audiences) |
59
96
  | `get_stage_breakdown` | read | E-commerce funnel stages: stage mix (observed vs hinted), arrival channel x stage, stage moves between visits, tested holdout lift per first-visit context and channel (the headline lift's always-valid test, all-time, alpha split over 23 series), versions per context with evidence (windowed, observational) |
97
+ | `get_known_people` | read | Known people: visitors split into new, returning and already past the main goal (one per person), first-time vs repeat main-goal conversions, and the stored known-people list by how each was learnt (reporting only) |
98
+ | `get_main_funnel` | read | The main funnel: people at each step on the way to the main goal — Arrived, the funnel's steps, the main goal — for new and returning visitors, with people who already converted left out, drop-off per step and step health |
99
+ | `get_page_groups` | read | Page groups: the site's pages in named groups, where each sits on the main funnel, and per group the people who viewed it, the components that live there (where they were actually shown), layouts served, plus site-wide components |
100
+ | `get_plan` | read | Sentient's plan: tests running (day and a status word per version), winners waiting for a decision, proposals with their reason and the versions that could be tested, and what was learned |
101
+ | `get_test` | read | One test: its versions, the people counted and how many reached the goal, a status word per version, and how it ended |
102
+ | `get_page_elements` | read | The elements the site check found (buttons, headlines, forms), each with the id manage_generation open_pr needs to send a change to your code |
103
+ | `get_needs_you` | read | Needs you: versions waiting for approval, failed work, winners to keep, changes with your developers (pull request, checks, review) and what just finished |
60
104
  | `get_layout_stats` | read | Per-persona layout order + bandit pulls/reward (cumulative state, not windowed) |
61
105
  | `get_insights` | read | Ranked measured findings (tier + sample, low-sample flagged; `limit`, default 10) + (Growth) AI narrations, which are unmeasured |
62
106
  | `refresh_insights` | write | Async trigger — wait ~15s then call `get_insights`. Starter+ and an editor/admin role |
@@ -66,7 +110,8 @@ Every write tool changes what real visitors see or what the project accepts —
66
110
  | `list_cell_reviews` | read | Generated versions waiting for approval |
67
111
  | `review_cell` | write | Approve (publishes to live traffic) or reject one waiting version |
68
112
  | `get_agent_traffic` | read | AI crawlers / automated browser sessions / agent API callers reading the site (windowed; paid plans) |
69
- | `get_traffic_breakdown` | read | Where traffic came from: People vs visitors we couldn't confirm vs automated (7 groups, windowed) |
113
+ | `get_traffic_breakdown` | read | Where traffic came from: People vs visitors we couldn't confirm vs automated vs your team / test sites (windowed) |
114
+ | `get_internal_traffic_rules` | read | How the project keeps its team and test sites out of its numbers: internal sites, team email domains and masked emails, browser link, sessions marked internal (7 days) |
70
115
  | `get_agent_legibility` | read | Whether agent-read pages are machine-legible, with fixes (paid plans) |
71
116
  | `get_agent_access` | read | Which areas a person has allowed agents to change (read this before a write; only a person can change it) |
72
117
  | `list_campaigns` | read | Named campaigns, retargeting groups and campaigns seen in traffic; with `campaignId`, one campaign card |
@@ -75,11 +120,11 @@ Every write tool changes what real visitors see or what the project accepts —
75
120
  | `get_site_styles` | read | Captured site styles per role, whether colors were measured, last scan, audit score |
76
121
  | `get_region_history` | read | A region's published versions and whether it is still found on the live page |
77
122
  | `manage_generation` | write | Generate and edit written versions: queue generation, auto-fill, rewrite depth, regions, campaign versions, pull requests (Generate area) |
78
- | `manage_approvals` | write | Approve or reject generated versions, require approval, publish, roll back or pin a region version, promote a variant (Approve and publish area) |
79
- | `manage_tests` | write | Archive or restore components and regions, lift guardrail pauses, proof window, observation-only mode, restrict versions by context (Run tests area) |
123
+ | `manage_approvals` | write | Approve or reject generated versions, require approval, publish, roll back or pin a region version, promote a variant, keep a test's winner (Approve and publish area) |
124
+ | `manage_tests` | write | Propose, start, stop or skip a test and turn down a winner; archive or restore components and regions, lift guardrail pauses, proof window, observation-only mode, restrict versions by context (Run tests area) |
80
125
  | `manage_goals` | write | Edit, publish or archive goals and funnels, set a goal role, confirm or dismiss discovered goals and goal-name warnings (Goals and funnels area) |
81
126
  | `manage_campaigns` | write | Campaigns, retargeting and audiences: create, update, promote or roll back, plus stage and search settings (Campaigns and audiences area) |
82
- | `manage_settings` | write | Project settings: edit the project, origins, webhooks, site styles, report shares, previews, models, test events (Project settings area); accept, dismiss or save a structured insight is always allowed |
127
+ | `manage_settings` | write | Project settings: edit the project, origins, webhooks, site styles, report shares, previews, models, test events, who counts as already converted (gate setting, import of known people) (Project settings area); accept, dismiss or save a structured insight is always allowed |
83
128
  | `get_integration_guide` | read | SDK setup guide (static) |
84
129
  <!-- mcp-tools:end -->
85
130
 
@@ -116,9 +161,16 @@ The evidence state (from the brief) drives the change. It is keyed on the server
116
161
  3. Review mode: `list_cell_reviews`, show the user the version, then `review_cell` with `approve` or `reject`
117
162
 
118
163
  **Understand the audience**
119
- 1. `get_persona_breakdown` — cluster sizes + reliability
120
- 2. `get_layout_stats` — what layout order each persona gets
121
- 3. `get_insights` — AI narrative on what changed
164
+ 1. `get_audiences` — declared and discovered audiences, and what blocks promotion
165
+ 2. `get_cell_matrix` — each audience's served share and what it sees (a declared persona at 0% is one the site never declares)
166
+ 3. `get_persona_breakdown` — who was served as which audience (the Matrix share), and, apart, behaviour groups (descriptive, never audiences)
167
+ 4. `get_layout_stats` — what layout order each persona gets
168
+ 5. `get_insights` — AI narrative on what changed
169
+
170
+ **"Why doesn't audience X see its version?"**
171
+ 1. `get_cell_matrix` — is X's share 0? A declared persona the site never sends has no visitors: give the user the declaration line for their setup (see Audiences above)
172
+ 2. Is the component a hybrid with an old variants test? Its new versions wait for `migrate_component`
173
+ 3. Is the version waiting for approval (`list_cell_reviews`) or restricted to a campaign?
122
174
 
123
175
  **Validate before going live (shadow mode)**
124
176
  - Shadow mode is enabled/disabled in the dashboard (Project Settings)
@@ -137,3 +189,10 @@ The evidence state (from the brief) drives the change. It is keyed on the server
137
189
  - Using `restore_variant` to activate a draft — it is for retired variants; activate drafts with `update_variant` `status: active`
138
190
  - Using a `pk_` key instead of `sk_` — it will be rejected
139
191
  - Interpreting `avgReward` in layout stats as a conversion rate — it's a bandit reward signal, not CVR
192
+ - Reporting a behaviour group as an audience's visitors — behaviour groups are not personas; an audience's visitors are `get_persona_breakdown` `personas` (= the Matrix share)
193
+ - Expecting a declared persona to serve because it is in the vocabulary — the site has to declare it on the visit
194
+ - Naming a version (or a code `variants` key) after an audience and expecting it to target them — pin it instead
195
+ - Generating versions for a hybrid component that still has its old variants test — nothing serves until `migrate_component`
196
+ - Building a funnel over goal ids nothing sends — every step needs a source
197
+ - Writing any other call shape for server goals than the `trackServerGoal({ … })` block above
198
+ - Telling a user to filter staging or team traffic out of a report — there is no report filter or IP rule; point them to Settings → Internal traffic (it applies from when it is turned on), and read the current rules with `get_internal_traffic_rules`
package/README.md CHANGED
@@ -87,7 +87,7 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
87
87
  |------|--------|-------------|
88
88
  | `list_projects` | read | List the projects this credential can see (an `sk_` key sees only its own project) |
89
89
  | `create_project` | write | Create a project and return its `pk_` public key (account login only — not an `sk_` key or demo token) |
90
- | `get_project_stats` | read | Ingestion health: status, 24h events and People (with how many are being analysed or automated), and calls to the `/v1/agent` API (`agentCalls` — not MCP tool calls) |
90
+ | `get_project_stats` | read | Ingestion health: status, 24h events and People (with how many are being analysed or automated), and calls to the `/v1/agent` API (`agentCalls` — not MCP tool calls), plus sustained domains the snippet runs on that are turned away (not allowed) |
91
91
  | `add_origin` | write | Allow-list a site origin so the SDK's events from it are accepted (idempotent) |
92
92
  | `list_components` | read | Adaptive components with variant counts and impressions |
93
93
  | `get_variant_performance` | read | Per-(component, variant) rates with their n and the server's evidence verdict vs the baseline (range 7d/30d/90d/all or from/to; default 7d; the verdict judges the windowed rate, with all-time reliability reported separately) |
@@ -106,8 +106,15 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
106
106
  | `list_funnels` | read | Defined multi-step funnels |
107
107
  | `get_funnel_report` | read | Step-by-step funnel drop-off |
108
108
  | `list_guardrail_events` | read | Every variant currently paused by a guardrail (pass `days` to see only pauses from the last N days) |
109
- | `get_persona_breakdown` | read | Visitor clusters with session counts and reliability (all retained sessions) |
109
+ | `get_persona_breakdown` | read | Visitors per audience they were served as (30 days — the Matrix share), plus behaviour groups (visitors who behaved alike — never audiences) |
110
110
  | `get_stage_breakdown` | read | E-commerce funnel stages: stage mix, arrival channel x stage, stage moves between visits, tested holdout lift per first-visit context and channel (all-time), and versions per context (windowed, observational) |
111
+ | `get_known_people` | read | Known people: visitors split into new, returning and already past the main goal (one per person), first-time vs repeat main-goal conversions, and the stored known-people list by how each was learnt (reporting only) |
112
+ | `get_main_funnel` | read | The main funnel: people at each step on the way to the main goal — Arrived, the funnel's steps, the main goal — for new and returning visitors, with people who already converted left out, drop-off per step and step health |
113
+ | `get_page_groups` | read | Page groups: the site's pages in named groups, where each sits on the main funnel, and per group the people who viewed it, the components that live there (where they were actually shown), layouts served, plus site-wide components |
114
+ | `get_plan` | read | Sentient's plan: tests running (day and a status word per version), winners waiting for a decision, proposals with their reason and the versions that could be tested, and what was learned |
115
+ | `get_test` | read | One test: its versions, the people counted and how many reached the goal, a status word per version, and how it ended |
116
+ | `get_page_elements` | read | The elements the site check found (buttons, headlines, forms), each with the id manage_generation open_pr needs to send a change to your code |
117
+ | `get_needs_you` | read | Needs you: versions waiting for approval, failed work, winners to keep, changes with your developers (pull request, checks, review) and what just finished |
111
118
  | `get_layout_stats` | read | Per-persona section order with bandit pulls and reward (cumulative state) |
112
119
  | `get_insights` | read | Ranked measured findings with their sample (low samples flagged), plus AI narrations marked unmeasured |
113
120
  | `refresh_insights` | write | Regenerate AI insights — needs Starter or higher and an editor/admin role (a paid model call); advisor recommendations are Growth+ |
@@ -117,7 +124,8 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
117
124
  | `list_cell_reviews` | read | Generated versions waiting for approval (review mode) |
118
125
  | `review_cell` | write | Approve (publish) or reject one generated version waiting for review |
119
126
  | `get_agent_traffic` | read | Which AI crawlers, automated browser sessions and agent API callers read the site (windowed; paid plans) |
120
- | `get_traffic_breakdown` | read | Where traffic came from: People vs visitors we couldn't confirm vs automated (7 groups, windowed) |
127
+ | `get_traffic_breakdown` | read | Where traffic came from: People vs visitors we couldn't confirm vs automated vs your team / test sites (windowed) |
128
+ | `get_internal_traffic_rules` | read | How the project keeps its team and test sites out of its numbers: internal sites, team email domains and masked emails, browser link, sessions marked internal (7 days) |
121
129
  | `get_agent_legibility` | read | Whether the pages agents read are machine-legible, with fixes (paid plans) |
122
130
  | `get_agent_access` | read | Which areas a person has allowed agents to change (read this before a write; only a person can change it) |
123
131
  | `list_campaigns` | read | Named campaigns, retargeting groups and campaigns seen in traffic; with `campaignId`, one campaign card |
@@ -126,11 +134,11 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
126
134
  | `get_site_styles` | read | Captured site styles per role, whether colors were measured, last scan, audit score |
127
135
  | `get_region_history` | read | A region's published versions and whether it is still found on the live page |
128
136
  | `manage_generation` | write | Generate and edit written versions: queue generation, auto-fill, rewrite depth, regions, campaign versions, pull requests (Generate area) |
129
- | `manage_approvals` | write | Approve or reject generated versions, require approval, publish, roll back or pin a region version, promote a variant (Approve and publish area) |
130
- | `manage_tests` | write | Archive or restore components and regions, lift guardrail pauses, proof window, observation-only mode, restrict versions by context (Run tests area) |
137
+ | `manage_approvals` | write | Approve or reject generated versions, require approval, publish, roll back or pin a region version, promote a variant, keep a test's winner (Approve and publish area) |
138
+ | `manage_tests` | write | Propose, start, stop or skip a test and turn down a winner; archive or restore components and regions, lift guardrail pauses, proof window, observation-only mode, restrict versions by context (Run tests area) |
131
139
  | `manage_goals` | write | Edit, publish or archive goals and funnels, set a goal role, confirm or dismiss discovered goals and goal-name warnings (Goals and funnels area) |
132
140
  | `manage_campaigns` | write | Campaigns, retargeting and audiences: create, update, promote or roll back, plus stage and search settings (Campaigns and audiences area) |
133
- | `manage_settings` | write | Project settings: edit the project, origins, webhooks, site styles, report shares, previews, models, test events (Project settings area); accept, dismiss or save a structured insight is always allowed |
141
+ | `manage_settings` | write | Project settings: edit the project, origins, webhooks, site styles, report shares, previews, models, test events, who counts as already converted (gate setting, import of known people) (Project settings area); accept, dismiss or save a structured insight is always allowed |
134
142
  | `get_integration_guide` | read | SDK setup guide (static — same for every project) |
135
143
  <!-- mcp-tools:end -->
136
144
 
@@ -138,12 +146,32 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
138
146
  >
139
147
  > **Generated versions.** An `<Adaptive id="…">` that wraps your original as children (no `variants`) registers as a personalizable region once it is mounted and deployed. Its versions per visitor type are written in SentientUI — inspect and fill them with `get_cell_matrix`, `get_cell_detail`, and `generate_cell` — with no code change or redeploy. When the project has review mode on, a generated version waits in `list_cell_reviews` until `review_cell` approves it.
140
148
  >
149
+ > **Which audiences actually serve.** A *declared* persona serves only on visits where your site declares it (`persona` prop on `<AdaptiveRoot>` / `<AdaptiveProvider>`, `init({ persona })`, or `window.sentient.persona`) — adding it to the vocabulary only names it. A *discovered* audience serves once it is promoted. *Campaigns*, arrival types and retargeting groups reach visitors by how they arrived, which is how to reach anonymous traffic. `get_persona_breakdown` counts the audience each visit was actually served as (the Matrix share); its `behaviourGroups` are descriptive groups of similar behaviour, not personas — never read one as an audience's visitors. A version's name never targets anyone — pin it to an audience instead. Pinned visitors stop teaching the optimizer for that component.
150
+ >
151
+ > **Hybrid components need Migrate.** An `<Adaptive>` with children *and* `variants` whose id already ran a variants test keeps serving that test; generated versions for it do not serve until it is migrated (`manage_tests` `migrate_component`, or Migrate… in the dashboard).
152
+ >
153
+ > **Funnels and server goals.** Every funnel step needs something that sends it. For a step your backend confirms, the call is `trackServerGoal({ serverKey, userId, name, dedupeKey })` from `@sentientui/react/server` (or `@sentientui/core/server`) — see `AGENTS.md` for the exact block.
154
+ >
141
155
  > **Code-native vs no-code variants.** Variants you declare in your app (`<Adaptive variants={{…}}>`) register automatically the first time the SDK requests an assignment after you deploy — they go live immediately and need **no** `create_variant` call. Use `create_variant` only for **no-code** variants whose content is stored in SentientUI and rendered without a code change; these start as drafts — activate one with `update_variant` (`status: active`) or from the dashboard.
142
156
  >
143
157
  > **Optimizing a component?** Call `get_variant_brief` first. It returns each variant's rate with its sample and the server's evidence verdict, the audience, measured findings, and an evidence-state assessment — then your AI assistant writes a new on-brand variant directly into your code (which auto-registers on deploy). While nothing is decided, the brief falls back to best-practice priors for your project's context type so the assistant still makes a sensible change.
144
158
 
159
+ ## Excluding your team and test sites
160
+
161
+ Visits marked **internal** still see your versions — so QA on staging keeps working — but never count in any report (People, conversions, the Matrix share, funnels) and never teach the optimizer. Reports and `get_traffic_breakdown` list them as **Your team / test sites**. They are set up in the dashboard under **Settings → Internal traffic**, four ways:
162
+
163
+ - **Internal sites** — switch on any allowed domain (staging, preview, `localhost`); every visit from it is internal. Only allowed domains can be chosen.
164
+ - **Team emails & domains** — `@example.com` for a whole team, `name@example.com` for one person. They match visitors the site identifies with their email: `identify(userId, { email })` (core, or `useSentient()` in React) or `window.SentientSnippet.identify(userId, { email })` on the script tag. The SDK sends a SHA-256 of the trimmed, lowercased address and its domain — never the address — and exact rules are stored as the same hash and shown masked.
165
+ - **Browser link** — `https://<site>/?sentient_internal=<token>` opened once marks that browser; `?sentient_internal=off` stops it. Rotating the link un-marks every browser.
166
+ - **Code flag** — `<AdaptiveRoot internal={…}>` / `<AdaptiveProvider internal>`, `init({ internal })` in `@sentientui/core`, or `window.sentient.internal` (a boolean, or a function read once at start-up). Example: `internal={user.email.endsWith('@example.com')}` — the email never leaves the site.
167
+
168
+ It applies from when it is turned on: earlier visits can't be separated, because which site a visit came from was not recorded before. A visit marked internal after it already trained (a late identify, a rule added later) drops out of every report on the next read but is not untrained. There is no report filter or IP rule. `get_internal_traffic_rules` reads the rules (read-only; a person changes them in the dashboard).
169
+
145
170
  ## Example prompts
146
171
 
172
+ The whole loop — setup, goals, versions, pull requests, tests — can run from your agent. The tool-by-tool order is in [Run Sentient from your agent](https://sentient-ui.com/docs#run-from-agent).
173
+
174
+
147
175
  - *"What projects do I have?"*
148
176
  - *"Show me the CVR trends for the hero banner this week"*
149
177
  - *"Are any variants paused by the guardrail right now?"*
@@ -151,6 +179,8 @@ A demo token is provisioned automatically — 10 calls/month, read-only (write t
151
179
  - *"Refresh insights for project X"*
152
180
  - *"Optimize my hero CTA — pull the brief and add a new variant in the code"*
153
181
  - *"Create a new variant called 'short-copy' for the pricing CTA"*
182
+ - *"What should we test next? Start it with the shorter version."*
183
+ - *"Is anything waiting for me? How is our pull request doing?"*
154
184
 
155
185
  ## Configuration
156
186