# pi-profiles

Reusable pi configuration profiles — list, load, and capture from any project.

This package lets you save and reuse your `.pi/` setup (extensions, skills, settings, prompts) as a named profile and switch between profiles per-project via slash commands.

## Install

**From npm** (recommended):

```bash
pi install npm:@timurci/pi-profiles
```

**From GitHub**:

```bash
pi install git:github.com/timurci/pi-profiles
```

Pin a specific version:

```bash
pi install npm:@timurci/pi-profiles@0.1.0
pi install git:github.com/timurci/pi-profiles@v0.1.0
```

## Usage

Three slash commands are registered when the extension is loaded:

| Command | Description |
| --- | --- |
| `/profiles` | List all available profiles |
| `/profile <name>` | Load a profile (prompts to choose if name omitted) |
| `/profile-from-project` | Capture the current `./.pi` as a new profile |

### `/profile <name>`

Creates a symlink at `./.pi` pointing to `~/.pi/profiles/<name>`, then
triggers a `/reload` so the profile's extensions, skills, etc. take
effect immediately.

If `./.pi` already exists:

- **Symlink to another profile** — asked to confirm before replacement
- **Real file or directory** — asked to confirm before being removed and replaced
- **Already pointing to the requested profile** — no-op

Tab completion is available for the profile argument.

### `/profile-from-project`

Copies `./.pi` into `~/.pi/profiles/<new-id>/`. If a profile with the
same id already exists, you'll be warned and asked to confirm the
overwrite.

If `./.pi` has a `PROFILE.md`, its `name` and `description` are reused
and no prompts are shown.

If `./.pi` does **not** have a `PROFILE.md`, the command prompts for:

1. **Name** — empty input falls back to the cwd basename.
2. **Description** — required; the prompt re-asks if you submit an empty value.

A `PROFILE.md` is then generated in the new profile directory using
the values you provided.

## Config

Optional: `~/.pi/agent/extensions/profiles.json`

```json
{
  "profilesDir": "/custom/path/to/profiles"
}
```

If `profilesDir` is omitted, defaults to `~/.pi/profiles`. Run
`/reload` after editing.

## Profile format

Each profile is a directory under `profilesDir` containing a `PROFILE.md`
file with YAML frontmatter (same convention as `SKILL.md`):

```
~/.pi/profiles/
└── python-dev/
    ├── PROFILE.md
    ├── skills/
    │   └── ...
    └── extensions/
        └── ...
```

`PROFILE.md`:

```markdown
---
name: python-dev
description: Python development environment with ML/data tooling.
---

# Python Profile

Add profile documentation here.
```

Only `name` and `description` are read by this extension. The rest of
the file is freeform.

## Security

This extension runs with your full user permissions, creates symlinks in your current working directory, and copies files from `./.pi` to your home directory. The [pi security model](https://github.com/earendil-works/pi-mono/blob/main/docs/security.md) is explicit that extensions and third-party packages are full-trust — do not install profiles from sources you have not reviewed.