---
name: schaffa-guide
description: Use when the user asks for a step-by-step guide.
---

# Schaffa Guide

Keep `SCHAFFA_TOKEN` in the environment. Start before the first action. Keep `.schaffa/guide-session.json` and `.schaffa/recordings/` local and uncommitted; they do not store the token.

Prefer automatic recording:

- Signed-in Chrome on macOS: `npx schaffa record --title "<title>" --chrome "<url>"`
- Isolated browser profile: `npx schaffa record --title "<title>" --browser "<url>"`
- Desktop: `npx schaffa record --title "<title>" --desktop --app <bundle-id>`

`--chrome` asks running Chrome for a window without creating or selecting a profile. Chrome chooses an existing profile session with its logins, extensions, and password manager. Do not promise a specific profile. The recorder binds to that exact window and ignores others. Use `--browser` only for an isolated profile.

Clicks get a compact cursor and red target outline. Close the recorded window or press Ctrl+C to publish. Alt+Shift+R pauses capture. After upload failure, run `npx schaffa guide sync`; a clean sync publishes.

Review every server step. Use a one-based number or exact step ID. Published fixes create an immutable revision:

- Inspect: `npx schaffa guide status --json`
- Edit: `npx schaffa guide edit-step --step <number-or-id> --title "<title>" --text "<instruction>"`
- Replace an image: `npx schaffa guide replace-screenshot --step <number-or-id> --screenshot <path>`
- Delete: `npx schaffa guide delete-step --step <number-or-id>`

Replacement does not recreate the cursor or target outline. Add them to the image before upload when needed.

For mixed work, record manually:

- Start: `npx schaffa guide start --title "<title>"`
- Add a step: `npx schaffa guide step --title "<step>" --text "<instruction>" --action <type> --target "<target>" --verification "<expected-result>"`
- Finish: `npx schaffa guide finish --json`

Record state changes, not every click. Add screenshots only when visible state helps. Never capture authentication, passwords, payments, private data, or secret-manager screens. Chrome pixels can expose tabs, extensions, and forms; pause and review. Desktop mode ignores other apps, editable values, and secure controls.

Writes use the persisted edit revision. On conflict, reload and reconcile. Retry with the original idempotent manifest entry.

Finishing publishes it automatically. Fix preflight findings and rerun `npx schaffa guide finish --json`. Return its URL.