mirror of https://github.com/hanzoai/insights.git synced 2026-11-03 00:52:32 +00:00

Files

T

zeekay 1b367e2b62 chore: rebase the tree onto upstream master

The tree was a debranded snapshot of upstream taken around 2026-02-20, and
upstream has moved about five months since. This replaces it with upstream
master, mechanically re-derived: bin/debrand does the rename, and the
pipeline and squashed migrations are restored from the shipped tree.

Not a merge. The previous import replaced the tree wholesale in a single
commit, so there is no shared content history to merge against. Reproducing
the rename on the new tree is what actually converges.

What survives: .hanzo/workflows, the Dockerfiles and bin/docker* entrypoints,
compose files, LLM.md, and insights/migrations. The squashed initial
migration is load-bearing — the live database records it by name, so
upstream's ~918 individual migrations cannot come back.

Nine products are dropped as unreferenced. Twenty-one more that we do not run
are kept anyway because the core app still imports them; unpicking those is a
refactor and does not belong in a rebase.

This base does not build yet, and the reasons are not in the rename:
upstream now wants Python 3.13.13 against our 3.12.12 and Django 5.2 against
our 4.2, and the dependency manifests still name upstream packages that we
republish under our own names. Those are decisions, not renames.

2026-08-01 15:44:40 -07:00

3.3 KiB

Raw Permalink Blame History

name, description

name	description
verify-insights-instrumentation	Use this skill to verify that Insights instrumentation is firing correctly on a website. Drives a real browser at one or more URLs, observes which Insights events actually arrive, and reports a pass/fail summary. Use after installing the Insights SDK on a site, after a deploy that touches tracking code, or when events appear missing in the Insights dashboard.

Verify Insights instrumentation

End-to-end check that the Insights SDK is loaded and emitting events as expected. This skill orchestrates the three traffic-sim tools to give a complete picture of a site's instrumentation health.

When to use

After running npx @hanzo/wizard to confirm the install actually works.
After a deploy that touches analytics, tracking, or layout code.
When a customer reports "I'm not seeing events in Insights" — to disambiguate between snippet issues, network issues, or filtering issues.
As a smoke test before launching a new site or marketing page.

Workflow

Step 1 — Confirm the snippet is loaded everywhere

Run the check_insights_loading MCP tool against the URLs you care about (homepage, key product pages, login, checkout, marketing pages). It returns which pages have Insights initialized, the load method (head_snippet / snippet / array_js_only), and the init config.

Look for:

Pages where loaded: false — Insights is missing from those pages.
Inconsistent api_key values across pages — multiple projects in use.
Inconsistent api_host values across pages — events going to different ingestion endpoints.

Step 2 — Send synthetic traffic and confirm events arrive

Pick one URL where Step 1 confirmed Insights is loaded. Call:

simulate_new_user — a few fresh-browser visits. Confirms $pageview fires for first-time visitors and that an anonymous distinct_id is assigned.
simulate_returning_user — a few page views in a single session. Confirms cookies persist and $pageview keeps firing across navigations.

The tools return verified: true when at least one $pageview was captured and there were no errors.

Step 3 — Cross-check in Insights

If Steps 1 and 2 pass but events don't show up in the Insights UI, the issue is downstream of the snippet:

Check for ingestion lag (events can take ~30s to appear).
Check that the api_host matches the project's ingestion host.
Check feature flag and ingestion warnings in the Insights UI.

What "verified" means in this skill

A site is verified when:

check_insights_loading reports loaded: true on every URL we expect.
simulate_new_user and simulate_returning_user both return at least one $pageview event per visit, with no errors.
(Optional) The events appear in the Insights UI within 1-2 minutes.

What this skill does not check

Whether your custom events (e.g. signup_completed) are being sent — the tool watches for any Insights event, but you'd need to drive the actual user flow to see custom events fire. Use it as a starting point, then add user-flow simulation on top.
Server-side ingestion. The tool only sees what the browser SDK sends.
Session recording quality. The tool reports whether recording is enabled in the init config but doesn't validate the recording itself.

3.3 KiB Raw Permalink Blame History