# 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/`.

## Development
- When modifying this repo, rebuild and install the binary: `go build -o ~/.local/bin/sigil .`
- Bump the version constant in `main.go` for every change (follow semver: bugfix = patch, feature = minor, breaking = major)

## 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. This repo: `/home/thomasgl/programming/sigil/AGENTS.md`
2. Dotfiles repo: `/home/thomasgl/.dotfiles/AGENTS.md`

Keep them in sync so agents have correct instructions regardless of which directory they're working in.