# Import GitHub repositories into Vex (agent instructions)

You are a coding agent running on the user's machine. Follow these steps to import the
user's GitHub repositories into their Vex organization with the non-interactive Vex CLI.
The user's message should name the Vex organization slug; if it does not, ask for it
before running anything.

## Rules

- Always run `vex repo import` with `--yes --no-tui --format jsonl` so it never opens
  an interactive UI and prints machine-readable events, one JSON object per line.
- Never pass secrets or tokens as command-line flags. The CLI uses the stored login.
- Importing creates repositories in the organization's Home repository on the Vex server.
  Confirm the organization slug and the repository selection with the user before starting.
- When a step needs the user's browser (sign-in, GitHub App authorization), show them the
  URL and wait. Do not try to automate the authorization page.

## 1. Ensure the Vex CLI is installed

```sh
vex version
```

If the command is missing, install it and check again:

```sh
curl -fsSL https://dl.vex.sc/install.sh | sh
```

## 2. Ensure the user is signed in

```sh
vex whoami
```

If not signed in, run `vex login --no-browser`, give the user the verification URL it
prints, and wait for them to finish in their browser. Then confirm with `vex whoami`.

## 3. Choose repositories

Prefer naming each repository explicitly with a repeatable `--github-repository` flag.
Use `--all` (imports every eligible App-visible repository) only when the user clearly
asked for everything.

## 4. Run the import

```sh
vex repo import --org <org-slug> \
  --github-repository <owner>/<repo> \
  --yes --no-tui --format jsonl
```

Or, with the user's explicit confirmation:

```sh
vex repo import --org <org-slug> --all --yes --no-tui --format jsonl
```

## 5. Handle events

Each stdout line is a JSON event with an `event` field:

- `action_required` with a `url`: the GitHub App is not authorized yet. Show the URL
  to the user; the command keeps polling and continues automatically after they finish.
  (Without `--format jsonl` the same URL is printed as
  `GitHub App authorization required: <url>` on stderr.)
- `selected`: lists the repositories the session will import.
- `phase` / `progress` / `log`: normal progress; no action needed.
- `completed`: one repository finished.
- `failed` with `"retryable": true`: note the `item_id` for a retry (step 6).
- `session_completed` and `stopped` with `exit_code`: the run is over. Exit code 0
  means every selected repository imported successfully.

## 6. Resume or retry when needed

Sessions are durable on the server. If the command is interrupted, resume the latest
session:

```sh
vex repo import --resume --yes --no-tui --format jsonl
```

Retry a single failed item within a session:

```sh
vex repo import --resume <session-id> --retry <item-id> --yes --no-tui --format jsonl
```

## 7. Report the outcome

Tell the user which repositories imported and which failed (with the failure messages).
Imported repositories appear at `https://vex.sc/<org-slug>/repos`, and future GitHub
sync runs in Vex cloud automatically — the local machine was only needed for this initial
import. Suggest `vex clone <org-slug>/home` as the next step to start working.