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).

1.9 KiB Raw Blame History