ScriptTap AI Best Practices v1
URL target: https://scripttap.com/ai_best_practices_v1.txt

Goal:
Build scripts that are useful, importable, fast, and easy for the user to finish inside ScriptTap.

General rules:
- Build by default. Missing details should produce incomplete-but-importable drafts, not refusal.
- Keep commands simple unless the user clearly needs advanced behavior.
- Prefer fewer screen reads and tighter search areas.
- Prefer explicit user-completion notes over guessed coordinates/assets.
- Imported AI scripts start disabled/AI-marked; the user reviews and enables them.

Nickname completion markers:
- Every command needs a useful nickname of 20 characters or less.
- Complete commands should use short clear nicknames without `ai!`.
- Incomplete commands that need user work must start the nickname with exact lowercase `ai!`.
- Use compact labels such as `ai!set x,y`, `ai!need text`, `ai!add color`, or `ai!capture img`.
- Put the full user-completion instructions in top-level `notes`, not in the nickname.

Screen-read priority:
1. Use `get_pixel_color` when one known pixel tells the state.
2. Use `pixel_find` when a color or small set of colors identifies the target.
3. Use `img_find` when shape/image recognition is actually needed.
4. Use `visual_trigger` for reusable watcher-style screen conditions.

Performance:
- Keep all search/read areas tight.
- Do not use full-screen image or pixel scans unless the user explicitly asks for full screen or no smaller area is known.
- If area is unknown, mark the command incomplete and explain the needed area in `notes`.
- Keep assets small. ScriptTap image assets are limited to 32x32.
- Transparent pixels are useful when they reduce active pixel count without losing recognition quality.
- Avoid unnecessary debug screenshots and logs in performance-sensitive scripts.

Confidence:
- ScriptTap `confidence` is deterministic pixel/channel/tolerance-style matching.
- It is not AI semantic visual similarity.
- Do not treat confidence as "looks like this button" unless the function's documented matching fields support that use.

Concurrent behavior:
- Concurrent `loop` runs in a background branch.
- It does not globally block other runtime branches by itself.
- `pause_concurrent` is user-facing `Exclusive`; it is the cross-runtime blocking section.
- Use `pause_concurrent` and `unpause_concurrent` only when a watcher/action block must prevent other branches from touching screen reads or gestures at the same time.

Watcher pattern:
- Use a concurrent loop for background checks.
- Put screen read conditions inside the loop.
- Route to an action block with `goto`, `call`, or direct commands.
- Wrap action blocks in `pause_concurrent` only when needed for safe exclusive control.

Flow:
- Always pair `loop` with `end_loop`.
- Always pair `pause_concurrent` with `unpause_concurrent`.
- Always pair IF starts (`or`, `and`, `xor`, `rgb_confidence`) with matching end rows.
- `else` belongs only between an IF start and that IF's end row.
- Use `label` and `goto` for simple current-script routing.
- Use `call` for reusable child scripts.

Variables:
- Declare variables with `set_variable` when it improves readability.
- Writer commands can create valid output variables.
- Reader commands need valid available variables.
- Use typed variable names: `i1` integer, `b1` boolean, `h1` hex, `s1` string, `t1` time.
- Use array letters only where the function expects an array letter, for example `i` for Integer array output.

Assets:
- Never embed images in JSON.
- Reference asset names only.
- If a needed asset is missing, add `assetRequirements[]`, mark the command incomplete, and explain what the user must capture.
- Do not assume ScriptTap will find an existing asset by name during import.

Common good patterns:
- `get_pixel_color` -> `rgb_confidence` IF -> action.
- `pixel_find` with tight area -> output variables -> IF or Tap.
- `img_find` with tight area and named asset requirement -> incomplete draft for user capture.
- Concurrent watcher loop -> Exclusive action -> Stop Call or GoTo when target appears.
- `prompt_me` -> variable output -> IF route.

Common mistakes:
- Returning Markdown fences.
- Returning questions instead of JSON.
- Making `.sts`.
- Embedding base64 images.
- Inventing command fields.
- Marking image commands complete when assets are missing.
- Leaving incomplete commands without an `ai!` nickname.
- Using `ai!` on complete commands.
- Using full-screen scans for small buttons.
- Putting `else` outside an IF block.
- Moving an IF end row above its `else`.