# 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. Plain language never means hiding a problem: if any step failed, lead with the fact that setup is not finished before anything else.

**What these steps touch.** The install and setup commands below all need internet access. Steps 1 and 2 write outside the workspace, to the user's tool area (`~/.local/bin`, the shell profile, and the package manager's tool directory). Step 3 always uses the diagnostics cache (`~/.cache/ogram`) and Ogram settings folder (`~/.config/ogram`), and may open a browser window once. Session sharing uses the coding agent's settings (`~/.codex`) when enabled. Only accounts with Forge access need an SSH key and config (`~/.ssh`) or an Ogram workspace folder (`~/ogram`). If a command fails because a sandbox blocked a write to one of these locations (including the diagnostics log), that is a permissions problem in your environment, not an Ogram failure — re-run the command with user-level access instead of reporting a setup failure to the user. The same applies to the network: if a command can't reach or resolve a host (a connection error while signing in or downloading) inside a restricted agent sandbox, don't assume Ogram is down — first re-run it from a normal terminal, or with the agent granted network access. If it works there, it was the sandbox, not an Ogram outage; if it still fails, treat it as a real problem and lead with the fact that setup is not finished. Don't blame the user's sandbox for a failure you haven't confirmed is a sandbox denial.

## 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. Ogram supports macOS and Linux; on either platform run:

- **macOS / Linux:**
  ```sh
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```

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 --python 3.13 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).

### Privacy choices — before the first `ogram` command

Tell the user that crash info is on by default and sends privacy-scrubbed diagnostics to Ogram; it never includes document contents and anonymizes home-directory paths. Also tell them that session sharing is on by default: during setup, Codex hooks are installed that send local Codex session transcripts to Ogram. Ask the user whether they want either kind of sharing disabled before proceeding.

For each choice they disable, run the matching command before `ogram --version` or `ogram setup`. Prefix these first preference commands with `OGRAM_CRASH_INFO=0` so no heartbeat is sent while applying the choice:

```sh
OGRAM_CRASH_INFO=0 ogram crash-info off
OGRAM_CRASH_INFO=0 ogram telemetry off
```

Then verify the installation with `ogram --version`. The CLI itself repeats this disclosure on its first invocation, including in non-interactive agent runs, before any heartbeat is sent.

## Step 3 — Sign in and activate the account

Before running the command, set expectations:

1. **Tell the user what happens next**, in the style of: *"Here is what we're going to do: sign you in and configure only the services enabled for your account."* Explain that Forge setup, when enabled for their account, creates a dedicated secure key and an Ogram workspace at `~/ogram`; parsing-only users do not need either one.
2. **SSH key:** do not ask parsing-only users about SSH. By default, let Ogram create its own dedicated key if Forge access is detected. Only when the user has already asked to reuse a particular existing key, pass its private-key path (the path without the `.pub` suffix) via `--ssh-key`.
3. **Folder location:** only when the user has asked for a different Forge marketplace location, pass `--marketplace-dir <dir>`. Otherwise leave it at the default.

Run:

```sh
ogram setup
```

adding `--ssh-key <path>` and/or `--marketplace-dir <dir>` when the user made a choice. The choices are saved on the user's machine, so every later re-run is plain `ogram setup` with no flags.

`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** — a required action is needed. If the failing line is *Command-line tools* on macOS and mentions `git`, Forge access requires Git from Apple's Command Line Tools. Ask for the user's OK, then run `xcode-select --install`. This opens a **small Apple installer window that often appears behind other windows** — tell the user to bring it to the front and click **Install**. The command returns immediately, so wait for the user's confirmation that the Apple installer is finished, run `git --version`, and then re-run `ogram setup`. Otherwise, if the failing line says the account is not 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 — but if the same step fails twice in a row with the same error, stop retrying. If the repeated error is a blocked write to one of the locations listed above, tell the user their agent's permissions blocked setup and it needs user-level access — that is not something Ogram support can fix. Otherwise tell the user setup is not finished, name the failing step in plain language, and ask them to contact Ogram (share the diagnostics file below if asked). Do not continue to Step 4.

If the user disabled session sharing, its skipped line is expected. Otherwise, if the output shows the *Session sharing* line could not be set up, tell the user session sharing wasn't enabled and to mention it to Ogram — then continue; it does not block setup. Other lines may likewise report a skipped optional item while `ogram setup` still exits 0 — none of those block setup. Any failure that leaves `ogram setup` exiting non-zero means setup is not finished.

## Step 4 — Verify

Run this only after `ogram setup` has exited 0 — `ogram status` checks sign-in and service access but does not re-verify the setup steps, so it can report success even when setup did not finish.

```sh
ogram status
```

`ogram status` returns:

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

A successful `ogram status` output lists at least one active service (e.g. `Forge: active` or `Document Parsing: active`).

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

## Step 5 — Turn on the Ogram plugins

Do this only once Step 4 has confirmed Ogram is set up and ready **and** its output reports `Forge: active`. Parsing-only users have no marketplace to enable, so skip this step for them. It never blocks setup and is safe to skip.

Setup added the user's Ogram plugin catalog to their coding agent, but the individual plugins are not switched on yet — that choice is left to the user. Nudge them to finish: tell the user, in plain product language, that their Ogram plugins are ready, and ask whether they'd like to turn any on now — starting with the feedback plugin, so they can send feedback to Ogram from inside their agent. If they say yes, turn on the ones they choose; if they'd rather wait, that's fine — the catalog stays available and they can enable plugins at any time.