TellUs User Guide

Everything you need to set up visual feedback collection on client sites.

Quick Start (5 min)
How the Widget Works
Dashboard Guide
For Developers / AI Agents
Troubleshooting
Installation by Platform

Quick Start

1 Log into the dashboard

Go to the dashboard and sign in with your admin credentials.

2 Add a client site

Click + Add Site in the header. Enter the domain (e.g. a4efloral.com) and a display name.

3 Install the widget

Add this script tag to the site's HTML, just before </body>:

<script defer src="https://tellus.alchemygraphics.com/widget/dist/tellus.min.js"></script>

The defer attribute ensures the script loads without blocking the page.

4 Send the reviewer an activation link

Add ?tellus= and the reviewer's email to any page URL:

https://a4efloral.com?tellus=reviewer@email.com

When they open this link, the feedback widget appears. It stays active for 24 hours via a cookie.

5 Review feedback

Notes appear in the dashboard automatically. Select the site, filter by session or status, click into note details, mark as resolved when done.

Tip: The widget is invisible to normal visitors. Only people who open the activation link (or have the session cookie) will see it. There's zero impact on regular site visitors.

How the Widget Works

Starting a review

The reviewer opens the activation link you sent them
A small purple circle appears in the bottom-right corner
They navigate the site normally — the widget follows them across pages

Leaving feedback

Click the widget icon to enter selection mode
Hover over any element — it highlights in blue
Click the element they want to comment on
A comment form opens with:
- The selected element's text (preview)
- A comment field
- A replacement text field (for exact text changes)
- A change type selector (text change, style issue, layout, etc.)
- Optional screenshot button
- Optional voice note button (records + auto-transcribes)
Click Save — a dot appears on the element as a visual indicator

Ending a review

There's nothing to "end." The session cookie expires after 24 hours. To deactivate immediately, visit ?tellus=off on the site.

Dashboard Guide

Site picker Switch between client sites using the dropdown in the header.

Sessions panel Left sidebar shows all review sessions. Click one to filter notes.

Status tabs Open / Resolved / All — filter notes by resolution status.

Note detail Click "View detail" for full forensic data: selectors, XPaths, styles, screenshot.

Resolve / Reopen Mark notes as resolved with an optional developer comment. Reopen if needed.

Export JSON Download all filtered notes as structured JSON for developers or AI agents.

Note card fields

Type badge — color-coded: Text change (blue), Style (purple), Layout (yellow), Broken (red), Content (green), Comment (gray)
Page path — which page the note was left on
CSS selector — the element that was targeted
Comment — the reviewer's feedback

Note detail drawer

The detail view includes everything an agent or developer needs:

CSS selector, XPath (positional + text-based), bounding box
Reviewer's viewport, browser, and OS
Computed CSS styles of the targeted element
Screenshot and voice note (if captured)
Developer comment field

For Developers / AI Agents

TellUs produces agent-consumable feedback with a two-layer report model:

Layer 1 — Summary

GET /api/reports/{domain}/summary?status=open

Each note is ~250 bytes: page, selector, current text, comment, replacement text, type. An agent can read 50 notes and act on most without needing more context.

Layer 2 — Detail

GET /api/reports/{domain}/detail/{noteId}

Full forensic payload: three independent anchors (CSS, positional XPath, text XPath), computed styles, bounding box, reviewer context, media URLs. Fetched only when the summary is ambiguous.

JSON export

The dashboard's Export JSON button downloads Layer 2 data for all filtered notes. Hand this file to an AI agent as task input.

Agent workflow: Export JSON → feed to Claude/GPT with the codebase → the agent reads selectors + replacement text and makes the changes directly. Most text-change notes need zero disambiguation.

Troubleshooting

Widget doesn't appear

Domain mismatch — check that the domain in the dashboard matches exactly (www.example.com and example.com are different)
Script tag missing — view page source and confirm the <script defer src="...tellus.min.js"> tag is present
No activation — the ?tellus= parameter must be present on the first visit
Console errors — open DevTools and look for errors starting with "TellUs:"

Notes don't save

CORS error — the domain must match what's registered. Check the browser console for CORS errors
API down — visit https://tellus.alchemygraphics.com/api/health to verify

Screenshots blank or show warning

Pages with cross-origin images (CDN, third-party) may cause screenshot capture to fail. This is a browser security limitation. Note text data is still captured normally.

Deactivating the widget

Visit any page on the site with ?tellus=off to clear the session cookie immediately.

Installation by Platform

WordPress

Option A: Use a "Header/Footer Scripts" plugin and paste the script tag in the footer section.

Option B (GeneratePress): Elements → Hook → wp_footer, paste the script tag.

Option C: Edit footer.php in your theme and add the tag before </body>.

Wix

Settings → Custom Code → Add code in the "Body - end" position.

Squarespace

Settings → Advanced → Code Injection → Footer field.

Webflow

Project Settings → Custom Code → Footer Code.

Static HTML

Paste directly before </body> in your HTML file.

Important: The script must be loaded from https://tellus.alchemygraphics.com/widget/dist/tellus.min.js. Don't download and self-host it — updates and bug fixes are deployed to this URL automatically.