# Ogram setup

You are setting up the Ogram platform tools for the user. Follow these steps carefully and keep the user informed at each stage. **Never surface technical details** (package manager internals, server names, sign-in flows) to the user — describe actions in plain product language only.

## Step 1 — Ensure the uv package manager is available

Check whether `uv` is available (`uv --version`). If it is not, **tell the user** that installing the Ogram tools requires installing the `uv` package manager first, and **ask for their OK** before proceeding.

Only install `uv` once the user has confirmed. Use the appropriate command for the platform:

- **macOS / Linux:**
  ```sh
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- **Windows (PowerShell):**
  ```powershell
  irm https://astral.sh/uv/install.ps1 | iex
  ```

After installation, start a new shell or `source` the profile file printed by the installer before continuing.

## Step 2 — Install the Ogram CLI

Run:

```sh
uv tool install ogram --index https://get.ogram.ch/packages/
```

If `ogram` is not on `PATH` after installation, run:

```sh
uv tool update-shell
```

and apply the export line it prints (or open a new shell). Verify with `ogram --version`.

## Step 3 — Sign in and activate the account

Run:

```sh
ogram setup
```

`ogram setup` runs through several steps and prints one line per step. Read the exit code to decide what to do next:

- **Exit code 0** — setup completed successfully. Continue to Step 4.
- **Exit code 2** — one step requires the user to sign in via the browser. A browser window has opened (or a URL was printed). Tell the user: *"Please complete sign-in in the browser that just opened, then let me know when you're done."* Once the user confirms, re-run `ogram setup` to continue.
- **Exit code 3** — the account is not yet enabled. Tell the user: *"Your account isn't activated yet. Please contact Ogram to complete account setup."* Stop here.
- **Exit code 1** — a step failed. Show the user the failing step line from the output and offer to re-run. `ogram setup` is safe to re-run; it picks up where it left off.

Repeat as needed until exit code 0.

## Step 4 — Verify

Run:

```sh
ogram status
```

`ogram status` returns:

- **Exit code 0** — everything is active. Confirm to the user: *"Ogram is set up and ready. Document Parsing is active."*
- **Exit code 2** — not signed in. Re-run `ogram setup` from Step 3.
- **Exit code 3** — account not entitled. Tell the user their account does not have access to this service and to contact Ogram.
- **Exit code 4** — service unreachable. Check network access and retry.

A successful `ogram status` output includes `Document Parsing: active`.

Diagnostics (if something goes wrong) are written to `~/.cache/ogram/setup-log.txt`. Share that file with Ogram support if asked.