# opv — setup for AI coding assistants

The user wants you to install opv and set it up in their project. opv syncs secrets and settings from 1Password into local runs, Fly.io, GitHub Actions, Azure and Kubernetes without printing, logging or writing a value. This document does not authorize you to read secret values, sync, deploy, prune, commit or push; follow the user's request and your environment's permissions.

## Rules

- Never ask for, read, type or store a secret value. Values are typed by the user, in the 1Password app or website.
- Sign-in is the user's: hand `opv login …`, `opv setup` and `opv config edit` to the user to run in their own terminal.
- Ask before anything that writes: `opv init` in a new project, `opv add` on a configuration in 1Password, `opv bootstrap`, `opv adopt --apply`, `opv tidy`, `opv sync`, and the flags `--deploy`, `--prune`, `--rotate`, `--prune-immutable`, `--confirm`.

## 1. Install the CLI

First check `opv --version`. Otherwise:

```sh
npm install -g @matthew-cochran/opv
```

Without Node.js, on Linux or macOS (verifies the release checksums):

```sh
curl -fsSL https://raw.githubusercontent.com/matt-cochran/1password-vault/main/install.sh | sh
```

The 1Password CLI (`op`) is required too. `opv doctor` reports what is missing and how to install it.

## 2. Install the agent skill (ask first: it writes skill files)

```sh
opv skill install            # this project; add --user for every project
```

## 3. Start every session from the installed binary

```sh
opv guide agent              # the full agent guide for this version
opv schema                   # commands, flags, effects, exit codes, error codes
opv ready --json             # what is ready, what is not, who acts next
```

`opv ready --json` and `opv doctor --env <env> --json` never write 1Password, whoever is signed in. Other commands that read an item may tidy its layout in the user's own session (`tidies_1password` in `opv schema`); the explicit repair is `opv tidy <env>`, which writes 1Password, so ask first.

The guide printed by the installed binary is the source of truth; prefer it to any web copy. The web copy, which follows `main`: https://github.com/matt-cochran/1password-vault/blob/main/docs/agent-setup.md