# Integrate ScreenCI

> Turn a flow in your app into a polished, narrated product video that you regenerate whenever the UI changes.

You are an AI agent integrating ScreenCI into this project. Work through the steps below in order.

## If you were given a setup code

A prompt from the ScreenCI web app carries a one-time code shaped like `SC-XXXX-XXXX` and points at its own brief (`/add-project.md`, `/add-video.md`, or `/edit-video.md`); prefer that brief when you have it. Then skip steps 1 and 2: run `npx screenci@latest start <code>` from the repository of the app to record (or an empty folder). It creates or pulls the `./screenci` workspace, writes the credentials, installs the skill, and prints its own brief with the task; add `--name "<project name>"` to choose a new project's name (default: the folder name). Continue with step 3 inside `./screenci`, and report the link `preview` prints: the person who sent the code sees it open in their browser.

## 0. Use npm throughout

This brief uses **npm** commands (lockfile: `package-lock.json`). Use npm for **every** command below, including CI. Do not mix package managers.

If the project's root lockfile shows a different manager, follow that manager's brief instead: `/integrate.md` (npm), `/integrate-pnpm.md` (pnpm), or `/integrate-yarn.md` (yarn).

## 1. Scaffold the project (do this first)

Run this in the repository root before anything else. Always pass `--yes`; without it the command blocks on prompts and hangs. No account or setup token is needed.

```bash
npm init screenci@latest -- --yes
```

- init generates `.github/workflows/screenci.yaml`, scaffolds `screenci.config.ts` and `recordings/`, and installs the **`screenci` agent skill** at the repository root so you can author videos. The project name defaults to the repository root directory name.
- If the user already has a `SCREENCI_SECRET` from an existing account (shared across their org's projects), pass it as the first argument so recordings upload straight to their organization: `npm init screenci@latest PASTE_YOUR_SCREENCI_SECRET_HERE -- --yes`. Otherwise `preview` (step 4) previews under a local, anonymous trial session with no sign-in.

## 2. Wire up the app server (if recording a local app)

If the videos navigate to this project's own app, configure `screenci/screenci.config.ts` with a CI-aware `webServer` before authoring. Skip this step if the videos only navigate to a remote URL (staging, production).

```ts
webServer: {
  command: process.env.CI ? 'npm run preview' : 'npm run dev',
  cwd: '..', // path from screenci/ to the project root
  url: process.env.CI ? 'http://localhost:4173' : 'http://localhost:5173',
  reuseExistingServer: !process.env.CI,
  timeout: 120_000,
},
use: {
  baseURL: process.env.CI ? 'http://localhost:4173' : 'http://localhost:5173',
},
```

To also build this project's app in CI, uncomment the "Install app dependencies" / "Build app" hints in the generated `.github/workflows/screenci.yaml` and add the root lockfile to its `cache-dependency-path` (the file shows where). Do not hand-write the workflow. Match ports and build commands to the framework, and keep `webServer.command` on npm.

## 3. Author a video for the requested flow

The installed `screenci` skill guides authoring. Create one video for the feature or files the user pointed you at:

- Add `recordings/<flow>.screenci.ts` and remove the starter `recordings/example.screenci.ts`.
- Read the referenced source files and pages to learn the real routes, selectors, and flow. If you only have a live URL (or this brief's URL carried a `?live` flag), use the `playwright-cli` skill to explore it first. Never write a Playwright script of your own to explore: it starts signed out and behaves nothing like the recorder. When a session is saved, load it with `playwright-cli state-load screenci/.screenci/auth/default.json`.
- If a recording stops on a bot check ("Just a moment...", "Performing security verification") that a normal browser sails past, that is the recorder's headless user agent being refused, not your script. Set a desktop `userAgent` in `use` in `screenci.config.ts` and re-run. Details: [Configuration](/docs/reference/configuration.md).
- Every video must include narration via `video.narration({ en: { ... } })` and open by stating its purpose.
- Wrap setup (initial navigation, cookie banners, loading) in `hide()`, then move through the demo with visible clicks.
- **If the app needs a sign-in**, do not script one and never ask the user for a password or a one-time code. Run `npx screenci login` (it opens a browser and returns at once), ask the user to sign in there as they normally do, then run `npx screenci login --wait`, which blocks until they finish. Do not end your turn instead of waiting: clicking the card saves the session in the browser but tells you nothing, so if nothing is waiting the user clicks and sees no reply. The recording replays that session, so the video contains no sign-in and no credentials. The session stays on their machine. Details: [Signing in](/docs/guides/signing-in.md).
- If the user asked for a still image rather than a walkthrough, use `screenshot('<title>', async ({ page, crop }) => { ... })` in the same file kind. Stills are silent (never narrate one), `hide()` and camera helpers do nothing because only the final page state is captured, and `crop()` frames the shot. Details: [Screenshots](/docs/guides/screenshots.md).

## 4. Verify, then preview or export it yourself

Run the commands yourself once tests pass. Do not stop after authoring and ask the user to run them.

```bash
npx screenci test            # run until green; fix selectors/flow and rerun
npx screenci preview "<title>"  # once green: record the free live preview and open the web editor
npx screenci export             # only when the finished videos are wanted (or preview is unavailable)
```

Prefer `preview` over exporting right away: it records the video's live preview (free, no render), prints the video link, and exits. Report the printed link so the user can review the video. Edits made in the browser apply to the preview and every later export right away. `preview` needs no account: without a `SCREENCI_SECRET` it runs under a free anonymous trial session (multi-language previews included, up to 3 languages at once; keep a video's declared languages), and signing up in the editor upgrades the trial automatically. `SCREENCI_SECRET` is the only credential; there is nothing else to paste.

`export` requires an account with an active paid subscription: without one it refuses and prints a sign-up link (the anonymous trial is preview-only). With one, it records what changed, renders, waits, and downloads the finished files into `./exports/`.

Then report the URL the command printed (the video link from `preview`; after an export a single video links its page, e.g. `https://app.screenci.com/project/<projectId>/video/<videoId>?export=...`, several videos link the run page `https://app.screenci.com/export/...`) so the user can open it. Without a `SCREENCI_SECRET`, the video link is also how they view and claim the anonymous trial.

## Full documentation

Every documentation page is also available as raw markdown by appending `.md` to its URL (for example `https://screenci.com/docs/video-script-basics.md`).

### Getting Started

- [Overview](/docs.md): How ScreenCI works: record locally, refine in the web editor, export in the service, and serve from a CDN. The service never sees your app's source code, and the CLI is open source.
- [Create Videos from the Web App](/docs/guides/create-from-web-app.md): Make and change videos without a repository: the Add project, Add video, and Edit buttons hand your coding agent a one-time setup code, and the browser opens the result when the recording lands.
- [Agent Integration](/docs/agent-integration.md): The recommended path: point a coding agent at the integration brief so it scaffolds ScreenCI, authors a video for your flow, and records it.
- [Editor](/docs/editor.md): Edit videos visually in the web app: live preview, timeline cuts and pacing, narration, overlays, and render options. With screenci preview connected, edits are written back into your script, and Export renders the finished video.
- [AI Context](/docs/guides/ai-context.md): What coding agents learn about your product before they record: the repository, the site URL, whether they may start the app, whether it needs a sign-in, team notes, per-project overrides, and moving sources into the repository.
- [Branding](/docs/guides/branding.md): The look and voice every new video starts from: background, output size, cursor and default narration voice per organisation, shared image and video assets referenced by name, per-project overrides, cloned voice samples, the ElevenLabs API key, and how coding agents apply the branding.

### Fixtures

- [Narration](/docs/guides/narration.md): Attach spoken cues to a video, overlap narration with visible UI motion, choose voices, use speech markup, and connect ElevenLabs for custom voices.
- [Overlays](/docs/guides/overlays.md): Add intro clips, corner logos, transitions, and timed overlays to ScreenCI recordings from files, HTML, or React.
- [Languages](/docs/guides/languages.md): Record per-language video versions from one script: set browser locale automatically, localize narration and overlays, and control the recording mode.

### Guides

- [Camera and Zooming](/docs/guides/camera-and-zooming.md): Choose between autoZoom and manual framing, and use camera direction to guide attention without making the video frantic.
- [Mid-Video Overlay Updates](/docs/guides/overlay-updates.md): Resize, hide, and show the recording frame and narration bubble mid-video with animated transitions, and fade overlays in and out.
- [Screenshots](/docs/guides/screenshots.md): Capture branded still screenshots with the screenshot() fixture: crop to a component, set quality and dark mode, and frame the shot on a background with overlays.
- [Public URLs and Embeds](/docs/guides/public-urls-and-embeds.md): Enable public delivery for a video, understand stable language-specific URLs, and embed ScreenCI outputs in other sites.
- [Redact Sensitive Content](/docs/guides/redact.md): Keep secrets out of a recording with redact: mask locators, typed values, and always-secret elements in the page before the frame is captured, so they are never uploaded.
- [Screen Audio](/docs/guides/screen-audio.md): Capture system audio alongside the screen recording and mix it into the rendered video. Linux only, with an automatic, isolated per-worker capture sink.
- [Version History](/docs/guides/version-history.md): Every render is kept as a version. Select which one a public URL serves, roll back to an earlier render, and understand per-language retention. Paid feature.
- [Organisation & SSO](/docs/guides/organisation.md): Manage organisation members and roles, and enforce single sign-on with SAML through your own identity provider. SSO and member management are a Business feature.
- [Anonymous Trial](/docs/guides/anonymous-trial.md): Record, preview, and edit without an account: what the anonymous trial allows, its limits (preview-only, no exports), and how signing up claims the trial and unlocks exporting.
- [Signing In to Your App](/docs/guides/signing-in.md): Record an app that needs a login: sign in once in a real browser, and every recording replays that session. Works with two-factor, single sign-on, passkeys, and magic links, and ScreenCI never receives your credentials.

### Code and CI

- [Manual Setup & First Video](/docs/manual-setup.md): Wire ScreenCI up by hand: initialize a project, run the starter video locally, and record your first final video.
- [Video Script Basics](/docs/video-script-basics.md): Author .screenci.ts files with Playwright-like APIs, ScreenCI narration and camera helpers, and workflow-aware pacing.
- [Animated Interactions](/docs/guides/animated-interactions.md): Understand how ScreenCI instruments the Playwright page so visible actions like clicks, typing, mouse movement, and scrolling are animated.
- [CI Setup](/docs/ci-setup.md): Understand the generated GitHub Actions workflow, required secrets, and how to keep CI recordings deterministic.
- [Update ScreenCI](/docs/guides/update-screenci.md): Upgrade the screenci package, refresh Playwright when needed, and verify that existing videos still behave as expected.

### Reference

- [CLI](/docs/reference/cli.md): Command reference for screenci start, context, login, logout, merge-complete, init, test, preview, export, project info, and public delivery commands.
- [Configuration](/docs/reference/configuration.md): Configure project identity, file locations, rendering defaults, upload behavior, and Playwright integration in screenci.config.ts.
- [Public Delivery API](/docs/reference/public-delivery-api.md): Technical reference for the unauthenticated endpoints that serve published videos, thumbnails, subtitles, and metadata.