> ## Documentation Index
> Fetch the complete documentation index at: https://www.glyphhq.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up with AI

> Give a coding agent the context and capture rules needed to integrate Glyph.

Glyph's docs are available in formats that coding agents can read directly. The prompt below provides the SDK choices, capture rules, and review steps for an integration.

## Point your tool at these docs

Use any of these entry points:

* **`/llms.txt`** — a machine-readable index at the site root. **`/llms-full.txt`** contains the full documentation in one file.
* **Any page as Markdown** — append `.md` to a page's URL to get its raw source.
* **MCP server** — available at `/mcp` for tools that can search documentation through MCP.
* **The contextual menu** on every page (top right) copies the page as Markdown or opens it directly in Claude, ChatGPT, or Cursor.

## The instrumentation prompt

Paste this prompt into your coding agent with the repository open. It includes the rules from [What to capture](/docs/guides/what-to-capture). Also provide this site's URL or `/llms-full.txt` if the agent needs the full SDK reference.

```text theme={"dark"}
Integrate Glyph customer event tracking into this codebase.

SDK selection:
- Server-side JavaScript/TypeScript: npm install @glyphhq/node
- Client-side web code: npm install @glyphhq/browser
- Python: pip install glyphhq
Prefer server-side instrumentation for business-critical events (payments,
subscription changes); use the browser SDK only for in-product actions and
page views that exist client-side.

Client setup:
- Create ONE shared client per side (e.g. lib/glyph.ts on the server).
- Read the write key from an environment variable (GLYPH_WRITE_KEY on the
  server; use the framework's public-env prefix for the browser key). Add
  entries to .env.example. Create separate named server and browser keys so
  the public browser credential can be rotated independently. Never commit a
  real key.
- Use glyph_test_ keys in development, preview, test, and staging. Use
  glyph_pk_ keys in production. Keep using the SDK's default ingestion host
  unless Glyph explicitly tells you to configure another one.
- Wire the onError callback to the project's existing logger. Never log a
  write key, message body, customer-authored content, or sensitive traits.
- Missing keys should make tracking a safe no-op in unconfigured local and
  test environments. Tracking failures must not break the customer's action.

Identity rules:
- Call glyph.profile(userId, { email, ...traits }) wherever signup and login
  complete, and wherever traits like plan change. email is REQUIRED on every
  profile. Traits merge server-side, so partial updates are fine.
- userId must be the app's stable user ID from the database — never an email.
- Do NOT instrument anonymous or pre-signup visitors. Glyph only accepts
  known customers; there is no anonymous ID to send.
- Only attribute an event when there is an honest, known customer. Do not
  invent an actor for a system or background outcome.

Event selection:
- Do not optimize for a fixed event count. Audit the real product workflows
  and select as many meaningful events as needed to explain a customer's
  activation, adoption, value received, friction, retention, and lifecycle.
- Prefer semantically dense events over raw clickstream noise. Track completed
  workflows, meaningful results, results consumed, explicit feedback, and
  bounded failures. Do not track hovers, indiscriminate button clicks,
  automatic polling, passive refreshes, or framework lifecycle noise.
- Cover four categories:
  1. Activation: account creation, onboarding, and the first moment a customer
     reaches value. If the product has workspace, organization, project, or
     team creation, decide whether that is a separate activation milestone.
  2. Core value: the actions the product is paid for, plus evidence the
     customer consumed the result — for example opening it, viewing supporting
     detail, sharing it, or completing the next step.
  3. Friction: validation failures, rejected operations, processing fallbacks,
     errors shown to customers, delivery failures, usage limits, downgrades,
     and cancellation attempts. Do not skip these; they often explain behavior
     better than successes.
  4. Lifecycle: trial started, subscribed, upgraded, downgraded, cancellation
     requested, and cancelled — instrument these in authoritative billing
     webhooks when those states exist.
- Preserve explicit feedback choices as bounded properties. For example, one
  "Feedback submitted" event can distinguish useful, not_relevant, and
  dismissed without fragmenting the taxonomy.
- Do not add infrastructure events by reflex. "Invoice paid" is useful only
  when payment success answers a customer or revenue question not already
  represented by the subscription lifecycle.

Event naming and properties:
- Names are sentence-case, past-tense phrases a human reads on a timeline:
  "Report exported", "Export failed". No snake_case, no dot.namespaced.codes.
- Properties are small, flat, and bounded. Include context that helps explain
  the moment: object IDs, counts, durations, booleans, result types, surfaces,
  and enumerated reasons. Customer attributes belong in profile traits, not
  event properties.
- Never put passwords, tokens, full write keys, card numbers, email bodies,
  survey answers, notes, support text, search text, arbitrary error messages,
  stack traces, or other sensitive/customer-authored content in a trait or
  property. Send IDs, counts, lengths, and bounded classifications instead.

Delivery rules:
- In serverless functions and API routes: await glyph.flush() before
  returning the response, every time. Check early-return and error paths too.
- Explicit flush() calls are the delivery guarantee in short-lived runtimes.
  Do not change the SDK's periodic flush interval as a substitute for calling
  flush(). Leave the interval at its default unless the runtime has a clear
  reason to change it and every short-lived boundary has been audited.
- In scripts and workers: call close() before exit.
- Python has no background flush thread — flush()/close() explicitly, or
  use the client as a context manager.
- The browser queue is in memory and hidden-tab delivery is best effort. Never
  rely on browser delivery alone for payments, subscriptions, or other
  business-critical events.
- Deduplicate one-time milestones when concurrent requests could emit them
  twice. Deduplicate page views and error-boundary events across client
  remounts, and debounce filters or search without sending query text.

Process:
- Before installing packages or writing code, inspect auth hooks, server
  actions, API routes, jobs, billing webhooks, errors, plan-limit branches,
  and authenticated client workflows.
- Present the proposed event list as a table with: event name, category, the
  customer question it answers, where it fires, server or browser authority,
  safe properties, and any deduplication rule. Include events deliberately
  excluded as noise or unsafe. Wait for my confirmation.
- Ask me for the write key setup — I'll create a glyph_test_ key so we can
  verify in Glyph's isolated test environment before going live. Create
  separate named server and browser keys if both SDKs are used.
- Test non-trivial selection and delivery rules, including deduplication,
  safe property mapping, and tracking failure isolation.
- When done: list every file changed, every event added by category, and every
  event deliberately omitted. Report the validation commands and explain how
  to verify profiles, representative events, failures, and one-time milestones
  in the test environment.
```

## After the agent finishes

Review the diff before running it. Pay particular attention to event usefulness,
data safety, and delivery:

1. **Read the event list.** Each event should help explain an individual customer's experience. There is no fixed target count. Names should read like `Report exported`, not log identifiers. See the [event naming guidance](/docs/guides/what-to-capture#name-events-for-reading-not-querying).
2. **Check the coverage.** Look for activation milestones, value consumed, explicit feedback, friction, and lifecycle changes. Remove raw clickstream and background-process noise.
3. **Check the properties.** They should be small and bounded, with no credentials, customer-authored content, search text, arbitrary errors, or stack traces.
4. **Check every exit path.** A serverless handler that tracks must `await glyph.flush()` before responding. A script must call `close()`. A shorter flush interval is not a replacement. See [The process exited before flushing](/docs/guides/troubleshooting#the-process-exited-before-flushing).
5. **Check authority.** Payments, subscriptions, and completed server workflows should be tracked where the server confirms the outcome, not from a browser success screen.

Run the app with a `glyph_test_...` key and trigger each instrumented action. Check the resulting timelines in the test environment before configuring the live key.