Agent integration rules

Cursor can install Answers. Open Answers Keys at https://app.bootstrapware.co/answers/keys and click Add to Cursor (OAuth). The MCP endpoint is https://answers.bootstrapware.co/mcp.

Paste this into AGENTS.md, Cursor rules, or your agent system prompt when adding Bootstrapware Answers. The same file ships with the package. Install with pnpm add @bootstrapware/answers. Non-React pages use the Hosted script embed.

# Integrating @bootstrapware/answers

Use this file as agent instructions. The React widget and the Hosted Answers service are separate. This file is the install contract: config, keys, MCP, the widget, the script embed, and the Hosted ask route that already exists.

## What this package does

Visitors ask a question about the page. The widget shows one complete answer with citations, or an explicit fallback when the result is `unanswered`.

**Free:** local sample and test keys. No card. Pass `createLocalAdapter()`, or omit `adapter` when you also omit `publishableKey`. The sample answers hours, returns, and shipping for Northwind Outfitters. It does not call the network.

**BYO ($9.99):** live app config. Knowledge, retrieval, the model, and visitor logs stay on the customer backend. Pass an `AnswersAdapter`, or `createByoAdapter(impl)`.

**Hosted ($19.99):** live app config, and Hosted stores approved sources, the derived index, visitor questions, optional conversations, unanswered items, and citations. Hosted includes 2,500 answers per workspace each month, 1 GiB of knowledge and index, 2,000 sources, 4,000 indexed chunks per app, 20 MiB per file, and 30 days of conversation history. Hitting a ceiling stops that axis.

Stack discount is company-wide: 25% off the second paid product's list, 35% off the third and later. Env names only: `STRIPE_PRICE_ANSWERS_BYO` and `STRIPE_PRICE_ANSWERS_HOSTED`. Do not invent Stripe price ids.

`@bootstrapware/answers` is published to npm: `pnpm add @bootstrapware/answers`. Non-React pages can still use the Hosted script embed. The Cursor Marketplace listing is separate and is not implied by this file. Do not invent a version or a tarball. The imports in this file are the package contract.

Publishable env: `NEXT_PUBLIC_BSW_ANSWERS_PUBLISHABLE_KEY`.

Pass `appId` and `publishableKey` with no `adapter` and the React component and the script embed call Hosted ask. `createHostedAdapter({ appId, publishableKey })` is that client. A publishable key without an app id does not fetch.

## Install algorithm (do this in order)

1. Read this file. Call `list_answers_capabilities` on Answers MCP before inventing tools.
2. If the user only needs a working UI in this app: Path A. Do not invent keys.
3. If they need live Hosted ask: Path B.
4. If they need their own backend: Path C.
5. Never mint live or secret API keys via MCP or in the browser. For a test publishable key, call `ensure_answers_test_publishable`.

### Path A: local, zero keys

```tsx
import { Answers, createLocalAdapter } from "@bootstrapware/answers";
import "@bootstrapware/answers/styles.css";

<Answers adapter={createLocalAdapter()} />
```

Try these questions, in order, on one session:

1. `What is your return window?` Answered. Citation id `ane_returns`.
2. `How long do I have?` Follow-up on that same session. A new session returns unanswered.
3. `What are your hours?` Answered. Citation id `ane_hours`.
4. `Is shipping free?` Answered. Citation id `ane_shipping`.
5. `Do you price match?` Unanswered, with the sample fallback.

`onFallback` runs for unanswered results. The widget does not render an answer body for that outcome.

### Path B: Hosted

1. Confirm Cursor MCP `bootstrapware-answers` at `https://answers.bootstrapware.co/mcp` (OAuth URL-only). If disconnected, tell the human to click **Add to Cursor (OAuth)** on https://app.bootstrapware.co/answers/keys
2. `list_answers_capabilities` → `create_answers_app` → `update_answers_draft` (toggles + `allowedOrigins` for localhost and production; `name` is optional) → `publish_answers_app`
3. `ensure_answers_test_publishable`. Put `envLine` in `.env.local`. The full test publishable is returned every time. The env name is `NEXT_PUBLIC_BSW_ANSWERS_PUBLISHABLE_KEY`.
4. `get_answers_install_snippet`. `appId` is real. Use `process.env.NEXT_PUBLIC_BSW_ANSWERS_PUBLISHABLE_KEY`. Never invent a key and never put a secret in the snippet.
5. The snippet passes `appId` and `publishableKey`. That posts to `POST /api/v1/ask?appId=`.
6. `add_answers_url_source` for each dedicated public page whose body already states the fact (`/pricing`, hours, returns). Do not stop at the homepage.
7. After the index job succeeds, tell the human to ask through the widget with a test key: a product question, a follow-up that names no product, and a question the pages do not answer. The dashboard retrieval check shows which passages a question finds.

`create_answers_app` returns these `nextSteps`, in order:

1. Call `update_answers_draft` with `allowedOrigins` for localhost and production. Name is optional.
2. Call `publish_answers_app`.
3. Call `ensure_answers_test_publishable` to get or create a test publishable key.
4. Call `get_answers_install_snippet`. `appId` and `publishableKey` call Hosted ask. No hand-written adapter.
5. Call `add_answers_url_source` with a dedicated public page whose body already states the fact. A homepage of product blurbs is a weak first source.
6. After the index job succeeds, ask through the widget with a test key: a product question, a follow-up that names no product, and a question the pages do not answer. The dashboard retrieval check shows which passages a question finds.

`publish_answers_app` returns:

1. Call `ensure_answers_test_publishable` to get or create a test publishable key.
2. Call `get_answers_install_snippet`. `appId` and `publishableKey` post to `POST /api/v1/ask`.
3. Call `add_answers_url_source` with a dedicated public page whose body already states the fact. A homepage of product blurbs is a weak first source.
4. After the index job succeeds, ask through the widget with a test key: a product question, a follow-up that names no product, and a question the pages do not answer. The dashboard retrieval check shows which passages a question finds.

```tsx
import { Answers } from "@bootstrapware/answers";
import "@bootstrapware/answers/styles.css";

<Answers
  appId="ana_demo"
  publishableKey={process.env.NEXT_PUBLIC_BSW_ANSWERS_PUBLISHABLE_KEY}
  suggestedQuestions={["What is your return window?"]}
  shortcut="mod+k"
/>
```

`suggestedQuestions` renders clickable starter chips. `shortcut="mod+k"` opens the widget and focuses the question (Command on macOS, Control elsewhere). The same props work on `BootstrapwareAnswers.mount`. `createHostedAdapter({ appId, publishableKey, apiBaseUrl })` posts to `POST /api/v1/ask?appId=` when you want the client as an `adapter`. Optional `apiBaseUrl` defaults to `https://answers.bootstrapware.co`.

`get_answers_install_snippet` substitutes the published `ana_` id. Optional API host in the snippet defaults to `https://answers.bootstrapware.co`.

The ask body is `{ sessionId, question, pageContext }`. `pageContext` is `{ url, title }` only. The widget does not send the DOM. Success is `{ data }` with `outcome` `answered` or `unanswered`. An answered result includes `answer` and citations whose ids came from retrieval. An unanswered result includes `fallback` and no answer text. There is no public confidence percentage. The response is complete. It does not stream.

Live publishable config and live Hosted writes need a paid plan. Test keys work unpaid. Live Hosted writes need Hosted ($19.99). Live config needs BYO ($9.99) or Hosted ($19.99).

Public URL sources are `add_answers_url_source` with `kind` `website`, `sitemap`, or `url`. `reindex_answers_app` takes that same URL, or omits `url` to reindex the app. Neither tool accepts file bytes or a question.

### Path C: BYO

Same MCP app config as Path B. Implement `AnswersAdapter` on the customer backend. `createByoAdapter(impl)` returns that adapter. Knowledge, retrieval, the model, and visitor logs never go to Bootstrapware.

`ask` receives `{ sessionId, question, pageContext }` and returns `{ sessionId, answerId, outcome, answer?, citations?, fallback? }`. `outcome` is `answered` or `unanswered`. Optional `feedback({ sessionId, answerId, helpful })`.

```tsx
<Answers
  appId="ana_demo"
  adapter={createByoAdapter({
    ask: async (input) => {
      const response = await fetch("/api/answers/ask", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(input),
      });
      if (!response.ok) throw new Error("Could not ask.");
      return response.json();
    },
  })}
/>
```

The fastest BYO backend is the engine in this package: `createAnswersBackend` from `@bootstrapware/answers/server` (Node 18+). It indexes your sitemap, URLs, or documents, plus custom Q&A, and its `handler(request)` speaks the same JSON contract as the widget adapter. `OPENAI_API_KEY` stays in server env.

```ts
import { createAnswersBackend } from "@bootstrapware/answers/server";

const answers = createAnswersBackend({
  siteName: "Acme",
  openaiApiKey: process.env.OPENAI_API_KEY,
  sitemap: "https://acme.com/sitemap.xml",
  qa: [{ question: "Do you offer refunds?", answer: "Yes, within 14 days of purchase." }],
});
export const POST = (request: Request) => answers.handler(request);
```

Custom Q&A changes at runtime with no refresh: `await answers.upsertQa({ id, question, answer })`, `answers.removeQa(id)`, or `answers.setQa([...])`. Only the changed entry is embedded. To keep your own vector store, pass `retrieve` or call `answerQuestion` with your retrieval; custom Q&A is still always considered.

The full reference app is `examples/answers-nextjs` (markdown knowledge on disk, a JSON visitor log).

Citations must be ids you retrieved. The widget links a URL only when that URL is on the returned citation. Other URLs stay text. HTML in the answer stays text.

## Hosted MCP (Cursor)

HTTP MCP endpoint: `https://answers.bootstrapware.co/mcp`

**Preferred:** OAuth Connect, URL-only. Scope `answers:mcp`. **Add to Cursor (OAuth)** on https://app.bootstrapware.co/answers/keys

**Fallback:** test secret as `Authorization: Bearer`. Live and secret keys stay on the dashboard. Cursor connects through the Answers MCP endpoint. A Cursor marketplace listing is optional and may not be listed yet.

Tools:

- `list_answers_apps`
- `get_answers_app`
- `create_answers_app`
- `update_answers_draft` (does not publish; `name` optional)
- `publish_answers_app`
- `get_answers_published_config`
- `get_answers_install_snippet`
- `ensure_answers_test_publishable`
- `list_answers_capabilities`
- `add_answers_url_source` (public `http` or `https` URL only)
- `reindex_answers_app` (that URL, or the app when `url` is omitted)

**Dashboard-only (do not invent MCP tools):** live and secret key mint, webhooks, app delete, billing, file upload, manual sources, conversations, unanswered text, provider secrets, export, purge. Call `list_answers_capabilities`.

Publishing stores hosted app config. There is no `GET /api/v1/config/:appId` route. `POST /api/v1/ask` reads the published revision.

## Config

Draft defaults: `assistantLabel` "Ask", `greeting` "Ask a question this site already answers.", `theme` "light", `presentation` "launcher", `fallbackMessage` "We could not find an answer in the published sources.", `allowedOrigins` `["*"]`, `retainHistory` true, `publicAnsweringEnabled` true, `allowCodeExcerpts` false.

`["*"]` is the CORS default for the ask route. It is not content authorization. `update_answers_draft` accepts `assistantLabel`, `greeting`, `theme`, `presentation`, `fallbackMessage`, `allowedOrigins`, `retainHistory`, `publicAnsweringEnabled`, and `allowCodeExcerpts`. It rejects questions, answers, file bytes, and provider keys.

`allowCodeExcerpts` defaults to false. How-to, install, and embed answers stay short sentences with a docs link. Set it true only when the app should quote code from a source.

`publicAnsweringEnabled: false` pauses new asks. Sources and history stay.

## Props

- `appId`: published app id (`ana_`).
- `publishableKey`: browser publishable key. With `appId` and no `adapter`, the widget calls Hosted ask.
- `adapter`: `ask`, and optional `feedback`.
- `presentation`: `launcher` (default), `section`, `modal`, or `window`.
- `defaultOpen`: modal, window, and launcher start closed unless this is set.
- `theme`: `light` or `dark`. Omit it and the shell stays the light cream default: no `data-theme`, and no `prefers-color-scheme`.
- `pageContext`: `{ url, title }`. Omit it and the widget sends `location.href` and `document.title`.
- `greeting`: empty-state copy. Omit it and the widget shows "Ask a question this site already answers."
- `onFallback`: called with the sanitized unanswered result.
- `suggestedQuestions`: starter questions shown as chips. A click asks that question.
- `shortcut`: for example `mod+k`. Opens the widget and focuses the question field. `mod` is Command on macOS and Control elsewhere.
- `apiBaseUrl`: Hosted origin when `appId` and `publishableKey` auto-wire the client. Defaults to `https://answers.bootstrapware.co`.
- `className`: layout only.

Escape closes modal, window, and launcher. The backdrop closes modal and launcher. Nudge the corner with `--bsw-an-frame-launcher-right` and `--bsw-an-frame-launcher-bottom`.

Hosts may set `--bsw-an-bg`, `--bsw-an-panel`, `--bsw-an-fg`, `--bsw-an-muted`, `--bsw-an-line`, `--bsw-an-accent`, `--bsw-an-accent-fg`, and `--bsw-an-radius` on `.bsw-an` (with `theme="dark"`, `.bsw-an[data-theme="dark"]`).

## Session

The widget stores `ans_` plus 24 hex in `sessionStorage` under `bsw_an_session:<appId>` (`local` when `appId` is omitted). It does not write a cookie. The adapter's returned `sessionId` does not replace that value. Citation sources start collapsed. The visitor opens the source count to read titles and excerpts.

Questions are limited to 1,000 Unicode code points. A longer draft stays in the composer and is not sent.

## Script mount

`GET https://answers.bootstrapware.co/embed/v1.js` serves the versioned IIFE. A local build writes `dist/answers.iife.js` (gitignored).

```html
<div id="answers"></div>
<script src="https://answers.bootstrapware.co/embed/v1.js"></script>
<script>
  BootstrapwareAnswers.mount(document.getElementById("answers"), { presentation: "launcher" });
</script>
```

`mount` returns an unmount function. Calling `mount` again on the same element updates props. `BootstrapwareAnswers.unmount(el)` removes it. The script is the same widget. Pass `appId` and `publishableKey` and it calls Hosted ask. `suggestedQuestions` and `shortcut` work the same as in React. Pass an adapter function from the page script for BYO.

## Publish pages that can be quoted

Hosted indexes the main body of each page, split by headings; navigation, headers, footers, and cookie banners are dropped. The model writes a short answer from the best-matching passages and must cite them. It does not use outside knowledge. `list_answers_capabilities` returns `sourceAdvice` with the same rules.

1. Make sure the fact is stated in a page body, not only implied by a homepage card. A pricing page, a support page, and one page per product work well.
2. Keep each figure next to what it prices (`Hosted is $19.99/month`). An answer whose price or number is not in a cited passage is rejected unless it follows from cited figures (a single-step percent-off or percent-of of a cited amount, rounded to the nearest cent, or a sequential stack total with each line rounded to the nearest cent). The same number written with a comma, dot, space, or apostrophe as the thousands separator is that figure (`2,500`, `2.500`, and `2 500`). A comma with one or two decimal digits is that decimal (`19,99` and `$19.99`).
3. After `add_answers_url_source`, wait for the index job, then use the dashboard retrieval check to see which passages a question finds. Ask through the widget with a test key to see the written answer.
4. For facts you want stated exactly (prices, refund policy, support contact), add a custom Q&A in the dashboard. Custom Q&A is always considered, and a matching entry is answered first. Hosted entries are indexed on save, usually within about a minute; the dashboard knowledge list shows when each is indexed. With BYO, an entry changed through `upsertQa`, `removeQa`, or `setQa` applies from the next question.
5. When the pages are silent on a yes/no question (certification, compliance, encryption), the answer says the site does not state it and gives the support contact if a source has one. Add the support contact as a custom Q&A so that works. Unanswered with the fallback is the correct outcome when nothing covers the question. Add a URL or a custom Q&A. Do not send the question through MCP.

## Knowledge, grounding, and provider

Hosted knowledge kinds are website root, sitemap, single public URL, PDF, DOCX, TXT, Markdown, and custom Q&A (a question and its answer). A website or sitemap crawl also fetches `/llms.txt` and `/llms-full.txt` on that host when `robots.txt` allows them. Text and Markdown are indexed. A missing file is ignored and is not an index error. BYO `refresh()` does the same for each origin in `urls` or the sitemap. These agent indexes stay below product pages when both match a question. MCP can add a public URL and reindex it. Files, custom Q&A, conversations, and unanswered question text stay on the dashboard.

Every Hosted source is visitor-readable. Do not upload private runbooks or secrets. Crawl is public `http` and `https` only. Private hosts are rejected. `robots.txt` is honored. A failed crawl leaves the last good index in place. A page that is only navigation chrome is rejected and does not become a citation.

Retrieval combines keyword and embedding search over the active index. When the question names a product whose pages live under a URL path, those pages are preferred, and passages on that path that mention the distinctive terms in the question are reserved for the model. Custom Q&A is always considered, and a matching entry is answered first. The model answers in 1 to 4 sentences in the visitor's language, citing passages it was given; citations are ids from the retrieved index, and the model does not invent URLs. A draft that declines, cites an unretrieved passage, states a figure that is not in a cited passage and does not follow from cited figures by the rules above, or writes code not quoted from a passage is retried once and then returns `unanswered` with the configured fallback. A derived total that depends on billing order is rejected unless the visitor set the order, or the answer says order matters and gives the catalog-order total, every order total, or the min-to-max range. A partial set is rejected. An itemized sum is checked even when the answer caveats order, and separate order alternatives are not added into one sum. A stated range must run from the lowest to the highest order total, and a total given for one of those products being first must be the total with that product first and the others in catalog order. Equal list prices are one total, for Hosted and for BYO. A discounted total described as a list price is rejected. The second-product discount already applies when the question names two or more paid products. A question about limiting which pages are indexed still retrieves the passage that explains scoping. A reply whose language does not match the question is retried once. A file the question names, such as `/llms.txt`, and a compare page for a competitor the question names stay in the retrieved context. Off-topic questions and prompt-injection attempts are declined before retrieval. How-to questions get the documented steps and a citation to the docs page; the model does not write new code. There is no model-memory fallback. Earlier turns are used only for clear follow-ups ("what about Chat?"); a standalone question is answered fresh.

Unanswered observations store normalized question text even when conversation history is off, so the dashboard can group them. MCP does not return that text.

Hosted AI is managed OpenAI (a low-cost chat model plus `text-embedding-3-small`), or one Hosted BYOK OpenAI key. The secret route is `GET`, `PUT`, and `DELETE /api/v1/apps/:id/provider` with a secret key. `PUT` accepts only `{ "apiKey" }` and returns the key once. Later reads return a hint. MCP, the browser package, logs, and publishable config do not receive the key. Anthropic and Gemini are not in this version.

## Pricing and retention

- Free: local mode and test keys
- BYO $9.99: live config; you store knowledge and visitor logs
- Hosted $19.99: Hosted stores approved sources, the derived index, visitor questions, optional conversations, unanswered items, and citations
- Cancel Hosted: writes freeze immediately. Dashboard JSON export for 30 days, then Hosted sources, index, conversations, and unanswered items are deleted
- Hosted to BYO keeps the rows and does not start the 30-day clock

## Security

- Do not put `bsw_live_sec_` or `bsw_test_sec_` in client code, `NEXT_PUBLIC_*`, logs, or snippets.
- Do not send visitor questions, file bytes, or provider keys to MCP or webhooks.
- Publishable keys and `allowedOrigins` identify the workspace and apply CORS. They do not stop a script that replays the publishable key. Hosted ask still checks the key, the body size, the burst limits, and the monthly allowance before retrieval or a model call.
- Visitor question text and indexed documents are untrusted. Render the safe markdown subset only.
- Local and BYO question text stays in the browser or on the customer backend.

Related: Cursor guide · Quickstart · API overview