Folder Index

Maintain a lightweight index at ~/.config/folder-index.json to know where important things are without rescanning.

{
  "folders": [
    {"path": "/Users/alex/projects/webapp", "type": "project", "note": "Main client project"}
  ]
}

When user asks "where is X" or "find my project Y", check the index first. If not found, do targeted discovery then offer to add the result.

Discovery

When asked to find or index folders:

• Scan likely locations: ~/projects, ~/Documents, ~/code, ~/dev, ~/work
• Detect projects by markers: .git, package.json, pubspec.yaml, Cargo.toml, go.mod, pyproject.toml, *.sln
• Stop at first marker (don't recurse into node_modules, vendor, build)
• Propose what was found, don't auto-add: "Found 8 projects in ~/code. Add to index?"

Path Security

• Canonicalize paths (resolve ~, .., symlinks) before any operation
• Reject system paths: /, /etc, /var, /usr, /System, /Library, C:\Windows, C:\Program Files
• Skip symlinks during traversal, report them separately

Destructive Operations

• Use OS trash instead of permanent delete
• State recoverability: "node_modules: recoverable with npm install"
• Build artifacts safe to delete: node_modules, pycache, .gradle, build/, target/, Pods/, .next/

Platform Quirks

• macOS: .DS_Store alone = effectively empty. Treat .app as single item.
• Windows: Paths >260 chars need \\?\ prefix.
• Network drives: Warn before bulk ops — may be slow or offline.