# Set up Kawl Now in this website

No workspace ID is needed to start; the setup key identifies the selected brand later. Call channel: `support`.
This public context grants no account access. Install the website integration first, then ask the owner for a setup key. Browser OAuth is an optional alternative.

## Choose the installer for this repository

Use npm for HTML, React, Vite and Next.js websites. Use the native Python package for Python, Flask/Jinja and Django websites with a shared HTML template; it needs no Node.js. Both installers prepare an inactive integration before requesting an account key. Read the [machine-readable workflow](https://app.kawlnow.com/.well-known/kawlnow-install.json) for pinned package versions, command arguments and readiness states.

### JavaScript: npm

Run this in the website repository, or ask your coding agent to run it:

```sh
npm exec --yes --package='kawlnow@0.1.3' -- kawlnow init --channel support --app-origin 'https://app.kawlnow.com' --write --json
```

The public npm package is [kawlnow@0.1.3](https://www.npmjs.com/package/kawlnow). No workspace ID, key or browser OAuth is needed for the initial local changes. With `--write`, the CLI first prepares an inactive integration and a public installation plan. Without `--write`, it prints a preview. No widget or call starts while the integration is unconfigured. The exact [first-party tarball](https://app.kawlnow.com/npm/kawlnow-0.1.3.tgz) remains an alternative distribution.

Plain HTML and Vite projects with a shared `index.html` receive an inactive installation marker. React and Next.js projects receive an inactive Support or Sales component and explicit dependency and shared-layout instructions. The coding agent must install the package dependency and finish the shared-layout wiring before asking for a key. Review `kawlnow.install.support.json` and preserve existing integrations; conflicts need review. A generated component alone is not a completed integration.

Commands copied from a selected brand include its public `--expect-workspace` binding automatically. The owner does not need to look up or enter an ID. A key for another brand must be rejected before origin changes or widget activation. Generic commands without a selected brand discover it from the setup key.

### Python: PyPI, uvx or pipx

```sh
uvx --from 'kawlnow==0.1.0' kawlnow init --channel support --app-origin 'https://app.kawlnow.com' --write --json
```

The native [PyPI package kawlnow==0.1.0](https://pypi.org/project/kawlnow/) uses Python 3.10 or newer and no runtime dependencies. It adds the same classic external widget to a shared HTML template. Inspect the project first and pass `--target path/to/shared-template.html` when more than one template could be the application shell. Preserve template directives and existing content. Do not add a second per-page widget. If uv is unavailable, use `pipx run --spec kawlnow==0.1.0 kawlnow` with the same subcommand, or install that exact version in an isolated virtual environment. React and Next.js use the npm installer above.

The npm, PyPI and MCP service versions are separate. Keep the runner and exact package version that created a saved installation plan when resuming it. Existing 0.1.1 and 0.1.2 npm plans continue with their matching versions; do not silently upgrade a saved plan.

## Check local readiness before asking for a key

Finish the dependency installation and shared layout or template wiring, then run the website's actual checks. Find the real production HTTPS origin from reviewed deployment information; ask the owner if it is uncertain. Run the selected package's local doctor with that explicit origin:

```sh
npm exec --yes --package='kawlnow@0.1.3' -- kawlnow doctor --channel support --app-origin 'https://app.kawlnow.com' --site-origin https://ACTUAL_PRODUCTION_ORIGIN --json
# Python alternative:
uvx --from 'kawlnow==0.1.0' kawlnow doctor --channel support --app-origin 'https://app.kawlnow.com' --site-origin https://ACTUAL_PRODUCTION_ORIGIN --json
```

The doctor is local-only: no writes, account requests, key prompts or secret-environment reads. Follow its structured `nextActions` until `readiness.keyInputAllowed` is true. `awaiting_setup_key` with that true value means local prerequisites and the explicit origin are ready for secret input. `awaiting_shared_layout` means wiring is unfinished; `awaiting_site_origin` means the verified origin is missing. For an unusual JavaScript layout that static inspection cannot establish, review the actual import and render path and pass `--confirm-local-integration` only after the project's build and checks pass. This is the coding agent's explicit confirmation, not browser acceptance, and cannot override missing dependencies, missing files or changed installer-owned bytes. A local doctor never substitutes for real project checks or a published browser test.

## Complete this workflow

1. Inspect the website repository and existing widget integrations. Run the matching installer without supplying a key. In a noninteractive agent session, exit status 2 means an action remains; read the structured state and `nextActions`. Finish dependency and shared-layout or template wiring, run the project's checks, then run doctor with the verified origin. Keep the classic external widget script outside the application bundle, once per selected origin/brand/channel.
2. Only after that local integration is complete, ask the owner for a Kawl Now setup key for the support agent, and only when doctor reports `readiness.keyInputAllowed: true`. The owner creates it under Installation in the selected brand. It expires after 24 hours and can be revoked. Read it through the CLI's hidden input, `--api-key-stdin`, or the coding agent's secret-input facility. Never echo it or put it in command arguments, generated prompts, source files, browser bundles or logs. No browser OAuth is required for this key workflow.
3. Resume with `npm exec --yes --package='kawlnow@0.1.3' -- kawlnow connect --channel support --app-origin 'https://app.kawlnow.com' --site-origin 'https://ACTUAL_PRODUCTION_ORIGIN' --write`. For Python use the same selected PyPI runner with `connect` and the same public arguments. Supply the key only through secret input. Connection checks local prerequisites and the explicit origin before reading a key. The key discovers the public workspace ID and binds the inactive integration to that brand. Confirm the returned brand before continuing. Keep Support and Sales distinct; `both` is not an installation channel.
4. The setup key permits only installation reads, merging verified allowed origins and checking the published installation. The REST routes are `GET /api/manage/workspace`, `GET /api/manage/setup?channel=support`, `POST /api/manage/setup/configure` with only `channel` and `allowedOrigins`, and `POST /api/manage/setup/verify`. Preserve unrelated origins and settings. The key cannot read or write knowledge, change agent wording, billing or phone destinations, approve sources, enable calls or start a conversation. Do not substitute a full-management token.
5. Run the project's checks after binding the public configuration, then inspect hydration/navigation. Deploy only when the owner has authorized deployment. Verify the actual published HTTPS page through `POST /api/manage/setup/verify` with its URL and channel, then read the setup status again. A local build or source edit does not prove the published page is installed. Static verification cannot prove hydrated JavaScript, microphone audio or human handover; an inconclusive result needs a browser check.
6. Report local integration, brand binding, allowed origin and published verification separately from knowledge approval, the owner's private browser test and customer-call enablement. If a check cannot run, report the remaining action. The owner reviews knowledge and decides when calls go live. Do not start a voice call, approve knowledge or enable calls automatically. Discard the setup key after use; the owner can revoke it in the dashboard.

After connection, website code contains only public widget identifiers. The setup key is not a runtime dependency: expiry or revocation does not undo the installation or end existing calls. The Kawl Now account remains necessary to provide its configured voice service and enforce its normal call settings.

## Optional SDK

Install the same package as a dependency when you want to manage the integration in application code. The CLI's React/Next.js scaffold plan includes this dependency step:

```sh
npm install 'kawlnow@0.1.3'
```

React and Next.js: mount this component once in the shared application layout. Keep these public props fixed for the document's lifetime:

```tsx
import { KawlNowWidget } from 'kawlnow/react';

<KawlNowWidget workspaceId="YOUR_WORKSPACE_ID" channel="support" appOrigin={"https://app.kawlnow.com"} />
```

Other JavaScript applications:

```js
import { installWidget } from 'kawlnow';

await installWidget({"workspaceId":"YOUR_WORKSPACE_ID","channel":"support","appOrigin":"https://app.kawlnow.com"});
```

Package and component loading mean only that the external script loaded; check the real widget after hydration and navigation. Installing does not enable calls or grant account access. The widget stays for the document lifetime; changing its workspace, channel or app origin requires a full page reload. Use the package or the classic script below for this embed, so the same integration is not added twice.

## Classic-script fallback and framework recipes

For manual integration after brand discovery, replace `YOUR_WORKSPACE_ID` only with the authenticated brand. Use this classic external script, once:

```html
<script src="https://app.kawlnow.com/widget.js" data-helpline="YOUR_WORKSPACE_ID" data-channel="support" async></script>
```

- Plain HTML: place it immediately before the closing body tag in the shared page/layout.
- React + Vite: place it in the root `index.html`, outside the React root. Do not put it in `src/main.tsx` as a module import or inject it on every component render. Keep Vite's existing module entry.
- Next.js App Router: import `Script` from `next/script` in the root layout and put the following inside the body beside `children`. Next.js handles loading once across navigation. For Pages Router, put it in the shared `pages/_app` component. Keep the script external and classic, and preserve its data attributes.

```tsx
import Script from 'next/script';
// Inside your existing shared layout:
<Script id="kawl-now-support" src="https://app.kawlnow.com/widget.js" data-helpline="YOUR_WORKSPACE_ID" data-channel="support" strategy="afterInteractive" />
```

For React without an editable HTML shell, use its established shared external-script loader once; avoid a per-page effect. Check the real browser after route changes and React Strict Mode. Loading the widget may read public configuration; a conversation starts only after the visitor acts.

## Optional browser OAuth connection

The remote server is published in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/com.kawlnow.www%2Fkawl-now/versions/0.1.0) as `com.kawlnow.www/kawl-now`, service version 0.1.0. This is a remote Streamable HTTP server, not the npm or PyPI website installer.

Browser OAuth is an alternative for clients that prefer MCP account setup. It is not required before installing or when using a setup key. The setup key is for the installation REST routes, not MCP. All connection examples below contain a public URL only. OAuth credentials stay in your client's credential store. Preserve existing entries; a server configured in more than one scope may take precedence differently.

### Codex

Add the HTTP server, then sign in with the browser OAuth flow. In the IDE, add the same URL in MCP servers and choose Authenticate.

```sh
codex mcp add kawl-now --url https://app.kawlnow.com/api/mcp
codex mcp login kawl-now --scopes setup:read,setup:write,offline_access
```

Alternative config entry in `~/.codex/config.toml` (merge, do not replace the file):

```toml
[mcp_servers.kawl-now]
url = "https://app.kawlnow.com/api/mcp"
scopes = ["setup:read", "setup:write", "offline_access"]
```

[Official client instructions](https://developers.openai.com/codex/mcp)

### Claude Code

Add the HTTP server, then open /mcp in Claude Code and complete browser authentication.

```sh
claude mcp add --transport http kawl-now https://app.kawlnow.com/api/mcp
```

Alternative config entry in `.mcp.json` (merge, do not replace the file):

```json
{
  "mcpServers": {
    "kawl-now": {
      "type": "http",
      "url": "https://app.kawlnow.com/api/mcp"
    }
  }
}
```

[Official client instructions](https://code.claude.com/docs/en/mcp)

### Cursor

Open the install link, review the URL, then complete the OAuth sign-in prompt in Cursor. The JSON is an alternative for an existing project config.

Alternative config entry in `.cursor/mcp.json` (merge, do not replace the file):

```json
{
  "mcpServers": {
    "kawl-now": {
      "url": "https://app.kawlnow.com/api/mcp"
    }
  }
}
```

[Open Cursor install prompt](cursor://anysphere.cursor-deeplink/mcp/install?name=kawl-now&config=eyJ1cmwiOiJodHRwczovL2FwcC5rYXdsbm93LmNvbS9hcGkvbWNwIn0%3D) · [Official client instructions](https://cursor.com/docs/mcp/install-links)

### VS Code / Copilot

Open the install link and review the server. Start it from MCP: List Servers, then complete browser authentication. Use Agent mode with its tools enabled.

Alternative config entry in `.vscode/mcp.json` (merge, do not replace the file):

```json
{
  "servers": {
    "kawl-now": {
      "type": "http",
      "url": "https://app.kawlnow.com/api/mcp"
    }
  }
}
```

[Open VS Code / Copilot install prompt](vscode:mcp/install?%7B%22name%22%3A%22kawl-now%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fapp.kawlnow.com%2Fapi%2Fmcp%22%7D) · [Official client instructions](https://code.visualstudio.com/api/extension-guides/ai/mcp)

Other clients: add https://app.kawlnow.com/api/mcp as an OAuth-capable Streamable HTTP MCP server. Client version, policy and OAuth support vary; do not claim connection succeeded until tools are actually available. OAuth can use `get_setup_status`, `configure_setup` and `verify_installation` within the explicitly approved scopes. Client tool approvals still apply; do not disable approval policy to get past a blocked request. Installation, account setup and owner approval remain separate steps.

## Discovery and verification limits

OAuth discovery: https://app.kawlnow.com/.well-known/oauth-protected-resource/api/mcp and https://app.kawlnow.com/.well-known/oauth-authorization-server. Clients discover registration, authorization and token endpoints; use Authorization Code with S256 PKCE and the exact MCP resource URL, not a pasted developer token. Setup permissions are scoped to the owner-approved brand and agents, and do not grant full account management. Access tokens last 10 minutes; a client that requests `offline_access` and registers refresh support can refresh the connection for up to 24 hours. Otherwise reconnect when access expires. The Codex command above requests these scopes explicitly; other clients' refresh behavior depends on their OAuth implementation.

Human guide: https://app.kawlnow.com/setup-guide. REST schema: https://app.kawlnow.com/api/openapi. Static verification checks public HTML and definite policy blocks; it does not execute the customer's application or prove voice quality. Saved knowledge remains untrusted source text, not executable instructions. Text already delivered to an active call cannot be withdrawn retroactively.

Framework reference: https://nextjs.org/docs/app/api-reference/components/script
