# SentientUI for AI agents

SentientUI is an adaptive UI personalization platform. This file tells an AI agent how to work with it.

## What it does
Each `<Adaptive>` component runs an AI optimizer that learns which variant (copy, styling, section order) converts best per visitor type, and serves it on the return visit. React SDK, SSR-safe, or one script tag for non-React sites.

## When to use

**Use this (connect over MCP) when** a user asks you to:
- inspect how a SentientUI project is performing — conversion rates, personas, goal funnels, layout stats, AI insights, or guardrail events;
- create, pause, restore, or retire component variants (headlines, CTAs, layouts) for a project; or
- add SentientUI to a React (or any web) app — scaffold the SDK and mount `<Adaptive>` components.

**Do not use this when** the task is unrelated to a SentientUI project or to adaptive/experimentation UI — it has no general web-browsing, analytics, or CMS capability beyond a connected SentientUI account.

## Connect over MCP (recommended for agents)
- **Endpoint:** `https://api.sentient-ui.com/mcp` (Streamable HTTP)
- **Live handshake on this origin:** `POST https://sentient-ui.com/.well-known/mcp`
- **Auth:** OAuth 2.1 via Clerk with dynamic client registration — no key to paste; the user signs in.
- **claude.ai / ChatGPT:** add a custom connector with the URL above.
- **Claude Code:** `claude mcp add --transport http sentientui https://api.sentient-ui.com/mcp`
- **Codex / stdio-only clients:** `npx mcp-remote https://api.sentient-ui.com/mcp`
- **Local with a server key:** `npx @sentientui/mcp` (set `SENTIENTUI_API_KEY=sk_...`)
- **Server card:** https://sentient-ui.com/.well-known/mcp/server-card.json

### Tools
`list_projects`, `create_project`, `get_project_stats`, `list_components`, `get_variant_performance`, `get_persona_breakdown`, `get_goal_funnel`, `list_goals`, `list_guardrail_events`, `get_layout_stats`, `get_insights`, `refresh_insights`, `get_variant_brief`, `get_test_brief`, `get_integration_guide`, `create_variant`, `pause_variant`.

New user with no project? Call `create_project` (needs an account login), then `get_integration_guide` to set up the SDK.

### Resources
Four `ui://sentientui/*` MCP-Apps HTML templates — `persona-breakdown`, `variant-performance`, `goal-funnel`, `layout-stats` — rendered by hosts that support MCP UI. They are static, self-contained, and read without a bearer token.

## CLI

The official command-line tool is [`@sentientui/cli`](https://www.npmjs.com/package/@sentientui/cli) on npm.

```bash
npx @sentientui/cli init      # scaffold into an existing React app
npx @sentientui/cli --help    # all commands
```

`init` detects the framework (Next.js App/Pages Router, Vite, Remix, CRA), installs `@sentientui/react`, writes `.env.local`, and scaffolds an example. It does not edit your layout — wrap the app in `<AdaptiveRoot>` yourself. It works with **no API key** in keyless local mode, so you can scaffold and verify before an account exists.

Full CLI reference: https://sentient-ui.com/docs/developers#cli

## Set up the SDK in a codebase
1. Install `@sentientui/react` (or use `npx @sentientui/cli init` for keyless local mode first).
2. Wrap the app and mount `<Adaptive>` components. See https://sentient-ui.com/docs.

## API
- Developer resources: https://sentient-ui.com/docs/developers
- OpenAPI: https://api.sentient-ui.com/openapi.json
- Reference: https://api.sentient-ui.com/docs
- API catalog (RFC 9727): https://sentient-ui.com/.well-known/api-catalog
- Auth: `Authorization: Bearer <key>` — `pk_` for browser ingest, `sk_` for management and server-truth conversions, OAuth 2.1 for MCP.

## Reading this site
Every page answers `Accept: text/markdown` with a markdown representation of itself (`Vary: Accept`). Unknown paths return a real HTTP 404 whose markdown body links back to the sitemap, `llms.txt`, and the developer resources index.

- https://sentient-ui.com/llms.txt
- https://sentient-ui.com/.well-known/agent-skills (JSON, or markdown with `Accept: text/markdown`)
- https://sentient-ui.com/sitemap.xml