98 lines
3.4 KiB
Markdown
98 lines
3.4 KiB
Markdown
# 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/ # common files (all OSes)
|
|
files.linux/ # Linux-specific overrides
|
|
files.macos/ # macOS-specific overrides
|
|
files.windows/ # Windows-specific overrides
|
|
```
|
|
|
|
Each package has a `config.lua` that defines its target path per OS.
|
|
|
|
### Per-OS file variants
|
|
|
|
Create `files.<os>/` directories alongside `files/` for OS-specific overlays:
|
|
|
|
```
|
|
pi-agent/
|
|
files/
|
|
settings.json # shared config
|
|
files.linux/
|
|
agent.json # Linux-specific
|
|
files.macos/
|
|
agent.json # macOS-specific
|
|
```
|
|
|
|
On Linux, `agent.json` links to `files.linux/agent.json`. On macOS, it links to `files.macos/agent.json`. Files in `files/` are applied first, then OS-specific variants overlay on top.
|
|
|
|
## 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.
|
|
|
|
**Important:** Whenever you add new files to the repo (e.g., create new scripts or configs), you must run `sigil apply` afterwards to create the symlinks. New files in `files/` directories are not automatically linked until `sigil apply` is run.
|
|
|
|
## IMPORTANT: Update AGENTS.md files when Sigil changes
|
|
|
|
Whenever Sigil is modified (new features, behavior changes, new commands), you MUST update the AGENTS.md documentation in BOTH locations:
|
|
1. Sigil repo: `/home/thomasgl/programming/sigil/AGENTS.md`
|
|
2. This dotfiles repo: `/home/thomasgl/.dotfiles/AGENTS.md`
|
|
|
|
Keep them in sync so agents have correct instructions regardless of which directory they're working in.
|
|
|
|
# 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).
|