From 59dbfd8162b25084fb8c521883cf6796a034b1f3 Mon Sep 17 00:00:00 2001
From: "Thomas G. Lopes" <thomasgl@pm.me>
Date: Thu, 19 Feb 2026 20:25:28 +0000
Subject: [PATCH] Expand README

---
 README.md | 23 ++++++++++++++++++-----
 1 file changed, 18 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 8dca315..aa5db96 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Sigil
 
-Minimal dotfile symlink manager with per-package Lua config.
+Sigil is a minimal symlink-based dotfile manager with per-package Lua config.
 
 ## Install (dev)
 
@@ -10,17 +10,21 @@ go run . <command>
 
 ## Commands
 
-- `sigil apply` - apply symlinks from `~/.dotfiles`
-- `sigil add <path>` - add an existing file or folder (merges into existing package for single files)
+- `sigil apply` — apply symlinks from `~/.dotfiles`
+- `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) and remove from repo
+- `sigil remove <spec>` — same as unlink, plus remove package/subpath
 
 ## Repo layout
 
 ```
 ~/.dotfiles/
-  nvim/
+  <package>/
     config.lua
     files/
-      init.lua
+      ...
 ```
 
 ## `config.lua`
@@ -35,7 +39,16 @@ return {
 }
 ```
 
+## Spec formats
+
+`unlink/remove` accept:
+- `package`
+- `package:relative/path`
+- repo path: `~/.dotfiles/<pkg>/files/...`
+- target path: e.g. `~/.config/<app>/...`
+
 ## Notes
 
 - Uses `SIGIL_REPO` env var to override the repo path.
 - Conflicts are detected (existing non-symlink files will stop apply).
+- Prefer `sigil add` over manual edits in `files/`.