# Ishara docs

Ishara puts suggesting mode on any website. Reviewers leave a quick note, or point at what’s wrong and rewrite it in place; each note arrives with a screenshot of what they saw and its page, section, element path, screen and language. You answer from the dashboard, or your coding agent does over MCP.

## Install the widget

Create a site in the dashboard, then add one line to every page you want notes on, before `</body>`:

```html
<script src="https://useishara.com/w.js" data-site="pk_…" defer></script>
```

The script is one file of about 34 KB gzipped. It waits for the page, asks for the site’s settings, and draws inside its own Shadow DOM, so your styles never reach it and its styles never reach your page.

### Frameworks

- **Next.js (App Router):** in `app/layout.tsx`, `<Script src="https://useishara.com/w.js" data-site="pk_…" strategy="afterInteractive" />` from `next/script`.
- **Astro:** in your layout, `<script is:inline src="https://useishara.com/w.js" data-site="pk_…" defer></script>`.
- **Vue · Nuxt:** add the script to `app.head.script` in `nuxt.config.ts`, or to `index.html` in a Vite app.
- **WordPress · Webflow · Framer:** paste the line into the site-wide footer code (a “custom code” or “footer scripts” setting, or a header/footer plugin).

The site’s **allowed domains** decide where its key works. `example.com` covers `www.example.com` and any port; `*.example.com` covers subdomains; `localhost` works while you develop. A page outside the list gets no widget, and the browser console says why.

## Options

Attributes on the script tag override the site’s settings for that page.

| Attribute | Values | Default |
| --- | --- | --- |
| `data-site` | The site’s public key, `pk_…` (required) | — |
| `data-lang` | `auto`, `en`, `ar`, `es`, `fr`, `de`, `tr` | The site’s setting; `auto` reads `<html lang>` |
| `data-position` | `end` or `start` (bottom corner, by reading direction) | `end` |
| `data-color` | A hex colour, e.g. `#c2255c` | The site’s colour |
| `data-label` | The launcher’s text | “Leave a note” in the reviewer’s language |
| `data-launcher` | `false` hides the floating button (open it from your own UI) | shown |
| `data-first` | `quick` (a comment with a screenshot, pointing one tap away) or `pick` (point at the page first) | The site’s setting (`quick` for new sites) |
| `data-screenshots` | `false` sends notes from this page without a screenshot | The site’s setting (on) |

## JavaScript API

Once loaded, the widget exposes `window.Ishara`:

```js
Ishara.open();   // what «Leave a note» does: the site's first view
Ishara.note();   // a quick note: a comment on the page, with its screenshot
Ishara.point();  // pointing: the reviewer picks a sentence, photo or section first
Ishara.notes();  // the reviewer's own notes and the replies they got
Ishara.close();
addEventListener("ishara:ready", (e) => console.log(e.detail)); // { lang, allowed }
addEventListener("ishara:sent", (e) => console.log(e.detail));  // { id, number, kind, target, … }
```

## Reviewers and access

- **People with the reviewer link (default):** the widget appears only for people who opened the site once through its reviewer link, `https://your-site/?ishara=<review key>`. The widget remembers the key on that device and removes it from the address bar. Making a new link in the dashboard invalidates the old one.
- **Everyone:** every visitor sees «Leave a note». Pair it with *Accepted notes only* for agents.

Reviewers type their name once per device and never need an account. A random device token lets them see their own notes, with your status and reply; nobody else’s notes are ever shown to them. “Open on the page” in the dashboard opens the reviewer’s page with `#ishara=N-12:<selector>`, and the widget rings that element.

## Connect an agent (MCP)

Ishara is a remote MCP server (Streamable HTTP, JSON responses, no session) at `https://useishara.com/mcp`, authorised with a bearer token. Create a token under *Agents* in the dashboard; each token reaches every site in your account and can be revoked there. Without a token the server answers only the handshake and the tool list; every tool call needs the token.

```sh
# Claude Code
claude mcp add --transport http ishara https://useishara.com/mcp --header "Authorization: Bearer ishara_…"

# Clients that only speak stdio
npx -y mcp-remote https://useishara.com/mcp --header "Authorization: Bearer ishara_…"
```

```json
{ "mcpServers": { "ishara": { "url": "https://useishara.com/mcp", "headers": { "Authorization": "Bearer ishara_…" } } } }
```

**Safety.** Notes are written by people outside your team, so every reviewer-written field reaches the agent inside `<untrusted>` markers with an instruction to treat it as data, never as instructions. A site set to **Accepted notes only** hides new notes from agents until a person moves them to *In progress*. Your agent works in your repository, so review its changes as you would any other.

## MCP tools

| Tool | Arguments | What it does |
| --- | --- | --- |
| `list_sites` | — | The sites (embeds) in this account, with how many notes are open on each and what agents may see there. |
| `list_notes` | site?, status? (open · new · doing · done · wontdo · all), kind?, limit? (1–100) | Notes reviewers left on the live sites, newest first. Default: open notes (new and in progress) on every site. Each has an id for get_note and update_note, and a short ref like "N-12". |
| `get_note` | id | One note in full: the page, the section heading, the CSS selector, the text before and after, the reviewer's words and its history. |
| `get_note_photo` | id | The photo a reviewer attached (the replacement image, or one that shows the problem), as an image. With which: "screenshot", the screenshot of the page as the reviewer saw it, any element they picked ringed in gold (get_note says whether a note has one). |
| `update_note` | id, status? (new · doing · done · wontdo), reply? | Set a note's status and/or reply. The reviewer sees both in the widget on their site. Use "doing" while working, "done" once the change is committed or deployed, "wontdo" with a reason when it will not be applied. Write the reply in the reviewer's language. |
| `export_notes` | site? | Every open note, grouped by page, as one Markdown document (a checklist to work through). |

The server’s instructions ask agents to apply text edits by finding the original wording in source, content and translation files, to save replacement photos into the project before referencing them, and to close each note with `update_note` and a reply in the reviewer’s language.

## REST API

The same token works over plain HTTP (JSON; at most 300 requests a minute per token).

| Request | Returns |
| --- | --- |
| `GET /api/v1/sites` | Your sites, open counts, agent scope |
| `GET /api/v1/notes?site=&status=open&kind=&limit=50` | Notes, newest first (`site` is an id, public key or name) |
| `GET /api/v1/notes/:id` | One note with its history |
| `PATCH /api/v1/notes/:id` | `{"status": "done", "reply": "…"}`: the reviewer sees both |
| `GET /api/v1/notes/:id/photo` | The attached photo (JPEG, PNG or WebP) |
| `GET /api/v1/notes.md?site=` | Open notes as Markdown, grouped by page |

## What a note captures

Only what the reviewer chose to send, plus where it was:

- the kind (comment, edit text, replace image, layout, something wrong), the reviewer’s words, their name, and an optional photo (shrunk to at most 2000 px in the browser; JPEG, PNG or WebP up to 1.8 MB);
- a screenshot of the visible page as they saw it, any element they picked ringed, unless the site turns screenshots off or they remove it before sending. It is drawn in their browser from the page itself: typed form values, password and payment fields, anything marked `data-ishara-mask` or `data-ishara-ignore`, editable text and other sites’ frames stay blank, and the widget is never in it;
- the page address without its fragment, its title and language, the screen size and the browser’s user agent;
- the chosen element: what it is, its section heading, a CSS path, its static text (or the image’s address and description).

Typed form values (`<input>`, `<textarea>`), password fields and payment-card fields are never read. Mark any element with `data-ishara-ignore` (or `data-private`) to exclude it from pick mode and surrounding text, or `data-ishara-mask` to let reviewers flag a problem without sending its text or images.

The widget sends no cookies and sets none. Notes and photos are stored in Cloudflare’s European Union jurisdiction (D1 and R2). Details: https://useishara.com/security and https://useishara.com/dpa.

## Content Security Policy

If your site sends a CSP, allow the widget’s origin for scripts and requests: `script-src … https://useishara.com; connect-src … https://useishara.com; img-src … blob:` (the photo preview). The widget builds its DOM node by node and styles itself with a constructable stylesheet, so it needs neither `'unsafe-inline'` nor Trusted Types exceptions.
