# Agent Instructions

## Screenshots

When the user provides a screenshot path (e.g., `/tmp/pi-clipboard-xxx.png`), **ALWAYS** use the `read` tool to read the image file. Do NOT assume you can see the screenshot contents without reading it first.

---

# Sigil usage (for agents)

This repo is managed by **Sigil**, a minimal symlink-based dotfile tool.

## Repo layout

```
~/.dotfiles/
  <package>/
    config.lua
    files/
      ...
```

Each package has a `config.lua` that defines its target path per OS.

## Common commands

- `sigil apply` — apply symlinks (prompts for stale links)
- `sigil apply --prune` — prune stale links without prompting
- `sigil add <path>` — add a file/dir to the repo and symlink it
- `sigil status` — show stale links
- `sigil unlink <spec>` — restore file(s) to target and remove from repo
- `sigil remove <spec>` — same as unlink, plus remove package/subpath from repo

## Spec formats

`unlink/remove` accept these:

- `package` (entire package)
- `package:relative/path`
- repo path: `~/.dotfiles/<pkg>/files/...`
- target path: e.g. `~/.config/<app>/...`

Examples:

```
sigil unlink wezterm
sigil unlink wezterm:lua
sigil unlink ~/.dotfiles/wezterm/files/wezterm.lua
sigil unlink ~/.config/wezterm/wezterm.lua
```

## Notes

- If a repo file is missing, stale links should be pruned.
- Prefer `sigil add` over manual moves into `files/`.

# Editing dotfiles

When editing dotfiles, it is preferred to add/edit the files in this project directly, instead of going to the source. this way we can then use sigil apply --prune, and everything will be synced, even when there are new files.

# pi extensions

Extensions live in `pi/files/agent/extensions/`. 

**Discovery quirk:** If `package.json` has a `pi.extensions` field, pi **only** loads those listed extensions and skips auto-discovery of `*.ts` files. To enable auto-discovery (load all `.ts` files including symlinks), either:
- Remove the `extensions` field entirely: `"pi": {}`
- Or delete `package.json` if you don't need npm dependencies

Multi-file extensions (directories) need an `index.ts` entry point (or `package.json` with `pi.extensions` pointing to the entry file).
