# Agent-readable CLI

`ui-clone` is the preferred agent and human entrypoint for pipeline state.
The older `python -m ui_clone.*` commands remain supported for hooks and
compatibility.

## Install / run

```bash
npx ui-clone-cli --help
```

From a checkout, use the local bin directly:

```bash
node bin/ui-clone --help
```

The wrapper dispatches to the Python modules in this package. It prefers
`uv run --project <package-root> python -m ...` and falls back to `python3`
with `PYTHONPATH=<package-root>`.

## Pipeline status

```bash
npx ui-clone-cli pipeline <url> <component-or-run-dir> <session> status --json
```

Use this before reading raw artifacts. The JSON response includes:

- `status`: `active`, `verified`, `needs_verify_stamp`, or terminal status.
- `run_dir` / `ref_dir`: canonical evidence directory.
- `impl_dir`: implementation directory when discoverable.
- `current_gate`, `completed_steps`, `remaining`.
- `read_for_llm`: small files safe for agents to read.
- `do_not_read`: raw DOM/style/screenshot/video directories to avoid.

The pipeline command also supports shorthand:

```bash
npx ui-clone-cli <url> <component-or-run-dir> <session> status --json
```

## Next action

```bash
npx ui-clone-cli pipeline <url> <component-or-run-dir> <session> next --json
```

Use this to resume interrupted work. It prints the current gate, terminal
state if any, next action, and safe read paths.

## LLM report

```bash
npx ui-clone-cli pipeline <url> <component-or-run-dir> <session> report --for-llm
```

Use this for compact handoff context. Prefer it over grepping large raw
artifacts.

## Verify

```bash
npx ui-clone-cli pipeline <url> <component-or-run-dir> <session> verify --json
```

`verify --json` runs post-implementation gates and returns machine-readable
results. On success it creates `verify-stamp.json`. On failure it writes
verify reports/logs and records `terminalState`; it does **not** create a fake
success stamp.

## Terminal failed / incomplete state

Use terminal state when an evidence run is intentionally over but not
verified:

```bash
npx ui-clone-cli state terminal <ref-dir> \
  --status incomplete \
  --category hardening-probe-incomplete \
  --gate section-compare \
  --reason "canonical verify failed; evidence preserved"
```

Allowed `--status` values:

- `failed`
- `incomplete`
- `unclonable`
- `abandoned`

`--category` is a free-form evidence category. Do not use terminal state to
claim success; success remains `verify-stamp.json` only.

## Layout compatibility

Phase 1 supports both layouts:

- Legacy: `tmp/ref/<component>`
- Agent-first: `.ui-clone/runs/<id>`

Passing an existing run directory or a run id under `.ui-clone/runs/` resolves
to that directory. Automatic migration/copying of existing evidence is out of
scope.
