sheldonify 0.1.0

package/skills/sheldonify/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: sheldonify
+description: Use this skill when the user asks to "organize files", "sort files", "clean up a directory", "tidy up a folder", "organize my downloads", "sort my desktop", "group files by type", "find duplicate files", or discusses file/folder organization, directory cleanup, or decluttering. Also use when the user mentions "sheldonify" by name.
+version: 0.1.0
+---
+
+# Sheldonify — File & Folder Organizer
+
+Sheldonify is a CLI tool that organizes files in a directory by type, context, date, or custom rules. It never deletes data — only moves files into organized folders and generates undo scripts.
+
+## Prerequisites
+
+Sheldonify must be installed globally via npm:
+
+```bash
+npm install -g sheldonify
+```
+
+If not installed, offer to install it for the user before proceeding.
+
+## Commands
+
+### Organize by file type (default)
+
+```bash
+sheldonify <directory> --strategy type
+```
+
+Groups files into: `Images/`, `Documents/`, `Code/`, `Videos/`, `Audio/`, `Archives/`, `Fonts/`, `Executables/`, `Data/`, `Design/`, `Other/`, `Misc/`.
+
+### Organize by context/purpose
+
+This is the most powerful strategy — it uses filename heuristics and your LLM capabilities together.
+
+**Step 1:** Scan the directory to get file metadata with heuristic guesses:
+
+```bash
+sheldonify scan <directory> --json
+```
+
+**Step 2:** Read the JSON output. Files with `heuristicGuess: null` or low confidence need your classification. Classify them based on filename patterns, extensions, and context.
+
+**Step 3:** Create a plan JSON file with your classifications:
+
+```json
+{
+  "classifications": [
+    { "file": "relative/path/to/file.ext", "category": "CategoryName", "reason": "why this category" }
+  ]
+}
+```
+
+**Step 4:** Apply the plan:
+
+```bash
+sheldonify apply <directory> --plan plan.json
+```
+
+### Organize by date
+
+```bash
+sheldonify <directory> --strategy date
+```
+
+Groups into `YYYY/MM-MonthName/` folders based on modification date.
+
+### Organize with custom rules
+
+```bash
+sheldonify <directory> --strategy custom --config rules.json
+```
+
+See the references directory for config file format.
+
+## Important Flags
+
+| Flag | Purpose |
+|------|---------|
+| `--dry-run` | Preview changes without executing. **Always use this first.** |
+| `--json` | Structured JSON output — use this for parsing results programmatically |
+| `--depth <n>` | Recursion depth (default: 1, current directory only) |
+| `--config <path>` | Path to a config file |
+| `--verbose` | Detailed logging |
+
+## Workflow
+
+1. **Always start with `--dry-run`** to show the user what will change
+2. Ask the user to confirm before executing
+3. After execution, mention the undo scripts (`_sheldonify-undo.sh` / `_sheldonify-undo.ps1`) and the index file (`_sheldonify-index.json`)
+
+## Safety
+
+- Sheldonify **never deletes files** — it only moves them
+- Every run generates undo scripts (bash + powershell) and a JSON index
+- Protected folders are automatically skipped: `.git`, `node_modules`, `.venv`, project roots with `package.json`/`Cargo.toml`/etc.
+- Duplicate files are moved to `_duplicates/` with metadata, not deleted
+
+## Handling Uncertain Files
+
+When using the context strategy, some files may be flagged as uncertain (confidence < 50%). Present these to the user with the candidate categories and ask which category to use. Then include the user's choice in the classification plan.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Runtime error |
+| 2 | Invalid arguments/config |
+| 3 | Target not found |
+| 4 | Nothing to do (already organized) |

package/skills/sheldonify/references/config-format.md

@@ -0,0 +1,55 @@
+# Sheldonify Config File Format
+
+Place a `sheldonify.config.json` in the target directory, the user's home directory, or pass via `--config`.
+
+## Full Schema
+
+```json
+{
+  "strategy": "type",
+  "depth": 1,
+  "protected": {
+    "useDefaults": true,
+    "include": ["folder-to-skip"],
+    "exclude": ["folder-to-include"]
+  },
+  "typeStrategy": {
+    "extraMappings": { "sketch": "Design", "fig": "Design" },
+    "categoryRenames": { "Code": "Source" }
+  },
+  "contextStrategy": {
+    "extraKeywords": { "Tax-Documents": ["tax", "w2", "1099"] }
+  },
+  "dateStrategy": {
+    "dateSource": "modified"
+  },
+  "customRules": [
+    {
+      "name": "Tax Documents",
+      "match": {
+        "extensions": ["pdf"],
+        "patterns": ["*tax*", "*w2*"],
+        "regex": "tax-\\d{4}"
+      },
+      "priority": 10
+    }
+  ]
+}
+```
+
+## Custom Rules
+
+Rules are evaluated in priority order (highest first). A file matches if any condition in `match` is true:
+
+- `extensions`: Match file extension (without dot, lowercase)
+- `patterns`: Glob patterns matched against filename (case-insensitive)
+- `regex`: Regular expression matched against the relative file path (case-insensitive)
+
+Unmatched files go to `Unsorted/`.
+
+## Protected Folders
+
+When `useDefaults` is true, these are automatically skipped:
+`.git`, `.svn`, `.hg`, `node_modules`, `.venv`, `venv`, `__pycache__`, `.idea`, `.vscode`, `.vs`, `vendor`, `bower_components`, `.terraform`, `.serverless`, `.next`, `.nuxt`, `.svelte-kit`, `_duplicates`, all dotfolders, and any folder containing project markers (`package.json`, `Cargo.toml`, `go.mod`, etc.).
+
+Use `include` to add more patterns to skip, `exclude` to remove patterns from the default list.

package/skills/sheldonify-scan/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: sheldonify-scan
+description: Use this skill when the user asks to "scan files", "analyze a directory for organization", "what's in this folder", or wants to preview how sheldonify would classify files before organizing. Also use when the user wants smart context-based classification that uses LLM judgment.
+version: 0.1.0
+---
+
+# Sheldonify Scan — Intelligent File Analysis
+
+The scan command extracts rich metadata from files and provides heuristic classification guesses. Use this when you need to analyze a directory before organizing, or when the context strategy needs LLM-powered classification.
+
+## Usage
+
+```bash
+sheldonify scan <directory> --json
+```
+
+## Output Format
+
+The scan outputs JSON with file metadata and heuristic guesses:
+
+```json
+{
+  "targetDir": "/path/to/dir",
+  "totalFiles": 42,
+  "files": [
+    {
+      "relativePath": "report.pdf",
+      "name": "report.pdf",
+      "extension": "pdf",
+      "size": 1048576,
+      "modifiedAt": "2026-06-25T10:00:00Z",
+      "createdAt": "2026-01-15T08:30:00Z",
+      "media": null,
+      "heuristicGuess": {
+        "category": "Exports",
+        "confidence": 0.8,
+        "reason": "filename contains \"report\""
+      }
+    },
+    {
+      "relativePath": "data_v2.bin",
+      "name": "data_v2.bin",
+      "extension": "bin",
+      "size": 524288,
+      "modifiedAt": "2026-03-10T14:20:00Z",
+      "createdAt": "2026-03-10T14:20:00Z",
+      "media": null,
+      "heuristicGuess": null
+    }
+  ],
+  "uncertainFiles": [
+    {
+      "file": "data_v2.bin",
+      "candidates": [
+        { "category": "Unsorted", "confidence": 0.1, "reason": "no context signals found" }
+      ]
+    }
+  ]
+}
+```
+
+## Your Role as LLM
+
+1. Read the scan output
+2. For files with `heuristicGuess: null` or low confidence — classify them yourself based on filename, extension, size, dates, and any context the user provides
+3. For files with high-confidence guesses — accept the heuristic or override if you disagree
+4. Build a classification plan and apply it:
+
+```bash
+sheldonify apply <directory> --plan plan.json
+```
+
+Plan format:
+
+```json
+{
+  "classifications": [
+    { "file": "data_v2.bin", "category": "Backups", "reason": "binary data file, likely a backup" },
+    { "file": "report.pdf", "category": "Reports", "reason": "report document" }
+  ]
+}
+```
+
+## When to Use Scan vs Direct
+
+- **Direct** (`sheldonify . --strategy type`): When organizing by type/date — no LLM needed
+- **Scan + Apply**: When using context strategy, or when the user wants you to make smart classification decisions

package/skills/sheldonify-undo/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: sheldonify-undo
+description: Use this skill when the user asks to "undo sheldonify", "reverse file organization", "put files back", "restore original layout", or wants to revert changes made by sheldonify.
+version: 0.1.0
+---
+
+# Sheldonify Undo — Reverse File Organization
+
+Every sheldonify run generates undo scripts that reverse all file moves. Use this skill to help users revert changes.
+
+## Undo Methods
+
+### Bash (Linux/macOS/WSL)
+
+```bash
+cd <organized-directory>
+bash _sheldonify-undo.sh
+```
+
+### PowerShell (Windows)
+
+```powershell
+cd <organized-directory>
+.\_sheldonify-undo.ps1
+```
+
+### Programmatic (using the index)
+
+Read `_sheldonify-index.json` and reverse the operations:
+
+```json
+{
+  "undo": [
+    { "from": "Images/photo.jpg", "to": "photo.jpg" },
+    { "from": "Documents/report.pdf", "to": "report.pdf" }
+  ]
+}
+```
+
+## Important Notes
+
+- Undo scripts reverse operations in LIFO order (last move undone first)
+- Empty directories created by sheldonify are removed during undo
+- If the user ran sheldonify multiple times, each run has its own undo scripts — the latest run's scripts are in the target directory
+- The undo scripts only reverse file moves — they don't delete the `_sheldonify-index.json` or undo scripts themselves. Clean those up manually after undoing.