@journeeze/sdk 0.0.0-stage → 0.1.0-rc.3

package/AGENTS.md

@@ -0,0 +1,80 @@
+# Integrating Journeeze — guide for coding agents
+
+Rules for an agent adding `@journeeze/sdk` to a host app. The Journeeze contracts are the source
+of truth: SDK (C0a), transport (C0b), journeys (C0c) and signals (C0d), with the integration guide.
+The public types in this package (`dist/types`) follow them.
+
+## Install
+- Public on npm: `npm install @journeeze/sdk@<exact version>`. No registry config or token.
+- Pin an exact version. `-rc.N` = release candidates (`rc` dist-tag), plain = stable (`latest`).
+
+## Configuration
+- `siteKey` (`pk_` + 32 hex, `SITE_KEY_PATTERN`) is **public** runtime config per site. It is not a secret.
+- Direct mode is the default: the browser calls `https://app.journeeze.dev` with CORS for the
+  site's allowlisted origins. Set `apiHost` (script tag: `data-journeeze-api-host`) in every
+  environment except production: `https://app.staging.journeeze.dev` for a staging site key,
+  `http://localhost:8080` for the local stack, or the host's own origin when it runs a same-origin
+  proxy (then `apiPath` for a sub-path). Keep it in the same runtime config as the site key. The
+  SDK never infers it from where the script was loaded. `http:` is accepted only for
+  `localhost`/`127.0.0.1`.
+- CSP, if the host sends one: `script-src 'self' https://app.journeeze.dev` (+ `'wasm-unsafe-eval'`
+  only with signals), `connect-src 'self' https://app.journeeze.dev`, `img-src 'self' blob:
+  https://app.journeeze.dev`, `media-src 'self' https://app.journeeze.dev`, and pass your `nonce`.
+  Use `app.staging.journeeze.dev` for staging.
+
+## Identity
+- `userId` is optional. It must be `HMAC-SHA256(per-environment secret, internal user id)` computed
+  **on the server**, as 64 lowercase hex or 43 base64url characters (`USER_ID_PATTERN` from
+  `@journeeze/sdk/contract`). Never an email, name or raw id; never hashed in the browser.
+- Deliver it only in an authenticated `Cache-Control: no-store` response for the signed-in user,
+  never in public runtime config.
+- **Sign it (v1.3, sdk-v1.md §14).** In the same response, return `userIdExp` (Unix seconds, at
+  most 24 h ahead) and `userIdSig = base64url_nopad(HMAC-SHA256(site identity secret,
+  "jz-id-v1\n" + siteKey + "\n" + userId + "\n" + userIdExp))`, and pass both to the SDK
+  (`userIdSig`/`userIdExp` config or provider props, or `setUser(userId, { sig, exp })`). New sites
+  ignore unsigned ids: that feedback is anonymous and carries no screenshot. Check your
+  implementation against the published test vectors. The identity secret is a server secret, like
+  the HMAC secret above; re-issue the signature before it expires (the SDK never refreshes it).
+
+## React
+- `<JourneezeProvider siteKey={…} userId={…} context={…}>` at the app root. While `siteKey` is
+  `undefined` the provider renders with an **inert handle** (no-ops, nothing sent); the first
+  defined key creates the real handle. `useJourneeze()` never throws inside the provider.
+- Logout is the provider's lifecycle: `userId` changing away from an id, or the provider
+  unmounting, calls `reset()`. Do **not** call `reset()` yourself inside the provider. Script-tag
+  hosts call `window.Journeeze.reset()` on every logout path.
+- `onHelpStatus(status)` (handle option or provider prop) reports `{ available: true }` or
+  `{ available: false, reason: "disabled" | "audience" }`; hide the host's own Help control on
+  `available: false`.
+
+## Context and privacy
+- `context`: `persona`, `journeyId`, `journeyStep`, `device`, `businessType`, `state`.
+  `journeyId` is the journey's candidate id (C0c); `journeyStep` is a stable `stepRef` id such as
+  `route.projects.hub` — **never a URL, path or record id**. With route ids, set `pagePath: "none"`.
+- Put `data-jz-mask` on every element showing customer content and `data-jz-block` on regions to
+  leave out of screenshots entirely. `maskSelectors` fail closed: one invalid selector disables
+  screenshots for that handle.
+- The SDK asks for consent before any capture. Global Privacy Control is honoured
+  (`respectGlobalPrivacyControl`, default on); Do Not Track is ignored (deprecated).
+- Give guided elements a stable `data-tflow-id`; guides fall back to test id, role + name, CSS.
+
+## Signals (optional)
+- `signals: { enabled: true, tflo: () => import("tflo-browser-events") }`. If the host already uses
+  `tflo-browser-events` (`>=0.1.0 <1`, optional peer dependency), **inject it** so the page has
+  one tflo runtime; otherwise the SDK lazy-loads its own copy after consent.
+- Signals start only after the same consent as feedback, and stop when the site's kill switch is off.
+
+## Script tag
+- `window.Journeeze` exists only after the module script runs, which is after inline scripts. Use
+  it from a user event or after `DOMContentLoaded`, never during page load.
+
+## GitHub
+- Issues and the `.jevitate/` catalog go through the Journeeze GitHub App
+  (`https://github.com/apps/journeeze/installations/new`), installed by the product owner on the
+  repository named at setup. Never use a personal access token.
+
+## Never
+- Put a secret in the bundle (the HMAC secret, tokens, gateway keys).
+- Send raw user ids, emails, names, URLs or record ids anywhere (context, steps, rules, params).
+- Load a second tflo runtime next to the host's.
+- Disable masking or skip the consent step.

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.1.0-rc.3 (not yet published)
+
+- **Setup documentation:** the README is a self-contained setup guide: what the Journeeze team sends you, install with a pinned version, `apiHost` per environment, CSP, signed identity with a test vector, privacy and masking, help, feedback, signals, the Journeeze GitHub App and its permissions, a checklist and troubleshooting. Examples use `window.Journeeze` only after `DOMContentLoaded`. The license line matches `LICENSE.md`.
+- **Help chat on the live `Converse` (HC8c):** each turn carries the reviewer token (when the host has one), and on consented turns the signed user id (`userId`, `userIdExp`, `userIdSig`) and the detector's over-masking counts (`overMasked`, counts per rule only). Closing the chat (✕ or Esc) ends a started conversation with a `cancel` turn; opening it again starts a new one.
+- **Chat copy as data (ADR 0020 §5):** the help chat ships no words of its own. Its chrome comes from the site's `widget.ui.*` copy (new `GetWidgetConfig.copy`, by full key, `{name}` placeholders filled by the widget), and its buttons, chips and "+" menu use the labels the server sends on each `Converse` action (`label`, `menu[].label/hint`). The chat reads `GetWidgetConfig` once (copy and mask selectors). If that call fails, only the launcher keeps a last-resort accessible name.
+- **Help chat shell (SDK 2.x, HC8a), behind `chat: true`:** `enableHelp()` (or `data-journeeze-chat` on the script tag) shows one "?" launcher that opens a conversation instead of the v1 help panel: job chips filtered as you type ("Other — none of these" last), inline guide cards, a composer with a "+" menu, a one-time consent line before anything is stored, a removable "Sent with this report" row and, for reviewers, "Team details". Turns go to the collector's `Converse` (direct-mode contract v2 §2). New `feedback()` on the handle opens the chat at "Report a problem" (without `chat: true` it switches feedback mode on). The chat is its own lazy chunk (≤ 11.5 KB gz).
+- **Intent routing in help (P6d):** when a reader who has already consented sends "Something else", help first asks the collector (`RouteIntent`) which of the site's jobs their words mean. A confident match with a guide shows "Did you mean: <job>?" with "Show me how" (its guide) and "No, send my request"; otherwise the request is sent as before. The answer is only a job id and its guide, never generated text; the words are not stored by routing. Without consent nothing is routed.
+- **Jobs in help (P4e2):** when the site's help index lists jobs, help opens on "What are you trying to do?": the jobs common for the host's `persona` under "Common for you", the rest under "More", a local filter, and "Something else". A job opens its guide (the persona's own when it has one) and ends with "Got it done?" (yes / partly / no, plus "Harder than it should be"); a job without a guide offers "Not possible here". `job_picked` / `job_not_possible` / `job_outcome` are aggregate engagement events (job id and entry version only), sent only after consent, with help on and never under Global Privacy Control. "Something else" is the reader's own words as a consented feedback request (with the optional "so you can…"), never telemetry. The jobs view is a separate lazy chunk (≤ 5 KB gz), loaded only for sites with jobs.
+
+## 0.1.0-rc.2 (2026-10-09)
+
+First version published to the public npm registry.
+
+- **Public on npm:** published to the npm registry as `@journeeze/sdk` (no registry config or token), starting with 0.1.0-rc.2. GitHub Packages (`@matt-cochran-products/journeeze-sdk`) is no longer published. The package is licensed for use with the Journeeze service (`LICENSE.md`); it is not open source.
+- **Signed host identity (contract C0a §4, v1.3):** `userIdSig` / `userIdExp` config fields and provider props, and `setUser(userId, { sig, exp })`. The signature is sent with feedback and end-user screenshot uploads while it is unexpired; the same id with a new signature only refreshes it. Sites that require signed identity treat an unsigned id as anonymous.
+- The SDK's own lazy tflo copy (used only when the host injects none) is `tflo-browser-events@0.3.0`: no element text, no `document.title` and path-only URLs by default. Hosts that inject their own tflo are unaffected; the 0.1.0 capability floor is still tested.
+
+## 0.1.0-rc.1
+
+First release candidate of the v1 SDK (epic #75). Published to GitHub Packages as
+`@matt-cochran-products/journeeze-sdk`; install it as `@journeeze/sdk` (see `docs/integrating.md`).
+
+- **Contracts:** implements SDK contract v1 (C0a v1.1-r3 + v1.2), direct-mode transport (C0b v1.1-r3 +
+  v1.2), journey import (C0c v1.1-r3) and signals (C0d v1.1-r3 + v1.2), all signed off by Allumata.
+- **Direct mode by default:** the browser talks to Journeeze directly (CORS for allowlisted origins,
+  `text/plain`, no preflight); `apiHost`/`apiPath` keep a same-origin proxy working. One 32 KiB
+  page-end budget, keepalive `fetch` first, retries honouring `Retry-After`, idempotent
+  `submissionId`.
+- **Handle, identity and context:** `setContext`, opaque host-computed `userId` (HMAC digest only,
+  sent on feedback), `reset()` on logout, per-owner outbox and consent, React provider lifecycle
+  with an inert handle until `siteKey` is known, `pagePath: "redacted" | "none"`.
+- **Feedback:** masked screenshots with preview before send; fail-closed `maskSelectors`;
+  `data-jz-block`; signed-in end users can attach screenshots (anonymous visitors never do).
+- **Help:** in-app guides with fallback target resolution (tflo id → test id → role + name → CSS)
+  in its own lazy chunk; public or reviewers-only audience; `onHelpStatus` reports availability.
+- **Signals:** opt-in, consent-gated derived signals via `tflo-browser-events` (host-injected or the
+  SDK's own lazy 0.2.0 copy); platform rules `jz-platform@1` plus registered site rules; no
+  session id, no sampling; the site kill switch is honoured.
+- **Size:** entry ≤ 2 KiB gzipped; everything else loads lazily.

package/LICENSE.md

@@ -0,0 +1,27 @@
+# Journeeze SDK License
+
+Copyright (c) 2026 Matt Cochran Products. All rights reserved.
+
+This package (`@journeeze/sdk`) is proprietary software. It is not open source.
+
+You may install this package and include it, unmodified, in websites and applications
+(including bundled and minified builds) solely to connect them to the Journeeze service, under
+the terms of your agreement for that service.
+
+You may not:
+
+- modify, adapt or create derivative works of this package, other than the bundling and
+  minification your build tools perform;
+- distribute this package on its own, or as part of anything other than a website or
+  application that uses the Journeeze service;
+- decompile, reverse engineer or otherwise attempt to derive source code from this package,
+  except to the extent applicable law expressly permits it;
+- use this package to build or operate a product or service that competes with Journeeze.
+
+Third-party components included in this package are licensed under their own terms; see
+`dist/THIRD_PARTY_LICENSES.txt`.
+
+THIS PACKAGE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NON-INFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY ARISING FROM, OUT OF OR IN CONNECTION WITH THIS PACKAGE OR ITS USE.

package/README.md

@@ -1,3 +1,344 @@
-# Temporary Holding Version
+# @journeeze/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Journeeze adds in-app help and an opt-in feedback mode to any website or app. Visitors read
+step-by-step guides built from your documented user journeys, and invited reviewers (or signed-in
+users) point at what is unclear. Journeeze groups that feedback and files it as GitHub issues in
+your repository.
+
+The SDK is a small loader (about 2 KB gzipped). Nothing observes the page until help or the
+feedback mode is switched on, and nothing is captured before the visitor consents.
+
+**Contents:** [Before you start](#before-you-start) · [Install](#install) ·
+[Environments](#environments-and-apihost) · [Content Security Policy](#content-security-policy) ·
+[Signed-in users](#signed-in-users) · [Privacy and masking](#privacy-and-masking) ·
+[Help](#in-app-help) · [Feedback mode](#feedback-mode) · [Signals](#signals-optional) ·
+[GitHub](#connect-github) · [Checklist](#setup-checklist) ·
+[Troubleshooting](#troubleshooting) · [Versions](#versions-and-license)
+
+## Before you start
+
+Journeeze is in early access. The Journeeze team sets up your account. Send them:
+
+1. Your organisation and product name.
+2. Every origin the SDK will run on, with scheme, host and port. Example:
+   `https://app.example.com`, `https://*.preview.example.com`. Staging and production are separate.
+3. Whether visitors can be anonymous, or every user is signed in.
+4. The GitHub repository issues should go to (`owner/repo`).
+5. Who should be the project owner on the review board.
+
+You get back:
+
+| You receive | What it is | Where it goes |
+|---|---|---|
+| A **site key** per site (`pk_` + 32 hex) | Public identifier. Not a secret. | Your page or app runtime config |
+| An **identity secret** per site (64 hex) | Server secret for [signing user ids](#signed-in-users). Sent as a one-time 1Password link, never by email or chat. | Your server's secret store only |
+| An **owner invite link** | Opens the review board as project owner. Single use. | Open it once, in your browser |
+
+## Install
+
+Pick one way. Both load the same code.
+
+### npm (bundled apps)
+
+```sh
+npm install @journeeze/sdk@0.1.0-rc.3 --save-exact
+```
+
+Pin an exact version. Release candidates (`-rc.N`) are on the `rc` tag; stable releases on
+`latest`.
+
+**React:**
+
+```tsx
+import { JourneezeProvider, useJourneeze } from "@journeeze/sdk/react";
+
+export function Root() {
+  return (
+    <JourneezeProvider
+      siteKey={config.journeezeSiteKey}      // public, from runtime config
+      apiHost={config.journeezeApiHost}      // staging and local only; see "Environments"
+      context={{ persona: "owner", journeyId: "billing", journeyStep: "route.billing.pay" }}
+      pagePath="none"                        // you pass route ids as journeyStep
+    >
+      <App />
+    </JourneezeProvider>
+  );
+}
+
+function HelpButton() {
+  const jz = useJourneeze();
+  return <button onClick={() => jz.enableHelp()}>Help</button>;
+}
+```
+
+- While `siteKey` is `undefined` (config still loading) the provider renders with an inert handle:
+  every method does nothing and nothing is sent. The real handle starts with the first key.
+- Keep `context` in sync with your router. The provider applies every change.
+- With TypeScript's `exactOptionalPropertyTypes`, optional props do not accept `undefined`. Pass
+  them only when set: `{...(config.journeezeApiHost ? { apiHost: config.journeezeApiHost } : {})}`.
+
+**Without React:**
+
+```ts
+import { createJourneeze } from "@journeeze/sdk";
+
+const jz = createJourneeze({ siteKey: "pk_...", apiHost: "https://app.staging.journeeze.dev" });
+document.querySelector("#help")?.addEventListener("click", () => jz.enableHelp());
+```
+
+### Script tag (no bundler)
+
+```html
+<script type="module"
+  src="https://app.journeeze.dev/sdk/script.js"
+  data-journeeze-site-key="pk_..."
+  data-journeeze-help></script>
+```
+
+The tag creates `window.Journeeze`. It is a module script, so it runs after your inline scripts.
+Use it from a click, or after `DOMContentLoaded`, never while the page is still loading:
+
+```html
+<button id="suggest">Suggest an improvement</button>
+<script>
+  document.addEventListener("DOMContentLoaded", () => {
+    document.getElementById("suggest").addEventListener("click", () => window.Journeeze?.enable());
+  });
+</script>
+```
+
+| Attribute | Effect |
+|---|---|
+| `data-journeeze-site-key` | Required. Your site key. |
+| `data-journeeze-api-host` | The collector origin. Required outside production; see below. |
+| `data-journeeze-api-path` | Path prefix, only for a same-origin proxy. |
+| `data-journeeze-help` | Shows the help launcher at once. |
+| `data-journeeze-chat` | Help opens as a conversation instead of the guide panel. |
+
+`/sdk/script.js` is always the SDK version the Journeeze service currently runs. To control the
+version yourself, install from npm and pin it.
+
+## Environments and `apiHost`
+
+The SDK sends to production (`https://app.journeeze.dev`) unless you set `apiHost`. It does not
+follow where the script was loaded from. A staging or local site key sent to production is
+refused, so set `apiHost` next to the site key in each environment's config:
+
+| Environment | `apiHost` / `data-journeeze-api-host` |
+|---|---|
+| Production | leave it out |
+| Staging | `https://app.staging.journeeze.dev` |
+| Local Journeeze stack | `http://localhost:8080` |
+| Your own same-origin proxy | your origin, for example `https://www.example.com` |
+
+The browser calls the collector directly with CORS, only from the origins you registered. Requests
+carry no cookies and are not cached. A proxy is optional. It suits offices or CI where many users
+share one IP address, or a policy that allows no third-party requests. The Journeeze team sends the
+proxy guide (gateway key, the paths to forward, reference Worker and server code) on request.
+
+## Content Security Policy
+
+If your site sends a CSP, add these. Use `https://app.staging.journeeze.dev` on staging.
+
+```
+script-src   'self' https://app.journeeze.dev;
+connect-src  'self' https://app.journeeze.dev;
+img-src      'self' blob: https://app.journeeze.dev;
+media-src    'self' https://app.journeeze.dev;
+style-src    'self' 'nonce-<your nonce>';
+```
+
+- Add `'wasm-unsafe-eval'` to `script-src` only if you turn on [signals](#signals-optional).
+- Pass your nonce as the `nonce` option. The SDK puts it on the styles it injects.
+- With npm and a proxy, `script-src` and `connect-src` need only `'self'`.
+
+## Signed-in users
+
+Attributing feedback to a user is optional. When you do, your server makes the user id and signs
+it. The browser never sees either secret.
+
+1. **User id.** `HMAC-SHA256(your own secret, your internal user id)`, as 64 lowercase hex or
+   43 base64url characters. Never an email, name or raw id. The SDK ignores anything else with a
+   console warning. Keep this secret stable: changing it splits every user's history.
+2. **Signature.** With the identity secret you received for the site:
+
+   ```ts
+   import { createHmac } from "node:crypto";
+
+   export function signUserId(identitySecretHex: string, siteKey: string, userId: string) {
+     const userIdExp = Math.floor(Date.now() / 1000) + 3600; // at most 24 h ahead
+     const userIdSig = createHmac("sha256", Buffer.from(identitySecretHex, "hex"))
+       .update(`jz-id-v1\n${siteKey}\n${userId}\n${userIdExp}`)
+       .digest("base64url");
+     return { userId, userIdExp, userIdSig };
+   }
+   ```
+
+   Check your code against this vector. Secret: the bytes `0x00` to `0x1f` (hex
+   `000102…1e1f`). Site key `pk_0123456789abcdef0123456789abcdef`. User id: `a` × 64.
+   `userIdExp` `1800000000`. Expected `userIdSig`: `IluU_qUHY6OdSzqKu0Y_wS0sDB53qVOOnobfdHuCnjI`.
+3. **Deliver** `{ userId, userIdExp, userIdSig }` from an authenticated endpoint with
+   `Cache-Control: no-store`. Never put them in public config.
+4. **Pass them to the SDK:** provider props `userId`, `userIdSig`, `userIdExp`, or
+   `jz.setUser(userId, { sig, exp })`. Re-issue the signature before it expires. The SDK never
+   refreshes it.
+5. **Logout.** The React provider calls `reset()` when `userId` goes away or the provider
+   unmounts. Without React, call `jz.reset()` (or `window.Journeeze.reset()`) on every logout path.
+   `reset()` sends that user's unsent feedback once, then clears it, the context, consent and the
+   reviewer token from the device.
+
+Sites require the signature by default. With a missing, expired or wrong signature, that feedback
+is anonymous and has no screenshot.
+
+## Privacy and masking
+
+- Nothing is captured until the visitor turns the feedback mode on and consents. Reading help
+  needs no consent.
+- Screenshots are masked in the browser before encoding, and the visitor sees the masked image
+  before sending. They can always send without it.
+- Always masked: inputs, textareas, selects, editable regions, video, audio, canvas, frames and
+  `[data-jz-mask]`. The SDK also masks elements that look sensitive (password and card fields, API
+  keys, IBANs, email-shaped text). Mark such elements yourself rather than relying on detection.
+- `[data-jz-block]` leaves an empty box that cannot be picked.
+- `maskSelectors: [".customer-name"]` and `maskAllText: true` widen masking. One invalid selector
+  turns screenshots off (fails closed).
+- Anonymous visitors never capture or send a screenshot.
+- `pagePath`: `"redacted"` (default) replaces id-like path segments with `:id`; `"none"` sends no
+  path.
+- Global Privacy Control turns help telemetry and signals off (`respectGlobalPrivacyControl`,
+  default `true`).
+- The collector accepts a closed list of fields. Raw ids, emails, URLs and page text are not on it.
+
+Put `data-jz-mask` on every element that shows customer content.
+
+## In-app help
+
+Help shows a launcher that opens guides built from your published journeys: search, step-by-step
+guidance that outlines each step's element, and an optional "Did this step make sense?" check-in.
+
+```ts
+await jz.enableHelp();   // loads the help code and shows the launcher
+jz.isHelpEnabled();      // true
+jz.disableHelp();        // removes it
+```
+
+- `onHelpStatus(status)` tells you whether help is available here: `{ available: true }`, or
+  `{ available: false, reason: "disabled" }` (help is off for the site) or `"audience"` (help is
+  for reviewers only and this visitor is not one). Hide your own Help button on `false`.
+- Steps point at elements by `data-tflow-id="area.element"` (lowercase letters, digits and `._:-`,
+  up to 96 characters). Give every element a guide points at a stable `data-tflow-id`. A step whose
+  element is not on the page shows its text without an outline.
+- Set `journeyStep` in `context` to a stable id for where the user is (a route id such as
+  `route.projects.hub`), never a URL or record id. Guides and signals match on it.
+- Help is switched on per site on the review board: **Settings → the site → In-app help**. Choose
+  **Reviewers** (default) or **Public visitors**.
+
+Where guides come from: see [Connect GitHub](#connect-github).
+
+## Feedback mode
+
+```ts
+await jz.enable();       // turns the feedback mode on (asks for consent first)
+jz.disable();
+jz.isEnabled();
+```
+
+- Invited reviewers arrive with `?jz_invite=<token>`. The SDK reads it once, removes it from the
+  URL and keeps it for the tab.
+- `onModeChange(enabled)` reports every switch, including Esc and Exit inside the widget.
+- When `journeyStep` changes, the widget can ask about the step the reviewer just finished.
+
+## Signals (optional)
+
+Aggregate behaviour signals: rage clicks, dead clicks, hesitation, abandoned journey steps and your
+own registered signals. They are computed in the browser. Only the derived signal is sent, with no
+URL, text, user id or session id.
+
+```ts
+createJourneeze({
+  siteKey,
+  signals: {
+    enabled: true,
+    tflo: () => import("tflo-browser-events"), // pass your copy if your app already uses it
+  },
+});
+```
+
+- They run only after consent, while help or feedback is on, and while the site's signals switch on
+  the board is on. Turning that switch off stops them without a deploy.
+- Only elements with a `data-tflow-id` outside masked regions are tracked. The SDK listens to
+  clicks, hover, focus and change events. It never reads keystrokes, input values or pointer
+  movement.
+- Without your own `tflo-browser-events` (`>=0.1.0 <1`, optional peer dependency) the SDK loads its
+  own copy. That needs `'wasm-unsafe-eval'` in `script-src` and `data:` in `connect-src`.
+
+## Connect GitHub
+
+Journeeze files issues and reads your journey catalog through the **Journeeze GitHub App**.
+Install it on the repository you named during setup:
+
+**<https://github.com/apps/journeeze/installations/new>** → choose your account → **Only select
+repositories** → your repository → **Install**.
+
+| Permission | Why Journeeze needs it |
+|---|---|
+| Issues: read and write | File a cluster of feedback as one issue, and follow it until it is closed. |
+| Contents: read and write | Read your `.jevitate/` journey catalog. Writes go only to a Journeeze branch, as a pull request you review. |
+| Pull requests: read and write | Open those catalog pull requests and read their status. |
+| Metadata: read | Basic repository information GitHub requires for every App. |
+
+Each call uses a one-hour token limited to that repository. You can remove the App at any time
+(GitHub → Settings → Applications → Installed GitHub Apps). Journeeze then stops reading and
+filing.
+
+**After installing, tell the Journeeze team.** They link the repository to your project. This is
+one step on their side until the board does it for you.
+
+**Your journey catalog.** Journeeze reads the Jevitate catalog in your repository's `.jevitate/`
+folder (personas, jobs and journeys) on each push. Guides with screenshots and video are imported
+from your approved journeys as drafts. A triager reviews each one on the board (**Journeys**), may
+lightly edit the step text, and publishes it. Only published guides appear in help.
+
+**Without the App: upload from CI.** Your CI can upload the catalog as a bundle instead:
+`POST https://app.journeeze.dev/api/upload/v1/bundles` with `Authorization: Bearer jzu_…`. The
+Journeeze team creates upload keys for now and sends them as a one-time 1Password link. Ask them
+for the bundle format and a CI example. Never put an upload key in a URL or a log.
+
+## Setup checklist
+
+- [ ] Site key (and `apiHost` outside production) in each environment's runtime config.
+- [ ] SDK installed with a pinned version, or the script tag on every page.
+- [ ] CSP updated, if you send one.
+- [ ] `data-jz-mask` on every element with customer content; masked screenshot checked on each
+      screen that shows data.
+- [ ] `data-tflow-id` on every element a guide points at; `journeyStep` set per route.
+- [ ] Signed-in users: user id and signature made on your server and delivered `no-store`;
+      `reset()` on every logout path.
+- [ ] Journeeze GitHub App installed on your repository, and the Journeeze team told.
+- [ ] Help switched on for the site on the board, audience chosen, guides published.
+- [ ] One test feedback item sent from each site and seen on the board.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---|---|
+| Requests go to `app.journeeze.dev` from staging or local, or the site key is refused | `apiHost` is not set. Set it for that environment. |
+| CORS error | The page origin is not registered for the site (scheme, host and port must match exactly). Ask the Journeeze team to add it. |
+| `window.Journeeze` is undefined | It was used during page load. Use it from a click or after `DOMContentLoaded`. |
+| Help launcher never appears | Help is off for the site, or the audience is Reviewers and this visitor has no invite. Check `onHelpStatus`. |
+| A guide step has no outline | The element's `data-tflow-id` is missing or changed. |
+| No screenshot offered | An invalid `maskSelectors` entry (fails closed), or the visitor is anonymous. |
+| Feedback is anonymous although `userId` is set | The signature is missing, wrong, expired, or made for another site key. |
+| `userId` ignored with a console warning | It is not a 64-hex or 43-base64url hash (for example a raw UUID or an email). |
+| `429` responses from an office or CI | Many users share one IP address. Use a proxy, or ask for a higher quota. |
+| Issues are never filed | The Journeeze GitHub App is not installed on the repository, or the Journeeze team has not linked it yet. |
+
+## Versions and license
+
+Changes are listed in `CHANGELOG.md` in this package. Public types ship in `dist/types`.
+`@journeeze/sdk/contract` exports `SITE_KEY_PATTERN` and `USER_ID_PATTERN` for your server's
+tests.
+
+Proprietary: see `LICENSE.md`. You may install this package and include it, unmodified, in
+websites and applications solely to connect them to the Journeeze service, under your agreement for
+that service. It is not open source.