npm - @alwaysmeticulous/cli - Versions diffs - 2.331.3 → 2.333.0 - Mend

@alwaysmeticulous/cli 2.331.3 → 2.333.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (61) hide show

package/dist/commands/onboard/templates/docs/onboarding-guide.ts CHANGED Viewed

@@ -1,22 +1,16 @@
 import {
-  ANGULAR_CLI_URL,
-  CLOUD_REPLAY_URL,
-  ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL,
+  CI_SETUP_URL,
+  DETECT_DIFFS_LOCALLY_URL,
   FAQ_AND_TROUBLESHOOTING_URL,
   FIX_FALSE_POSITIVES_URL,
   GITHUB_ACTIONS_SETUP_URL,
+  INSTALL_RECORDER_URL,
   MAKE_CHECK_BLOCKING_URL,
-  NETWORK_STUBBING_EXPLANATION_URL,
-  NEXTJS_APP_ROUTER_ADDITIONAL_SETUP_URL,
-  REACT_VITE_URL,
   RECORD_AND_REPLAY_ON_DIFFERENT_ENVIRONMENTS_URL,
-  TESTING_FEATURE_FLAGS,
   TROUBLESHOOT_AUTH_URL,
   TROUBLESHOOT_RECORDER_URL,
-  VUE_VITE_URL,
 } from "src/lib/utils/internal-urls/docs-urls.utils";
-import { SIMULATION_TAB_NAMES } from "./constants";
-import { EXPLANATION_OF_METHODS_TO_ADD_RECORDER } from "./recorder-snippets/explanation-of-methods-to-add-recorder";
+import { connectGitProviderInstructions } from "./how-to/connect-git-provider";
 export const document = `---
 {
@@ -26,390 +20,117 @@ export const document = `---
 # {% $frontmatter.title %}
-Welcome to Meticulous! This guide will help you set up automated visual testing for your web application in 3 main steps.
+Set up Meticulous in this order:
----
-## Quick Start - Choose Your Path
-Answer 3 questions to get a customized setup guide:
-**Question 1: What framework are you using?**
-- **Next.js** → See [Next.js Setup Guide](${NEXTJS_APP_ROUTER_ADDITIONAL_SETUP_URL})
-- **React (Vite/CRA)** → See [React Setup Guide](${REACT_VITE_URL})
-- **Vue** → See [Vue Setup Guide](${VUE_VITE_URL})
-- **Angular** → See [Angular Setup Guide](${ANGULAR_CLI_URL})
-- **Other** → Continue with general guide below
-**Question 2: What are you testing?**
-- **Static site (HTML/JS/CSS, no SSR)** → Use \`upload-assets\` action (simplest and most reliable)
-- **Server-rendered app (Next.js, Nuxt, etc.)** → Use \`upload-container\` action (Docker)
-- **Not sure?** → Continue reading below
-**Question 3: How do you deploy?**
-- **Vercel Preview URLs** → Use [Cloud Replay](${CLOUD_REPLAY_URL}) (no CI workflow needed)
-- **Netlify/Other preview URLs** → Use [Cloud Replay](${CLOUD_REPLAY_URL})
-- **GitHub Actions CI** → Use [GitHub Actions Setup](${GITHUB_ACTIONS_SETUP_URL})
-- **Other CI** → Continue with general guide below
----
-## Overview - 3 Steps to Get Started
-1. **[5 minutes]** Install recorder and test locally
-2. **[15 minutes]** Set up CI/CD workflow
-3. **[Ongoing]** Record sessions and review diffs
-**Total setup time**: ~20 minutes for basic setup
----
-## Step 1: Install Recorder and Test Locally (5 minutes)
-Before setting up CI, let's verify Meticulous works on your local machine.
-### 1.1 Add Recorder Script
-{% callout type="info" title="Choose Your Environment" %}
-- **Always install on localhost** (for local development)
-- **Recommended**: Install on staging/preview environments
-- **Production**: Contact support for guidance
-{% /callout %}
-Add the Meticulous recorder script to your HTML \`<head>\`:
-\`\`\`html
-<script
-  data-project-id="YOUR_PROJECT_ID"
-  src="https://snippet.meticulous.ai/v1/meticulous.js"
-></script>
-\`\`\`
-**Get your project ID**: [Meticulous Dashboard](https://app.meticulous.ai) → Project Settings
-**Where to add it**:
-- **Next.js App Router**: \`app/layout.tsx\` in \`<head>\`
-- **Next.js Pages**: \`pages/_document.tsx\` in \`<Head>\`
-- **React/Vue/Angular**: \`index.html\` or \`src/index.html\` in \`<head>\`
-### 1.2 Verify Recorder Works
-1. **Start your dev server**: \`npm run dev\`
-2. **Open browser DevTools Console**
-3. **Check for**: "Meticulous recorder initialized" message
-4. **Verify**: \`window.Meticulous\` object exists
-If recorder doesn't load, see [Troubleshoot Recorder](${TROUBLESHOOT_RECORDER_URL}).
-### 1.3 Test Local Simulation
-Let's verify Meticulous can replay a session on your local machine:
-{% command_card %}
-\`\`\`shell
-# Get a session ID from the dashboard first
-npx @alwaysmeticulous/cli simulate \\
-  --apiToken="{% api_token /%}" \\
-  --sessionId="<SESSION_ID>" \\
-  --appUrl="http://localhost:3000"
-\`\`\`
-{% /command_card %}
-**Where to get session ID**:
-1. Use your app normally with recorder installed
-2. Go to [Meticulous Dashboard](https://app.meticulous.ai)
-3. Find a recent session and copy its ID
-**Success criteria**:
-- Command completes without errors
-- You can view the simulation in the dashboard
-- Screenshots look correct
-**Common issues**:
-- **Authentication blocks simulation?** → See [Troubleshoot Auth](${TROUBLESHOOT_AUTH_URL})
-- **Different environment errors?** → See [Cross-Environment Guide](${RECORD_AND_REPLAY_ON_DIFFERENT_ENVIRONMENTS_URL})
-- **Need to debug?** → Add \`--debugger --devTools\` flags
-**Debug tools**:
-- View simulation events: Dashboard → Simulation → *${SIMULATION_TAB_NAMES.TIMELINE_AND_LOGS}* tab
-- Step through replay: Add \`--debugger --devTools\` to simulate command
-{% callout type="warning" title="Test Local Simulation Before CI" %}
-Debugging simulation issues on your local machine is **much easier** than debugging in CI.
-Don't proceed to Step 2 until local simulation works!
-{% /callout %}
----
-## Step 2: Set Up CI/CD Workflow (15 minutes)
-Now that local simulation works, let's run tests in CI on every pull request.
-### 2.1 Choose Your CI Approach
-**Option A: Upload static assets (Recommended for static sites)**
-- If your app can be served as static HTML/JS/CSS without server-side rendering
-- Simplest and most reliable approach
-- Not recommended for typical Next.js apps
-- Guide: [GitHub Actions Setup](${GITHUB_ACTIONS_SETUP_URL})
-**Option B: Upload a Docker container (Recommended for server-rendered apps)**
-- For Next.js, Nuxt, and other SSR frameworks
-- You build a Docker image, Meticulous hosts it
-- Guide: [GitHub Actions Setup](${GITHUB_ACTIONS_SETUP_URL})
-**Option C: Preview URL integration**
-- Works with Vercel, Netlify, and other preview URL providers
-- No CI workflow needed (Vercel has a direct integration)
-- Guide: [Cloud Replay Setup](${CLOUD_REPLAY_URL})
-### 2.2 Add API Token to CI
-1. **Get API token**: [Dashboard](https://app.meticulous.ai) → Project Settings
-2. **Add to GitHub**: Repo Settings → Secrets → Actions
-3. **Create secret**: Name it \`METICULOUS_API_TOKEN\`
-### 2.3 Create Workflow File
-Follow the [CI Setup Guide](${GITHUB_ACTIONS_SETUP_URL}) for step-by-step instructions and example workflow files for your chosen approach (upload static assets or upload a Docker container).
+1. Connect the repository to Meticulous.
+2. Choose automated CLI onboarding or manual setup.
+3. Record sessions and confirm Meticulous runs on pull requests.
-If using preview URLs, follow the [Cloud Replay Setup Guide](${CLOUD_REPLAY_URL}) instead.
-### 2.4 Verify Workflow Runs
-1. **Commit and push** the workflow file
-2. **Create a test PR** with a small change
-3. **Check Actions tab** for workflow run
-4. **Expected first PR**: "No base test run found" (this is normal!)
-### 2.5 Establish Base Run
-For the first PR to work, Meticulous needs a base run on your main branch:
-1. **Merge the PR** that adds Meticulous workflow
-2. **Wait** for workflow to run on main branch
-3. **Verify** in Actions tab: main branch run succeeded
-4. **Check dashboard**: You should see sessions and test runs
-### 2.6 Test with Second PR
-1. **Make a small UI change**
-2. **Create another PR**
-3. **Expected**: Meticulous comment with test results
-4. **If you changed UI**: Diffs are detected
-5. **If no changes**: "No diffs detected"
-{% callout type="success" title="Success!" %}
-If you see a Meticulous comment on your PR, congratulations! You're now running automated visual tests.
-{% /callout %}
----
-## Checklist: Is Everything Working?
-Use this checklist to verify your setup:
-### Recorder Installation
-- Recorder script added to HTML \`<head>\`
-- Project ID is correct
-- Console shows "Meticulous recorder initialized"
-- \`window.Meticulous\` object exists
-- Sessions appear in dashboard after using app
-### Local Simulation
-- \`npx @alwaysmeticulous/cli simulate\` completes successfully
-- Can simulate authenticated pages
-- Can simulate different environments (if needed)
-- Simulation screenshots look correct
-### CI Setup
-- API token added as repository secret
-- Workflow file created and pushed
-- Workflow runs on PRs
-- Base run exists on main branch
-- Meticulous comments on PRs
-### Ready for Production
-- No false positive diffs
-- Auth works in tests
-- All critical user flows are recorded
-- Team knows how to review diffs
+Connecting the repository first lets Meticulous identify the base and head
+versions of each pull request or merge request and publish its test result in
+the right place.
 ---
-## Step 3: Record Sessions and Review Diffs (Ongoing)
-### 3.1 Record Real User Sessions
-The more sessions you record, the better your test coverage:
-**Where to record**:
-- **Development**: Engineers testing locally
-- **Staging**: QA and product testing
-- **Preview URLs**: Testing on PRs
-- **Production**: Contact support for guidance
-**What gets recorded**:
-- User clicks, typing, scrolling
-- Network requests and responses
-- DOM changes and state
-### 3.2 Curate Your Golden Set
-Meticulous automatically selects sessions that maximize coverage:
-1. **View selected sessions**: Dashboard → Selected Sessions tab
-2. **Increase count if needed**: Configure → Number of Sessions
-3. **Manually add important flows**: Select specific sessions
-### 3.3 Review Diffs on Pull Requests
+## 1. Connect your repository
-When Meticulous detects visual differences:
+Create your Meticulous organization and project, then connect the Git provider
+that hosts the repository. Do this before installing the recorder or configuring
+CI.
-1. **Review diff screenshots** in PR comment
-2. **Determine if change is**:
-   - **Expected**: Click "Approve" to mark as intentional
-   - **Bug**: Fix the code
-   - **False positive**: See [Fix False Positives](${FIX_FALSE_POSITIVES_URL})
+${connectGitProviderInstructions}
-### 3.4 Make CI Check Blocking (Optional)
-Prevent merging PRs with unacknowledged diffs:
-1. Go to repository settings
-2. Add Meticulous check as required status
-3. Now PRs can't merge with pending diffs
-See: [Make CI Check Blocking Guide](${MAKE_CHECK_BLOCKING_URL})
+Once the linked project exists, choose how you want to install Meticulous.
 ---
-## Original Setup Details
+## 2. Choose your setup path
-Below are the detailed instructions from the original onboarding guide.
+{% tabs tabNameSpace="setup-path" %}
+{% tab label="Meticulous CLI (recommended)" %}
-## 1. Installing the session recorder
+## Automated setup with meticulous onboard
-Before installing the Meticulous session recorder, you should decide which environments are a good fit for recording user sessions:
+\`meticulous onboard\` uses Claude Code or Codex on your machine to inspect the
+application and prepare a pull request containing the recorder and CI
+configuration. Meticulous does not host the model inference; the command uses
+your existing Claude Code or Codex account.
-- The session recorder should always be installed on localhost to ensure that all sessions generated by engineers developing and testing your application locally are captured.
-- We also recommend installing it on other internal environments, like staging stacks or preview URLs.
-- If you are interested in recording production sessions, please reach out to Meticulous support for additional details.
+### Prerequisites
-${EXPLANATION_OF_METHODS_TO_ADD_RECORDER}
+- Run the command from a clone of the connected Git repository.
+- Install and authenticate [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex](https://developers.openai.com/codex/cli/).
+- Use Node.js 20 or newer.
-More information on troubleshooting recorder problems can be found [here](${TROUBLESHOOT_RECORDER_URL}) and [here](${ENSURE_RECORDER_CAPTURES_ALL_REQUESTS_URL}).
+### Run onboarding
-## 2. Setting up tests to run in CI
-### Validating that sessions can be simulated
-Before setting up tests to run in CI, you should ensure that sessions can be simulated on your local machine. Debugging any issues on your
-local machine is much easier than debugging any issues that occur in CI. You can replay locally using the following CLI command:
+From the application repository. If you are not logged in, the command opens a
+browser to sign in, then continues:
 {% command_card %}
-\`\`\`shell
-npx @alwaysmeticulous/cli simulate
-  --apiToken="{% api_token /%}"
-  --sessionId="<SESSION_ID>"
-  --appUrl="<URL_WHERE_APP_IS_RUNNING_LOCALLY>"
+\`\`\`bash
+npx @alwaysmeticulous/cli onboard --project="{% project_slug /%}"
 \`\`\`
 {% /command_card %}
-Important session simulation scenarios to check:
-- Can you simulate sessions on authenticated pages? If not, see [this doc](${TROUBLESHOOT_AUTH_URL}) on troubleshooting authentication & authorization issues.
-- Can you simulate sessions on a different environment from where they were recorded (e.g. can you simulate a session recorded on sandbox against
-  your localhost environment)? If not, see [this doc](${RECORD_AND_REPLAY_ON_DIFFERENT_ENVIRONMENTS_URL}) on troubleshooting cross-environment issues.
-Two tools to debug simulation issues:
-- Once a simulation has completed and been uploaded to Meticulous, you can view all the events that happened during the simulation on the
-*${SIMULATION_TAB_NAMES.TIMELINE_AND_LOGS}* tab of the simulation’s page in the Meticulous UI
-- Simulating a session with the flags \`--debugger --devTools\` will let you step through the simulation one user event at a time and pinpoint exactly where the issue is occurring
-### Running tests in CI
-For test runs to be executed in CI, Meticulous needs to be able to simulate sessions in 3 different contexts:
-1. **PR test runs**: whenever a new commit is pushed to a PR branch, Meticulous kicks off a test run where it simulates user sessions against the app running that commit.
-Ideally, this version of the app would be hosted on a commit-specific URL, but Meticulous can also run against the app if it's spun up in CI.
-2. **New-commit-on-main test runs:** whenever a new commit is pushed to the main branch, Meticulous kicks off a test run to take new baseline screenshots.
-Ideally, Meticulous would run against a commit-specific URL here as well, but running the app in CI also works.
-3. **Session selection test runs:** each night, Meticulous simulates every new session from the last 24 hours to determine if any of them add new coverage and should be
-included in the *selected set*. In this context, we want to test against the latest version of your app, so usually a publicly accessible staging URL works best.
-How to get Meticulous to trigger test runs across these contexts depends on how you build and serve your app:
+On a remote machine where a browser cannot reach this terminal, sign in first
+with device login, then re-run onboard:
-- **[Recommended] Upload static assets.** If your app can be served as a folder of static assets (HTML/JS/CSS) without server-side rendering, this is the simplest and most reliable approach. Follow the guide [here](${GITHUB_ACTIONS_SETUP_URL}) to set up the \`upload-assets\` action. This approach is not recommended for typical Next.js apps.
-- **Upload a Docker container.** For server-rendered apps (Next.js, Nuxt, etc.), you can build a Docker image and have Meticulous host it. Follow the guide [here](${GITHUB_ACTIONS_SETUP_URL}) to set up the \`upload-container\` action.
-- **Vercel preview URLs.** If you use Vercel preview URLs, the complexity of dealing with three different environments is completely abstracted.
-You can add Meticulous’ Vercel integration [here](https://vercel.com/integrations/meticulous) and then follow the guide [here](${CLOUD_REPLAY_URL}) to complete installation.
-- **Other preview URL providers (e.g. Netlify).** If you deploy your app to a preview URL without Vercel, you can follow the doc [here](${CLOUD_REPLAY_URL}) to set up Meticulous.
-Almost any app can be containerized, so if neither static assets nor preview URLs fit your app, uploading a Docker container is the universal fallback.
-{% callout type="info" title="GitHub Action Configuration" %}
-For a comprehensive list of all GitHub Action options and configuration parameters, see the [report-diffs-action README](https://github.com/alwaysmeticulous/report-diffs-action#readme).
-{% /callout %}
-## Common Gotchas
-Before diving into performance tuning, be aware of these common issues that can cause test failures:
-### Static Assets with Absolute URLs
-Meticulous automatically swaps the base URL for page navigation and API requests, but **static assets (CSS, JS, images) referenced with absolute URLs in your HTML are NOT rewritten**.
-If your HTML contains:
-\`\`\`html
-<script src="https://production.example.com/dist/app.js"></script>
-\`\`\`
-Change it to a relative URL:
-\`\`\`html
-<script src="/dist/app.js"></script>
+{% command_card hideProjectSelector=true %}
+\`\`\`bash
+npx @alwaysmeticulous/cli auth login --device
 \`\`\`
+{% /command_card %}
-See [Troubleshooting Cross-Environment Issues](${RECORD_AND_REPLAY_ON_DIFFERENT_ENVIRONMENTS_URL}) for more details.
-### Understanding Network Mocking
+It asks you to choose the frontend application in a monorepo and the local
+coding agent, reviews the repository, proposes a plan for approval, and then
+opens a setup pull request.
-Meticulous automatically mocks XHR, Fetch, and WebSocket requests, but does NOT mock static assets loaded via HTML tags. For a complete explanation of what is and isn't mocked, see [How Meticulous Handles Network Requests](${NETWORK_STUBBING_EXPLANATION_URL}).
+After the pull request is ready:
-### Cross-Environment Configuration
+1. Review and merge the recorder and CI changes.
+2. Add any requested API token to your CI provider&apos;s secret store.
+3. Record a representative session.
+4. Open a pull request and confirm that Meticulous reports a result.
-If you're recording sessions in one environment (e.g., production) and simulating against another (e.g., localhost or preview URLs), ensure your environments have consistent:
-- Authentication configuration
-- URL routing patterns
-- Environment variables
+{% /tab %}
+{% tab label="Manual setup" %}
-See our [FAQ & Troubleshooting](${FAQ_AND_TROUBLESHOOTING_URL}) guide for more details.
+## Manual recorder and CI setup
-## 3. Tuning Performance
+Use the guided setup in the Meticulous app or follow these docs:
-Once Meticulous is set up to run in CI, there is usually a tuning period (~1-2 weeks) required to get Meticulous working at full capacity.
-A variety of features that can be used to tune Meticulous are described below.
+1. [Install the recorder](${INSTALL_RECORDER_URL}) for localhost and your
+   trusted internal or preview environments.
+2. Exercise a representative user flow and confirm the session appears in the
+   Meticulous project.
+3. [Replay the session locally](${DETECT_DIFFS_LOCALLY_URL}) before moving to
+   CI. Debugging locally is faster than debugging a CI-only failure.
+4. [Choose a CI approach](${CI_SETUP_URL}):
+   [upload static assets or a container](${GITHUB_ACTIONS_SETUP_URL}).
-### Testing feature flags
+For authenticated applications, make sure the recorded flow can sign in and
+replay reliably. See [Troubleshooting authentication](${TROUBLESHOOT_AUTH_URL})
+and [recording and replaying across environments](${RECORD_AND_REPLAY_ON_DIFFERENT_ENVIRONMENTS_URL}).
-If you make heavy use of feature flags we recommend configuring Meticulous to support using old sessions to test new features that are
-gated behind feature flags. Get started [here](${TESTING_FEATURE_FLAGS}).
+{% /tab %}
+{% /tabs %}
-### Coverage
+---
-If you feel that coverage is insufficient, you can try to address it in a couple different ways:
+## 3. Verify the complete setup
-- **Increase the number of selected sessions**. When you click the *Configure* button in the *Selected Session* tab of your project dashboard in the Meticulous UI,
-you will see a *Number of Sessions to Auto Select* section. Below this, Meticulous will recommend increasing the number of selected sessions if it will add more coverage.
-- **Enable the session recorder on production.** Increasing the number of sessions being ingested by Meticulous should increase the level of
-coverage that Meticulous is able to provide. If you are interested in this option, please reach out to Meticulous support for more information.
+Setup is complete when:
-### Flakes & false diffs
+- The project is linked to the correct GitHub, GitLab, or Bitbucket repository.
+- At least one representative session reaches Meticulous.
+- A session replays successfully against your application.
+- The default branch has a baseline test run.
+- A pull request or merge request produces a Meticulous result.
-You may run into a flake or false diff during the tuning period — below are some strategies to manage them:
+If something fails, start with [recorder troubleshooting](${TROUBLESHOOT_RECORDER_URL})
+or the [FAQ and troubleshooting guide](${FAQ_AND_TROUBLESHOOTING_URL}).
-- If the flake is not too frequent or problematic, you can click on the screenshot of the diff and then click *Flag as Unexpected*.
-This sends a bug report to the Meticulous team so that the flake can be prioritized and fixed.
-- If the flake is problematic, you can use the techniques described in [this doc](${FIX_FALSE_POSITIVES_URL}) to debug or ignore the problematic element.
+After the first successful run, [make the Meticulous check blocking](${MAKE_CHECK_BLOCKING_URL})
+and [reduce false-positive diffs](${FIX_FALSE_POSITIVES_URL}).
 `;

package/dist/commands/onboard/templates/docs/recorder-getting-started.ts CHANGED Viewed

@@ -13,12 +13,15 @@ Meticulous recorder is a tool for recording real user sessions. The recorder cap
 include authorization tokens and other headers -- you should therefore only add trusted users to your Meticulous organization.
 You can either add the recorder to all environments or just internal non-production environments.
-## 1. Sign up
+## 1. Create and connect your project
 Sign up at [https://app.meticulous.ai/signup](https://app.meticulous.ai/signup). You will be prompted to create an organization and
-project.
+project. Connect the project to its GitHub, GitLab, or Bitbucket repository before installing the recorder.
 ## 2. Install the Meticulous recorder
+You can run \`npx @alwaysmeticulous/cli onboard --project="<ORGANIZATION>/<PROJECT>"\` from the connected repository to have
+Claude Code or Codex prepare the recorder and CI changes, or install the recorder manually:
 ${EXPLANATION_OF_METHODS_TO_ADD_RECORDER}
 `;

package/dist/commands/onboard/templates/docs/recorder-snippets/script-based-instructions/nuxtjs-instructions.ts CHANGED Viewed

@@ -11,7 +11,7 @@ export const nuxtJsInstructions = (
 {% code %}
 \`\`\`shell
-npm install @alwaysmeticulous/recorder-plugin --save-dev
+npm install @alwaysmeticulous/recorder-plugin@latest --save-dev
 \`\`\`
 {% /code %}

package/dist/commands/onboard/templates/docs/recorder-snippets/script-based-instructions/rsbuild-instructions.ts CHANGED Viewed

@@ -6,7 +6,7 @@ export const rsbuildInstructions = (
 {% code %}
 \`\`\`shell
-npm install @alwaysmeticulous/recorder-plugin --save-dev
+npm install @alwaysmeticulous/recorder-plugin@latest --save-dev
 \`\`\`
 {% /code %}

package/dist/commands/onboard/templates/docs/recorder-snippets/script-based-instructions/vite-instructions.ts CHANGED Viewed

@@ -6,7 +6,7 @@ export const viteInstructions = (
 {% code %}
 \`\`\`shell
-npm install @alwaysmeticulous/recorder-plugin --save-dev
+npm install @alwaysmeticulous/recorder-plugin@latest --save-dev
 \`\`\`
 {% /code %}

package/dist/commands/onboard/templates/docs/reference/cli-commands.ts CHANGED Viewed

@@ -37,6 +37,7 @@ meticulous [command]
 | Command | Purpose | Use Case |
 |---------|---------|----------|
+| \`onboard\` | Install Meticulous using local Claude Code or Codex | Initial recorder and CI setup |
 | \`ci run-with-tunnel\` | Run tests in cloud via tunnel | CI testing with local app |
 | \`ci upload-assets\` | Upload and test static assets | CI testing for static sites |
 | \`ci upload-asset-chunk\` | Upload one named, versioned asset chunk | Multi-bundle deployments |
@@ -93,6 +94,42 @@ For a closer look at the \`agent\` and \`auth\` commands — including their fla
 ---
+## onboard
+Install Meticulous in the current Git repository using your local Claude Code
+or Codex. The command reviews the frontend application and prepares a pull
+request with recorder and CI configuration. Model inference runs through your
+own coding-agent account, not Meticulous-hosted inference.
+### Authentication
+If you are not already logged in, \`onboard\` opens a browser to sign in and
+then selects the Meticulous project. On a remote or sandboxed machine, run
+\`npx @alwaysmeticulous/cli auth login --device\` first. Alternatively, pass
+\`--apiToken\`.
+### Examples
+\`\`\`bash
+# Interactive setup from the connected application repository
+npx @alwaysmeticulous/cli onboard --project="<ORGANIZATION>/<PROJECT>"
+# Choose an app in a monorepo and use Claude Code
+npx @alwaysmeticulous/cli onboard \\
+  --project="<ORGANIZATION>/<PROJECT>" \\
+  --app="apps/web" \\
+  --agent=claude
+# Prepare the workspace without launching an agent
+npx @alwaysmeticulous/cli onboard --printOnly
+\`\`\`
+Key options include \`--cwd\`, \`--project\`, \`--app\`, \`--agent\`,
+\`--model\`, \`--headless\`, \`--auto\`, \`--printOnly\`, and
+\`--apiToken\`.
+---
 ## ci run-with-tunnel
 Run Meticulous tests in the cloud against a locally-running application.

package/dist/commands/onboard/validate-ci-yaml.d.ts ADDED Viewed

@@ -0,0 +1,22 @@
+export interface InvalidCiYamlFile {
+    /** Path relative to the repository root, for display. */
+    relativePath: string;
+    /** First parse error, already including a line/column when the parser knew one. */
+    problem: string;
+}
+/**
+ * Parses the CI files that mention Meticulous and reports the ones a CI
+ * provider would reject. The install agent writes this YAML by hand, and a
+ * syntax slip there only shows up as a failed pipeline after the PR is open.
+ */
+export declare const findInvalidCiYaml: (options: {
+    projectRoot: string;
+}) => InvalidCiYamlFile[];
+/**
+ * Prints a warning for CI files the agent left unparseable, so the user hears
+ * it here rather than from a red pipeline on the onboarding PR.
+ */
+export declare const warnAboutInvalidCiYaml: (options: {
+    projectRoot: string;
+}) => void;
+//# sourceMappingURL=validate-ci-yaml.d.ts.map

package/dist/commands/onboard/validate-ci-yaml.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"validate-ci-yaml.d.ts","sourceRoot":"","sources":["../../../src/commands/onboard/validate-ci-yaml.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,yDAAyD;IACzD,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;CACjB;AAWD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,YAAa;IACzC,WAAW,EAAE,MAAM,CAAC;CACrB,KAAG,iBAAiB,EAgBpB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,YAAa;IAC9C,WAAW,EAAE,MAAM,CAAC;CACrB,KAAG,IAsBH,CAAC"}