Implement/modify UI for task via an iterative, diff-gated vision loop.

Workflow: 1. Load .agy-ui-scope and create an isolated git worktree. 2. Start the dev server (from scope.serve) inside the worktree and wait for it to be ready. 3. Loop up to max_iters: screenshot the route across viewports, build a vision prompt listing the shot + design-ref paths, run agy -p in the worktree, diff-gate the result, re-screenshot. Stop early once a round produces no new in-scope changes. 4. Collect the final diff, stop the server, clean up the worktree.

Args: project_dir: Absolute path to the project root (must contain the scope). task: Natural-language description of the UI change. design_refs: Optional absolute paths to design reference images. target_route: Optional route appended to scope.serve.url (e.g. "/login"); defaults to the base URL. max_iters: Maximum vision-loop iterations. apply: When True (default), copy the in-scope changed files from the worktree back into project_dir so the user can git diff and review/commit them. When False, the worktree is collected and torn down without writing anything to the project. match_threshold: Only used when design_refs is non-empty. agy is asked to self-report a 0-100 match score against the mockup each round; the loop stops early once that score reaches this threshold.

Returns: A dict with files_changed, diff, escalations, iterations, shots_before, shots_after, warnings, applied (whether apply was requested), applied_files (paths written to the project), match_score (the last self-reported 0-100 score, or None when no design refs were supplied), and match_gaps (the last reported remaining differences, or "").

Serve the app, screenshot it, and have agy critique it read-only.

Any file agy edits during the critique is reverted by the diff-gate, so this tool never mutates the project.

When a11y is set (and the platform is a web target), each target is also audited with axe-core; the violations ground agy's critique and are returned structurally under a11y. Native platforms have no DOM, so the audit is skipped there with a note.

Args: project_dir: Absolute path to the project root (must contain the scope). target_route: Optional route appended to scope.serve.url. against_design: Optional absolute paths to design reference images to critique against. a11y: Run axe-core accessibility checks on web targets (default True).

Returns: A dict with critique (agy's text), shots (captured paths), targets (the reviewed target names), a11y (a {target: [violations]} map; empty when disabled/native), and warnings.

Auto-detect the stack and write a starter .agy-ui-scope config.

Zero-to-config helper for non-technical users: inspects the project's manifests (package.json / pubspec.yaml / lockfiles), guesses the framework, serve command, and edit-scope globs, and writes a .agy-ui-scope YAML at the project root that the user can then tweak by hand. After this, the ui_implement / ui_review tools run with no further setup.

Args: project_dir: Path to the project root to scan and write into. overwrite: When False (default) an existing .agy-ui-scope is left untouched and status: "exists" is returned. Pass True to regenerate it (clobbering the existing file).

Returns: A dict describing the outcome: status (ok/exists/error), scope_path (absolute), written (whether the file was written), detected (framework/platform/serve/package-manager), allow and deny globs, design_dir_found, next_steps, and warnings.