# Getting started

[Documentation index](README.md) · [Commands and configuration](commands-and-configuration.md) · [Troubleshooting](troubleshooting.md)

## Requirements and compatibility

Pi Rich Questions is a Pi extension and must run in Pi's interactive terminal UI. The form does not run in RPC, JSON, or print mode. `/rich-questions` also needs an authenticated Pi model to perform automatic extraction; direct `ask_rich_questions` calls do not make that extra model request.

The package intentionally does not claim an exact minimum Pi version yet. Its current type checks and tests use `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` from the `0.80.10` development dependency line. If a current Pi release produces an API or keybinding error, include `pi --version`, the package version, and terminal details in a [bug report](https://github.com/ArtOfIntel/pi-rich-questions/issues).

## Install

Review third-party Pi package source before installing: extensions execute with your user account's permissions.

### npm (recommended)

```bash
pi install npm:pi-rich-questions
```

For a project-local install, run this in the project directory:

```bash
pi install -l npm:pi-rich-questions
```

Global packages live under Pi's global agent directory and are available across projects. Project-local packages are recorded under `.pi/` and load only after the project is trusted.

### Git

```bash
pi install git:github.com/ArtOfIntel/pi-rich-questions
```

Pin a reviewed tag or commit when reproducibility matters:

```bash
pi install git:github.com/ArtOfIntel/pi-rich-questions@v0.3.0
```

Use `-l` with either command for a project-local install.

### Local checkout

```bash
git clone https://github.com/ArtOfIntel/pi-rich-questions.git
cd pi-rich-questions
npm install
pi install .
```

For a temporary development run without installing the package:

```bash
pi -e ./extensions/index.ts
```

## First use

Start Pi interactively and request a demonstration:

```text
demo pi-rich-questions
```

Or wait for an assistant response containing questions, then run:

```text
/rich-questions
```

The first extraction opens a short configuration flow. See [Commands and configuration](commands-and-configuration.md).

## Manage the installation

```bash
pi list
pi config
pi update npm:pi-rich-questions
pi remove npm:pi-rich-questions
```

- `pi list` shows installed packages.
- `pi config` enables or disables package resources without uninstalling them.
- `pi update npm:pi-rich-questions` updates this npm package. `pi update --extensions` updates all unpinned packages.
- `pi remove npm:pi-rich-questions` removes the global npm installation; add `-l` for a project-local installation.

Use the same source form you installed when updating or removing. Pinned Git refs do not advance automatically; install the new tag or commit explicitly.

Restart Pi or run `/reload` after installation, update, enable/disable changes, or local extension edits so the resource set is reloaded. If both this package and another question extension register overlapping behavior, disable one through `pi config` and reload.

## Next steps

- Learn what each interface does in [Commands and configuration](commands-and-configuration.md).
- If you are asking the model to build a form, use the [authoring guide](authoring-questions.md).
- Keep the [interaction guide](interaction-and-accessibility.md) nearby for all keys.