@earendil-works/pi-coding-agent 0.87.0 → 0.99.0

package/docs/quickstart.md

@@ -1,167 +1,122 @@
 # Quickstart
 
-This page gets you from install to a useful first pi session.
+Pi runs in your terminal and works with files on your machine. To use it, you need access to a model through a supported provider. This can be a subscription, an API key, or a local model.
 
-## Install
+For native Windows setup, read [Windows Setup](windows.md). For Android, read [Termux Setup](termux.md).
 
-Pi is distributed as an npm package:
+## 1. Install Pi
+
+On macOS or Linux, you can use the installer:
 
 ```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+curl -fsSL https://pi.dev/install.sh | sh
 ```
 
-`--ignore-scripts` disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs.
-
-### Uninstall
-
-Use the package manager that installed pi. The curl installer uses npm globally, so curl and npm installs are removed with npm:
+Alternatively, install Pi from npm. This requires Node.js 22.19 or newer:
 
 ```bash
-# curl installer or npm install -g
-npm uninstall -g @earendil-works/pi-coding-agent
+npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+```
 
-# pnpm
-pnpm remove -g @earendil-works/pi-coding-agent
+Pi does not require dependency lifecycle scripts for a normal npm installation.
 
-# Yarn
-yarn global remove @earendil-works/pi-coding-agent
+Verify the installation:
 
-# Bun
-bun uninstall -g @earendil-works/pi-coding-agent
+```bash
+pi --version
 ```
 
-Uninstalling pi leaves settings, credentials, sessions, and installed pi packages in `~/.pi/agent/`.
+## 2. Start Pi
 
-Then start pi in the project directory you want it to work on:
+Change to the folder you want Pi to work with, then start it:
 
 ```bash
-cd /path/to/project
+cd /path/to/folder
 pi
 ```
 
-## Authenticate
+The working folder helps Pi discover relevant files, instructions, and configuration. Pi also uses it to group saved sessions.
+
+<p align="center"><img src="images/interactive-mode.png" alt="Pi running in a terminal with a conversation, input editor, and status footer" width="750"></p>
+
+The interface shows your conversation, an editor for prompts and commands, and a footer with the current folder, model, and session status. See [Use Pi in the terminal](usage.md) to learn how to add files, run commands, direct ongoing work, and manage results.
 
-Pi can use subscription providers through `/login`, or API-key providers through environment variables or the auth file.
+## 3. Choose a model
 
-### Option 1: subscription login
+A **model** generates Pi's responses. A **provider** is the service or account Pi uses to access that model.
 
-Start pi and run:
+In Pi, run:
 
 ```text
 /login
 ```
 
-Then select a provider. Built-in subscription logins include Claude Pro/Max, ChatGPT Plus/Pro (Codex), and GitHub Copilot.
+Choose a provider, then follow the prompts to use a subscription or store an API key. Run `/model` afterward if you want to select a different available model.
 
-### Option 2: API key
+See [Choose a model and provider](models.md) for supported providers, environment-variable authentication, local models, and custom endpoints.
 
-Set an API key before launching pi:
+## 4. Give Pi a task
 
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-pi
-```
-
-You can also run `/login` and select an API-key provider to store the key in `~/.pi/agent/auth.json`.
-
-See [Providers](providers.md) for all supported providers, environment variables, and cloud-provider setup.
+Pi shows each file read, search, command, and edit it performs. It does not ask before every tool call.
 
-## First session
-
-Once pi starts, type a request and press Enter:
+Enter a task that matches your work, for example:
 
 ```text
-Summarize this repository and tell me how to run its checks.
+Summarize @meeting-notes.md and save the action items to action-items.md.
 ```
 
-By default, pi gives the model four tools:
-
-- `read` - read files
-- `write` - create or overwrite files
-- `edit` - patch files
-- `bash` - run shell commands
-
-Additional built-in read-only tools (`grep`, `find`, `ls`) are available through tool options. Pi runs in your current working directory and can modify files there. Use git or another checkpointing workflow if you want easy rollback.
-
-## Give pi project instructions
-
-Pi loads context files at startup. Add an `AGENTS.md` file to tell it how to work in a project:
-
-```markdown
-# Project Instructions
-
-- Run `npm run check` after code changes.
-- Do not run production migrations locally.
-- Keep responses concise.
+```text
+Explain how this repository is structured and how to run its checks.
 ```
 
-Pi loads:
-
-- `~/.pi/agent/AGENTS.md` for global instructions
-- `AGENTS.md` or `CLAUDE.md` from parent directories and the current directory
-
-If a directory contains `AGENTS.override.md`, Pi loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory.
-
-Restart pi, or run `/reload`, after changing context files.
+```text
+Compare @previous.csv with @current.csv and summarize the important changes.
+```
 
-## Common things to try
+Type `@` in the editor to search for a file instead of entering its full path. When Pi finishes, review its response and any changed files. Use version control or backups for important work. For untrusted or unattended work, use a container or another sandbox. See [Security](security.md).
 
-### Reference files
+## Continue later
 
-Type `@` in the editor to fuzzy-search files, or pass files on the command line:
+Pi saves sessions automatically. Exit Pi, then resume the most recent session for the same working folder with:
 
 ```bash
-pi @README.md "Summarize this"
-pi @src/app.ts @src/app.test.ts "Review these together"
+pi --continue
 ```
 
-Images or text can be pasted with Ctrl+V (Alt+V on Windows); images can also be dragged into supported terminals.
+Use `/resume` to choose another saved session. See [Continue or branch a session](sessions.md) for session naming, branching, compaction, export, and sharing.
 
-### Run shell commands
+## Next steps
 
-In interactive mode:
+- [Use Pi interactively](usage.md) to learn input, commands, shortcuts, and queued messages.
+- [Add instructions](configuration.md#context-files) that Pi should follow whenever it works in a folder.
+- [Choose a model and provider](models.md).
 
-```text
-!npm run lint
-```
-
-The command output is sent to the model. Use `!!command` to run a command without adding its output to the model context.
+### Choose how to customize Pi
 
-### Switch models
+Start with the least powerful mechanism that meets your need:
 
-Use `/model` or Ctrl+L to choose a model for the current session. Press Ctrl+S in the model picker to save the highlighted model as the startup default. Use `/thinking` to choose a thinking level for the current session, or Ctrl+S in that picker to save the startup default thinking level. Use Shift+Tab to cycle thinking level. Use Ctrl+P / Shift+Ctrl+P to cycle through scoped models.
+| Need | Start with |
+|---|---|
+| Give Pi persistent instructions for a folder | [`AGENTS.md`](configuration.md#context-files) |
+| Reuse a prompt from the `/` menu | [Prompt template](prompt-templates.md) |
+| Add task-specific instructions and supporting files | [Skill](skills.md) |
+| Add executable tools, commands, or event handlers | [Extension](extensions.md) |
+| Build a custom terminal component | [Terminal UI](tui.md) |
+| Connect an unsupported model service | [Custom provider](custom-provider.md) |
+| Install or distribute several resources | [Pi package](packages.md) |
 
-### Continue later
+## Uninstall Pi
 
-Sessions are saved automatically:
+If you installed Pi with npm, run:
 
 ```bash
-pi -c                  # Continue most recent session
-pi -r                  # Browse previous sessions
-pi --name "my task"    # Set session display name at startup
-pi --session <path|id> # Open a specific session
+npm uninstall -g @earendil-works/pi-coding-agent
 ```
 
-Inside pi, use `/resume`, `/new`, `/tree`, `/fork`, and `/clone` to manage sessions.
-
-### Non-interactive mode
-
-For one-shot prompts:
+If you used the installer, run it again and choose **Uninstall Pi**:
 
 ```bash
-pi -p "Summarize this codebase"
-cat README.md | pi -p "Summarize this text"
-pi -p @screenshot.png "What's in this image?"
+curl -fsSL https://pi.dev/install.sh | sh
 ```
 
-Use `--mode json` for JSON event output or `--mode rpc` for process integration.
-
-## Next steps
-
-- [Using Pi](usage.md) - interactive mode, slash commands, sessions, context files, and CLI reference.
-- [Providers](providers.md) - authentication and model setup.
-- [Settings](settings.md) - global and project configuration.
-- [Keybindings](keybindings.md) - shortcuts and customization.
-- [Pi Packages](packages.md) - install shared extensions, skills, prompts, and themes.
-
-Platform notes: [Windows](windows.md), [Termux](termux.md), [tmux](tmux.md), [Terminal setup](terminal-setup.md), [Shell aliases](shell-aliases.md).
+Neither method removes configuration, credentials, sessions, or installed Pi packages from `~/.pi/agent/`.