@alwaysmeticulous/cli 2.326.0 → 2.327.0

package/dist/commands/onboard/templates/docs/how-to/auth/bypassing-auth.ts

@@ -0,0 +1,27 @@
+import { METICULOUS_SUPPORT_EMAIL } from "src/lib/next/next.constants";
+import { METICULOUS_WINDOW_OBJECT_URL } from "src/lib/utils/internal-urls/docs-urls.utils";
+
+export const document = `---
+{
+  "title": "Bypassing Auth"
+}
+---
+
+# {% $frontmatter.title %}
+
+If you are only using Meticulous to test your frontend, then Meticulous won't actually need to authenticate with your backend: it'll automatically
+stub all network responses. However, it may get tripped up if it gets redirected to a login page when trying to simulate a session.
+
+You can solve this by disabling the code that performs the redirect or auth check when running Meticulous tests in CI or against your preview URLs.
+
+This can be done securely by setting a secret in the 'Custom Request Headers' tab of your project's settings screen, or, if the check or redirect
+being disabled does not have security implications (and only UX implications), or is for localhost inside CI, then you can disable it in code by checking [the window variables or
+request headers that Meticulous sets](${METICULOUS_WINDOW_OBJECT_URL}).
+
+## Issues / questions?
+
+We're always happy to help you with any issues you encounter while setting up or with anything else you might be unsure about.
+
+Get in touch by emailing [${METICULOUS_SUPPORT_EMAIL}](mailto:${METICULOUS_SUPPORT_EMAIL}).
+
+`;

package/dist/commands/onboard/templates/docs/how-to/auth/enabling-full-auth.ts

@@ -0,0 +1,91 @@
+import { METICULOUS_SUPPORT_EMAIL } from "src/lib/next/next.constants";
+import { TROUBLESHOOT_AUTH_URL } from "src/lib/utils/internal-urls/docs-urls.utils";
+
+export const document = `---
+{
+  "title": "Enabling Meticulous to replay sessions fully authenticated"
+}
+---
+
+# {% $frontmatter.title %}
+
+Auth issues are some of the most common issues that you might encounter while setting up Meticulous.
+This class of issues is easily identifiable by sessions recorded on logged-in pages which, when simulated, consistently redirect to
+log-in pages or 401 screens.
+
+Note that you may not need to enable full authentication if you are only using Meticulous to test your frontend (read more [here](${TROUBLESHOOT_AUTH_URL})). If you
+do wish to enable full authentication, then select the auth provider that you're using from the options below:
+
+{% tabs %}
+{% tab label="Auth0" %}
+
+## Auth0
+
+[Auth0](https://auth0.com/) is a popular auth provider that is used by many web apps. There are many different integration methods with
+Auth0, but, at a high level, there are two main patterns:
+
+### Is the user session managed in the browser?
+
+This integration pattern is most common in single page applications (SPAs). In these methods, the user session is managed in
+the browser, and the browser is responsible for sending the session data to the backend with every request. Common SDKs used for this
+pattern are [auth0-spa-js](https://github.com/auth0/auth0-spa-js) and [auth0-react](https://github.com/auth0/auth0-react).
+
+By default, Auth0 stores user session data in JavaScript memory, which Meticulous cannot access while recording sessions. When Meticulous
+tries to simulate these sessions, Auth0 will fail to refresh the session data and then will force a redirect to the login screen.
+
+To fix this, you need to configure Auth0 to store user session data in \`localstorage\`. See Auth0's documentation [here](https://auth0.com/docs/libraries/auth0-single-page-app-sdk#change-storage-options)
+for more information on how to set this configuration.
+
+### Is the user session managed in the backend?
+
+This integration pattern is most common in traditional web applications and in web applications that make heavy use of server-side rendering.
+In these methods, the user session is managed in the backend, and the backend exposes this session to the frontend via cookies or headers.
+Common SDKs used for this pattern are [auth0-node](https://github.com/auth0/node-auth0) and [nextjs-auth0](https://github.com/auth0/nextjs-auth0).
+
+By default, Auth0 stores user session data in httpOnly cookies, which Meticulous cannot access while recording sessions. When Meticulous
+tries to replay these sessions, Meticulous will not pass a session cookie when attempting to load the initial page, so Auth0 will force
+a redirect to the login screen.
+
+To fix this, you need to configure Auth0 to not use httpOnly cookies in the environments where Meticulous records sessions. This can be
+accomplished by setting the \`AUTH0_COOKIE_HTTP_ONLY\` environment variable to false in the desired environments. See Auth0's documentation
+[here](https://auth0.github.io/nextjs-auth0/types/config.ConfigParameters.html) for more information on how to set this configuration.
+
+### Is the same Auth0 client being used across the record and replay environments?
+
+If you have made the suggested changes from the previous sections and are still seeing auth issues, then it is possible that the Auth0
+client is different between the record and simulation environments. Because live requests are being sent to Auth0 at simulation time
+with session data collected at record time, the same Auth0 client must be used across record and simulation environments.
+
+Please standardize your Auth0 client across environments, and try recording and simulating a session again.
+
+{% /tab %}
+
+{% tab label="Other" %}
+
+## Other
+
+### Is the same auth provider client being used across the record and replay environments?
+
+Because live requests are often sent to auth providers at simulation time with session data collected at record time, the same auth provider
+client must be used across record and simulation environments.
+
+Please standardize your auth provider client across environments, and try recording and simulating a session again.
+
+### Does your backend expose user session data to the browser exclusively via httpOnly cookies?
+
+If your backend exclusively uses httpOnly cookies to expose user session data to the browser, then Meticulous will not be able to access
+this data at record time. This will prevent Meticulous from passing a valid session cookie when loading the initial page at simulation time.
+
+To fix this, please disable httpOnly cookies in the environments where Meticulous records sessions.
+
+{% /tab %}
+
+{% /tabs %}
+
+## Issues / questions?
+
+We're always happy to help you with any issues you encounter while setting up or with anything else you might be unsure about.
+
+Get in touch by emailing [${METICULOUS_SUPPORT_EMAIL}](mailto:${METICULOUS_SUPPORT_EMAIL}).
+
+`;

package/dist/commands/onboard/templates/docs/how-to/configure-ignore-patterns.ts

@@ -0,0 +1,77 @@
+import { WHERE_CAN_I_REACH_OUT_FOR_SUPPORT } from "../constants";
+import { ENABLE_SOURCE_COVERAGE_URL } from "src/lib/utils/internal-urls/docs-urls.utils";
+
+export const document = `---
+{
+  "title": "Configuring Ignore Patterns for Coverage"
+}
+---
+
+# {% $frontmatter.title %}
+
+Meticulous uses a \`.meticulousignore\` file at the root of your repository to exclude files from [source coverage](${ENABLE_SOURCE_COVERAGE_URL}) tracking. The file follows the same syntax as [.gitignore](https://git-scm.com/docs/gitignore).
+
+## Global ignore patterns
+
+Create a \`.meticulousignore\` file at the root of your repository. Any file whose path matches a pattern in this file is excluded from coverage across all Meticulous projects that point to the repository.
+
+\`\`\`
+# .meticulousignore
+
+# Exclude generated files
+src/generated/**
+
+# Exclude Storybook
+apps/storybook/**
+
+# Exclude mobile-specific files
+**/*.ios.*
+**/*.android.*
+\`\`\`
+
+## Project-specific ignore patterns (monorepos)
+
+If your repository contains multiple Meticulous projects — for example, separate \`dashboard\` and \`admin\` apps in a monorepo — you can create per-project ignore files so that each project only tracks coverage for its own source files.
+
+Create a \`.meticulousignore.{slug}\` file at the root of your repository, where \`{slug}\` is derived from your Meticulous project name (see [How the slug is computed](#how-the-slug-is-computed) below).
+
+For example, a monorepo with a \`dashboard\` project and an \`admin\` project might have:
+
+\`\`\`
+# .meticulousignore.dashboard
+# Applied only when running coverage for the "dashboard" project
+
+apps/admin/**
+\`\`\`
+
+\`\`\`
+# .meticulousignore.admin
+# Applied only when running coverage for the "admin" project
+
+apps/dashboard/**
+\`\`\`
+
+Patterns from \`.meticulousignore\` (global) and \`.meticulousignore.{slug}\` (project-specific) are merged together, so both apply at the same time.
+
+## How the slug is computed
+
+The slug is derived from your Meticulous project name using these steps:
+
+1. Convert to lowercase
+2. Replace any character that is not alphanumeric, a hyphen (\`-\`), or an underscore (\`_\`) with a hyphen
+3. Collapse consecutive hyphens into a single hyphen
+4. Strip any leading or trailing hyphens
+
+| Project name | Ignore file |
+|---|---|
+| \`dashboard\` | \`.meticulousignore.dashboard\` |
+| \`my-next-cloudflare-app\` | \`.meticulousignore.my-next-cloudflare-app\` |
+| \`meticulous_app\` | \`.meticulousignore.meticulous_app\` |
+| \`My Dashboard App\` | \`.meticulousignore.my-dashboard-app\` |
+| \`apps/admin\` | \`.meticulousignore.apps-admin\` |
+| \`My App (v2)\` | \`.meticulousignore.my-app-v2\` |
+
+Your project name is shown in the Meticulous UI in the top-left of your project's page, and in the URL: \`app.meticulous.ai/projects/{org}/{project-name}\`.
+
+${WHERE_CAN_I_REACH_OUT_FOR_SUPPORT}
+`;

package/dist/commands/onboard/templates/docs/how-to/enable-source-coverage.ts

@@ -0,0 +1,84 @@
+import { WHERE_CAN_I_REACH_OUT_FOR_SUPPORT } from "../constants";
+
+export const document = `---
+{
+  "title": "Viewing source coverage information in Meticulous"
+}
+---
+
+# {% $frontmatter.title %}
+
+Meticulous can be set up to show you what parts of your code are being tested by us. In order to use this feature you must be serving [source maps](https://web.dev/articles/source-maps) for your code in at least some of the environments you're testing against (for instance, if building source maps significantly slows down your build you could do this only on pushes
+to your main branch to avoid delaying PR runs).
+
+## How can I view my source coverage?
+
+To view your coverage information, visit your project's landing page on Meticulous (that is, the \`Overview\` tab). From there click the
+\`View coverage & snapshots\` button, and select the \`Sources\` tab. You'll see a list of all the files in your project, and for each file
+you'll see a percentage of the lines in that file that are covered by your tests. You can click on a file to see the exact lines that are
+covered and not covered.
+
+## How can I serve source maps so Meticulous finds them?
+
+Meticulous will autodetect your source maps in three different ways (you only need to do one of these):
+
+1. You serve the source map in the same directory as the file it corresponds to, with the same name as the file, but with a \`.map\`
+extension added at the end. For instance, if you have a file \`https://mysite.com/static/assets/index.js\` then you should serve the
+source map at \`https://mysite.com/static/assets/index.js.map\`.
+2. You have a \`sourceMappingURL\` comment at the end of your file that points to the source map as documented
+[here](https://firefox-source-docs.mozilla.org/devtools-user/debugger/how_to/use_a_source_map/index.html).
+3. You set the \`SourceMap\` HTTP header on the response that serves the file to point to the source map as documented
+[here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/SourceMap).
+
+
+## Monorepos
+
+If you're using a monorepo, you'll need to build source maps for each package in your monorepo that your app depends on.
+
+For example, if your app is within \`apps/frontend\` and you have a package \`packages/utils\` that the app depends on,
+you'll need to build source maps for both of these packages. You might need to adjust your build process to load source maps
+for your dependencies, e.g. by using \`source-map-loader\` in your webpack config.
+
+
+### Example Next.js setup
+
+1. Enable source maps generation in your dependent packages.
+  \`packages/utils/tsconfig.json\`:
+    \`\`\`json
+    {
+      ...
+      "sourceMap": true,
+      "declarationMap": true
+    }
+    \`\`\`
+2. Install \`source-map-loader\` in your Next.js project:
+      \`\`\`bash
+      npm install --save-dev source-map-loader <OR>
+      yarn add --dev source-map-loader <OR>
+      pnpm add --save-dev source-map-loader
+      \`\`\`
+3. Add the following to your Next.js project&apos;s \`next.config.js\` in order to load source maps from your monorepo packages:
+      \`\`\`javascript
+      module.exports = {
+        ...
+        webpack: (config, { isServer }) => {
+          // Ensure TypeScript source maps from monorepo packages work correctly
+          config.module.rules.push({
+            test: /\\.js$/,
+            use: ['source-map-loader'],
+            enforce: 'pre',
+          });
+
+          // Silence source map parsing warnings.
+          config.ignoreWarnings = [
+            ...(config.ignoreWarnings || []),
+            /Failed to parse source map/,
+          ];
+
+          return config;
+        },
+      };
+      \`\`\`
+
+${WHERE_CAN_I_REACH_OUT_FOR_SUPPORT}
+`;

package/dist/commands/onboard/templates/docs/how-to/fix-false-positive-diffs.ts

@@ -0,0 +1,156 @@
+import { METICULOUS_SUPPORT_EMAIL } from "src/lib/next/next.constants";
+import { METICULOUS_WINDOW_OBJECT_URL } from "src/lib/utils/internal-urls/docs-urls.utils";
+import { WHERE_CAN_I_REACH_OUT_FOR_SUPPORT } from "../constants";
+
+const SERVER_SIDE_RENDERING_ANCHOR = "server-side-rendering";
+const ENV_DIFFERENCES_ANCHOR = "env-differences";
+const PAUSING_METICULOUS_REPLAYS_ANCHOR = "pausing-meticulous-replays";
+const OTHER_CAUSES_ANCHOR = "other-causes";
+const GENERAL_TECHNIQUES_ANCHOR = "general-techniques";
+
+export const document = `---
+{
+  "title": "Fix False Positive Diffs"
+}
+---
+
+# {% $frontmatter.title %}
+
+## Overview
+
+Ideally every difference you see in the Meticulous UI for a given PR should be directly caused by a code change introduced by that PR. Differences that
+show up that are unrelated to your code change could be due to:
+
+ - [Changes in content derived from database data, or the current date/time, when using server side rendering](#${SERVER_SIDE_RENDERING_ANCHOR}) (when using client side rendering Meticulous handles this automatically)
+ - Or, [differences in how you build the code for the two different environments you're comparing between (e.g. PR build vs main branch build)](#${ENV_DIFFERENCES_ANCHOR})
+ - Or, [executing asynchronous tasks that Meticulous doesn't natively handle](#${PAUSING_METICULOUS_REPLAYS_ANCHOR})
+ - Or, [other causes](#${OTHER_CAUSES_ANCHOR})
+
+In all of these cases, if you can't solve the underlying cause, then you can just mark the diff to be ignored:
+
+{% anchor id="${GENERAL_TECHNIQUES_ANCHOR}" /%}
+### Configuring certain diffs to be ignored
+
+You can configure diffs inside certain elements to be ignored by adding a CSS selector to the
+_'Elements to ignore when comparing screenshots'_ list in the _'Screenshotting behavior'_ section in project settings, or by adding the
+\`meticulous-ignore\` class to an element.
+
+Please note that if you open a pull request to add a \`meticulous-ignore\` class to an element then the ignore rule will only apply to Meticulous
+test runs for new PRs opened since the original PR adding the \`meticulous-ignore\` class was merged.
+
+Alternatively, you can detect if the app is being rendered as part of a Meticulous test, and disable part of the UI or code that is causing
+false positive diffs when being rendered in a test. For frontend components you can use the [Meticulous object on the window](${METICULOUS_WINDOW_OBJECT_URL}),
+and for server side components or server side rendering you can use the [\`meticulous-is-test\` header](#${SERVER_SIDE_RENDERING_ANCHOR}).
+
+{% anchor id="${SERVER_SIDE_RENDERING_ANCHOR}" /%}
+## Diffs due to changes in data or the current date when using server side rendering, or rendering NextJS server components
+
+By default Meticulous stubs out responses for any fetch or XHR requests from the browser and stubs out the Date functions in the browser.
+This means that even if the data in your database changes or the time changes you won't see any false positive diffs.
+
+However if you're using NextJS server components then Meticulous will re-render those server components on the backend every time it replays
+a session -- this means that if the data in your database changes or the date changes in the short window of time between when Meticulous
+replays the session on the base commit and when Meticulous replays the session on the head commit, and you render that data or the date to
+the page inside a server component, then you could see false positive diffs.
+
+Meticulous sends a \`meticulous-is-test\` header in every request it makes to your NextJS server. You can use this header to disable parts of
+your server components which cause flakes in Meticulous tests. It'll always be present (with value '1') if the request is being made as part
+of a Meticulous test.
+
+If you render text based on the current time (for example "Posted 7 minutes ago"), you can configure Meticulous to send a simulated date
+header with the virtual time by adding a custom header in your project settings (Settings > Custom Request Headers). Use the
+**Simulated Date** template to set the header value - this will be resolved per-request to the virtual time in RFC 7231 format.
+
+For example, you could add a custom header named \`meticulous-simulated-date\` using the Simulated Date template, then use it like so:
+
+\`\`\`javascript
+import { headers } from 'next/headers'
+
+const getCurrentDate = async () => {
+  const requestHeaders = await headers()
+
+  // If a simulated date header is configured in Meticulous project settings, use it instead of the current date
+  const simulatedDate = requestHeaders.get('meticulous-simulated-date')
+  return simulatedDate ? new Date(Date.parse(simulatedDate)) : new Date()
+}
+\`\`\`
+
+This avoids false positive diffs due to the time changing (e.g. "Posted 7 minutes ago" vs "Posted 8 minutes ago"): Meticulous will send
+the same timestamp every time for the same request. The timestamp is a UTC date in RFC 7231 format.
+
+You can also [configure Meticulous to ignore the diffs using CSS selectors](#${GENERAL_TECHNIQUES_ANCHOR}).
+
+{% anchor id="${ENV_DIFFERENCES_ANCHOR}" /%}
+## Diffs due to differences between environments
+
+### Using Vercel
+
+If you use Vercel then Meticulous will try to automatically generate previews using the same environmental configuration for both commits to the main branch,
+and to PR branches. So you shouldn't see any false positive diffs due to differences between environments. If you do, then reach out to
+the [Meticulous support team](mailto:${METICULOUS_SUPPORT_EMAIL}).
+
+### Using Netlify, or other preview providers
+
+If you use another preview URL provider, such as Netlify, then Meticulous will compare visual snapshots from the preview URL of the base commit on the main branch to snapshots from the preview URL of the head commit of the pull request branch.
+
+In this case the environment variables and configuration you use to run & build your app needs to be the same for the deployments of the main branch (production deploys) and the deployments of pull request branches (preview deploys). If this isn't the case Meticulous could display false screenshot differences.
+
+For example if you configure production deploys of your app (from the main branch) to have a blue banner, and preview deploys of your app (from pull request branches)
+ to have a red banner, then Meticulous would display screenshot diffs of the banner changing from blue to red for every screen. You want to make
+ sure that the only screenshot diffs Meticulous shows are due to changes in the code introduced by the pull request being tested, rather than
+ environmental differences between the environments tested on.
+
+To fix this check the environment variables and configuration you use to run & build your app are the same for the deployments of the
+main branch (production deploys) and the deployments of pull request branches (preview deploys).
+
+If it's not possible to unify the configuration across the environments then you can [configure Meticulous to ignore the diffs](#${GENERAL_TECHNIQUES_ANCHOR}).
+
+### Using GitHub Actions
+
+If, instead of preview URLs, you're using the \`report-diffs-action\` GitHub action, then Meticulous will compare snapshots from running your app from the base
+commit of the main branch to snapshots from running your app from the head commit of the pull request branch. In this case it's similarly important to make sure
+that you compile and run your app with the same configuration for both the main branch and the pull request branches.
+
+{% anchor id="${PAUSING_METICULOUS_REPLAYS_ANCHOR}" /%}
+## Diffs due to asynchronous tasks not handled natively by Meticulous
+
+Meticulous will automatically wait for most browser tasks to complete before continuing with javascript execution. This ensures the
+resultant screenshots are deterministic. However, if your application waits for asynchronous events that are *not* handled natively by Meticulous
+you can use the [Meticulous object on the window](${METICULOUS_WINDOW_OBJECT_URL}) to pause the execution of the replay while the
+asynchronous task is in-progress.
+
+For example, let's say you send a message to a custom Chrome extension and then wait for a response.
+In this case you can tell Meticulous to pause the replay until you have received the expected response:
+
+\`\`\`javascript
+function sendMessageToExtension() {
+  if (window.Meticulous?.isRunningAsTest) {
+    // Meticulous will pause test execution for up to 30 seconds. If we don't
+    // call pause() here Meticulous will sometimes take a screenshot before the
+    // Chrome extension has responded, and sometimes after, causing flaky tests.
+    window.Meticulous.replay.pause();
+  }
+  chrome.runtime.sendMessage(MY_EXTENSION_ID, "My message", (response) => {
+    if (window.Meticulous?.isRunningAsTest) {
+      // Important: we continue the replay even if the request fails
+      window.Meticulous.replay.resume();
+    }
+    if (response.success) {
+      doSomething(response.data);
+    }
+  });
+}
+\`\`\`
+
+{% anchor id="${OTHER_CAUSES_ANCHOR}" /%}
+## False positive diffs due to other reasons
+
+Meticulous ensures the session simulation executes identically every time, even if there are animations, timers, random number generators,
+changing data, or changing dates and times. So under normal operation false positive diffs or flakes should not happen.
+
+However, if you are making extensive use of web workers, WebGL or WASM, it is possible that in some cases you could see false
+positive diffs. If you do notice a false positive diff please reach out to the [Meticulous support team](mailto:${METICULOUS_SUPPORT_EMAIL}) and
+we'll take a look into it. You can also [configure Meticulous to ignore the diffs](#${GENERAL_TECHNIQUES_ANCHOR}).
+
+${WHERE_CAN_I_REACH_OUT_FOR_SUPPORT}
+`;

package/dist/commands/onboard/templates/docs/how-to/link-bitbucket.ts

@@ -0,0 +1,15 @@
+export const linkBitbucketInstructions = `
+1. Create a **repository access token** in Bitbucket:
+    - Open your repository in Bitbucket Cloud → **Repository settings** → **Access tokens** → **Create repository access token**
+    ([guide](https://support.atlassian.com/bitbucket-cloud/docs/create-a-repository-access-token/))
+    - Grant **Repositories: Read** and **Pull requests: Read**
+2. In Meticulous, link the repository and paste the token:
+    - When creating a Bitbucket project, or from **Project settings → CI settings → Linked repository**
+    - Enter your Bitbucket **workspace**, **repository slug**, and paste the access token (it is stored securely and never shown again)
+3. Add the Meticulous webhook in Bitbucket (**Repository settings → Webhooks → Add webhook**):
+    - Use the **Webhook URL** and **Secret** shown by Meticulous after linking
+    - Enable the pull request **Updated**, **Merged**, **Declined**, and **Superseded** triggers
+`;
+
+export const bitbucketRepositoryAccessTokenPermissionsSummary =
+  "Repositories: Read and Pull requests: Read";

package/dist/commands/onboard/templates/docs/how-to/link-gitlab.ts

@@ -0,0 +1,22 @@
+export const gitLabLegacyTokenScopesSummary =
+  "api (required) and read_repository";
+
+export const gitLabLegacyTokenPrefillUrl =
+  "https://gitlab.com/-/user_settings/personal_access_tokens?name=Meticulous&scopes=api,read_repository";
+
+export const linkGitLabInstructions = `
+1. Create a **legacy** GitLab personal access token (not a fine-grained token):
+    - Go to your avatar → **Edit profile** → **Personal access tokens**
+    - Choose **Add legacy token** (or **Create legacy token**), not **Generate fine-grained token**
+    - Under **Scopes**, enable **api** and **read_repository**
+    ([guide](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token))
+    - Your GitLab user must have **Maintainer** or **Owner** on the project
+    - Alternatively, a **project access token** (Premium/Ultimate on GitLab.com) with the same scopes and **Maintainer** role works
+    ([project token guide](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#create-a-project-access-token))
+2. In Meticulous, link the repository and paste the token:
+    - When creating a GitLab project, or from **Project settings → CI settings → Linked repository**
+    - Enter your GitLab **project ID** (from **Settings → General** in GitLab), paste the access token, and configure the webhook shown after linking
+3. Add the Meticulous webhook in GitLab (**Settings → Webhooks**):
+    - Use the **Webhook URL** and **Secret token** from Meticulous
+    - Enable **Merge request events**
+`;

package/dist/commands/onboard/templates/docs/how-to/record-session-context.ts

@@ -0,0 +1,129 @@
+import {
+  TESTING_FEATURE_FLAGS,
+  TYPESCRIPT_TYPES_URL,
+} from "src/lib/utils/internal-urls/docs-urls.utils";
+import { WHERE_CAN_I_REACH_OUT_FOR_SUPPORT } from "../constants";
+
+export const document = `---
+{
+  "title": "Recording the context of a user session"
+}
+---
+
+# {% $frontmatter.title %}
+
+When recording user sessions with Meticulous, you can add contextual information. This can
+make sessions easier to find, help your developers debug diffs in these sessions more
+easily, and let Meticulous optimise session selection across different combinations of
+context (e.g. flags, roles, themes).
+
+All \`window.Meticulous?.context.*\` calls below use optional chaining, so they're safe
+no-ops when the recorder isn't loaded — there's no need to guard them or check
+\`isRunningAsTest\`.
+
+If your project uses TypeScript, install
+[\`@alwaysmeticulous/sdk-bundles-api\`](${TYPESCRIPT_TYPES_URL}) and augment the \`Window\`
+interface as shown in the [TypeScript Types page](${TYPESCRIPT_TYPES_URL}); that gives
+every call below full type safety. You only need to do this once per project — the same
+augmentation covers \`recordUserId\`, \`recordUserEmail\`, \`recordFeatureFlag\`,
+\`recordCustomContext\`, and the rest of \`window.Meticulous\`.
+
+## Adding context to user sessions
+
+Meticulous provides several methods to record different types of context. If you record
+the same piece of context multiple times, the last value will be used.
+
+### Recording user information
+
+You can record the ID and email address of the logged-in user:
+
+\`\`\`js
+// Record the ID of the logged-in user
+window.Meticulous?.context.recordUserId('user-123');
+
+// Record the email address of the logged-in user
+window.Meticulous?.context.recordUserEmail('user@example.com');
+\`\`\`
+
+This information is associated with the session and makes it easier to find sessions for
+specific users.
+
+A natural place for these calls is wherever you load the current user (e.g. a
+\`useCurrentUser\` / \`useSession\` hook, or a \`/me\` query). If your app has a separate
+post-login flow where the user starts logged out and then signs in, you may also want to
+record there so those sessions pick up the user identity too.
+
+### Recording feature flags
+
+You can record which feature flags were active during a session (the value should be a
+string or boolean):
+
+\`\`\`js
+window.Meticulous?.context.recordFeatureFlag('bigUiRefactor', true);
+window.Meticulous?.context.recordFeatureFlag('checkoutFlowStyle', 'v3');
+\`\`\`
+
+We recommend looping over the flags your app already evaluates rather than maintaining a
+hand-curated list — that way new flags are picked up automatically:
+
+\`\`\`js
+// Use whichever flag map your app already has — an SDK snapshot
+// (e.g. client.getAllFlags() / posthog.getAllFlags()), an API
+// response from your backend, or a shared flag-provider value.
+const flags = client.getAllFlags();
+for (const [name, value] of Object.entries(flags)) {
+  window.Meticulous?.context.recordFeatureFlag(name, value);
+}
+\`\`\`
+
+If your app uses **both** a client-side SDK *and* server-evaluated flags (whose resolved
+values reach the frontend via something like a \`features\` field on \`/me\`), it's worth
+looping over both — they each affect what the UI renders. Recording the same flag twice
+is fine; the last value wins.
+
+A reasonable place to call this is wherever flags first become available (the SDK's
+initial-fetch callback, or the effect that resolves your flags API response). If your app
+re-evaluates flags after login or identity changes, recording there as well keeps the
+context accurate for sessions that started logged out.
+
+To learn how Meticulous *tests* the flags you record, see
+[Testing Feature Flags with Meticulous](${TESTING_FEATURE_FLAGS}).
+
+### Recording custom context
+
+For any other contextual information that doesn't fit into the categories above, you can
+use the custom context method (again with a string or boolean value):
+
+\`\`\`js
+window.Meticulous?.context.recordCustomContext('userRole', 'admin');
+\`\`\`
+
+Anything that changes how the UI looks or behaves between sessions is worth considering,
+since recording it helps Meticulous tell those differences apart from real diffs. Common
+examples:
+
+- **User role / permissions** — admin vs regular user, role-gated menus and actions.
+  Often available on the same user object you read for \`recordUserId\`.
+- **Tenant / organization / workspace ID** — for multi-tenant apps, which tenant is
+  active.
+- **Theme / colour scheme** — whatever drives the \`dark\` class on \`<html>\` or your
+  theme provider.
+- **Locale / language** — i18n setting from cookies, localStorage, \`useLocale\`,
+  \`next-intl\`, \`i18next\`, etc.
+- **Viewport / layout mode** — compact vs comfortable, sidebar collapsed, etc., when
+  saved per-user.
+- **Plan / subscription tier** — free vs pro vs enterprise, when it changes the UI.
+- **Environment or build version** — useful when comparing diffs across deploys.
+- **A/B test assignments** outside your main flag provider.
+
+It's usually enough to record each value once, where it's first read or initialised. If
+the value can change mid-session (a theme toggle, a locale switcher, a tenant switcher),
+recording in the change handler too keeps the context accurate.
+
+## Related Pages
+
+- [Testing Feature Flags with Meticulous](${TESTING_FEATURE_FLAGS}) - Learn how Meticulous tests the feature flags you record
+- [TypeScript Types for window.Meticulous](${TYPESCRIPT_TYPES_URL}) - Get type definitions for the \`window.Meticulous\` object
+
+${WHERE_CAN_I_REACH_OUT_FOR_SUPPORT}
+`;