{"id":"50c17c78-e0e3-4334-bd6b-ba829e55e937","entityType":"agent","slug":"clawhub-jlacroix82-smart-files","name":"smart-files","canonicalUrl":"https://www.xpersona.co/agent/clawhub-jlacroix82-smart-files","canonicalPath":"/agent/clawhub-jlacroix82-smart-files","generatedAt":"2026-10-10T21:48:24.263Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:27:00.361Z","emptyReason":null},"description":"Secure file search, dedup, organize, and rename for workspace files.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.3K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s175p518b8g47fx6r9zyvs95ks876t4t:smart-files","sourceUrl":"https://clawhub.ai/jlacroix82/smart-files","homepage":"https://clawhub.ai/jlacroix82/skills/smart-files","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/jlacroix82/smart-files","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/jlacroix82/skills/smart-files","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":63,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"smart-files technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:27:00.361Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:27:00.361Z","emptyReason":null},"stars":null,"forks":null,"downloads":1339,"packageName":null,"latestVersion":"2.2.3","tractionLabel":"1.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:27:00.360Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T16:27:00.361Z","lastCrawledAt":"2026-10-10T16:27:00.360Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T16:27:00.360Z","lastVerifiedAt":null,"highlights":[{"version":"2.2.3","createdAt":"2026-09-13T12:19:15.086Z","changelog":"- Added VET-REPORT.md for vetting or audit documentation. - Updated permissions in SKILL.md, including new \"env\" permission and simplified declaration format. - Removed skill-card.md from the project. - Updated configuration and documentation for permission alignment and clarity. - Internal code and metadata cleanup to match documentation changes.","fileCount":9,"zipByteSize":17182},{"version":"2.2.2","createdAt":"2026-08-15T20:17:02.515Z","changelog":"smart-files v2.2.2 - Updated documentation for clarity and alignment in SKILL.md and clawhub.yaml. - No functional or behavioral changes; commands, permissions, and security defaults remain the same. - Maintains all previous privacy, security, and safety guidance for users.","fileCount":8,"zipByteSize":17309},{"version":"2.2.1","createdAt":"2026-08-15T20:10:09.560Z","changelog":"Smart Files v2.2.1 - Updated documentation for improved clarity and alignment across README.md, SKILL.md, and clawhub.yaml. - SKILL.md description expanded to clarify core features, safety defaults, and permission requirements. - Permissions section revised and made explicit in all relevant files. - skill-card.md removed as part of documentation cleanup. - No functional changes to core features or commands.","fileCount":8,"zipByteSize":17248},{"version":"99.0.3","createdAt":"2026-08-02T20:01:19.814Z","changelog":"Version 99.0.3 - Updated documentation in SKILL.md and clawhub.yaml for accuracy and alignment. - Removed the redundant skill-card.md file. - No functional changes; documentation and metadata only.","fileCount":8,"zipByteSize":16550},{"version":"99.0.2","createdAt":"2026-08-02T16:46:50.519Z","changelog":"**Content snippet privacy now opt-in by default.** - Content snippets in search results are now hidden by default; use --snippets to show them. --quiet is retained for backward compatibility. - Permissions are now explicitly documented in SKILL.md. - Documentation updated to clarify watch mode, journaling, and permission requirements. - Added test script (test/run-tests.js); removed deprecated skill-card.md file.","fileCount":8,"zipByteSize":16477},{"version":"2.2.0","createdAt":"2026-07-31T20:47:00.496Z","changelog":"v2.2.0: Security audit remediation — search snippets now opt-in (--snippets), --force propagates to watch mode, permissions declared, journal disclosure documented.","fileCount":8,"zipByteSize":16802},{"version":"99.0.1","createdAt":"2026-07-23T01:28:16.154Z","changelog":"v99.0.1: Retag release — same canonical code as v2.1.0, but semver-higher to take over tags.latest. smart-files.js identical. CHANGELOG.txt updated to explain retag.","fileCount":7,"zipByteSize":15129},{"version":"2.1.0","createdAt":"2026-07-23T01:06:51.337Z","changelog":"v2.1.0: Reconciliation release — single canonical version that supersedes the 14+ retry attempts (v1.1.3-v2.0.4, v99.0.0, v3.0.0, v3.0.1, v4.0.0) from the fingerprint-match chaos. Carries the same audited smart-files.js (--force in watch mode, --quiet for content suppression, scoped workspace boundary). Version numbers reconciled: clawhub.yaml and SKILL.md both at 2.1.0. CHANGELOG.txt added to ensure unique fingerprint.","fileCount":7,"zipByteSize":15367}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s175p518b8g47fx6r9zyvs95ks876t4t:smart-files","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s175p518b8g47fx6r9zyvs95ks876t4t:smart-files` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/jlacroix82/smart-files before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jlacroix82-smart-files/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jlacroix82-smart-files/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jlacroix82-smart-files/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jlacroix82-smart-files/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jlacroix82-smart-files/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-jlacroix82-smart-files/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T21:48:24.260Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jlacroix82-smart-files/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jlacroix82-smart-files/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jlacroix82-smart-files/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-jlacroix82-smart-files/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T16:27:00.361Z","emptyReason":null},"readme":"Skill: smart-files\n\nOwner: jlacroix82\n\nSummary: Secure file search, dedup, organize, and rename for workspace files.\n\nTags: latest:2.2.0\n\nVersion history:\n\nv2.2.3 | 2026-09-13T12:19:15.086Z | auto\n\n- Added VET-REPORT.md for vetting or audit documentation.\n- Updated permissions in SKILL.md, including new \"env\" permission and simplified declaration format.\n- Removed skill-card.md from the project.\n- Updated configuration and documentation for permission alignment and clarity.\n- Internal code and metadata cleanup to match documentation changes.\n\nv2.2.2 | 2026-08-15T20:17:02.515Z | auto\n\nsmart-files v2.2.2\n\n- Updated documentation for clarity and alignment in SKILL.md and clawhub.yaml.\n- No functional or behavioral changes; commands, permissions, and security defaults remain the same.\n- Maintains all previous privacy, security, and safety guidance for users.\n\nv2.2.1 | 2026-08-15T20:10:09.560Z | auto\n\nSmart Files v2.2.1\n\n- Updated documentation for improved clarity and alignment across README.md, SKILL.md, and clawhub.yaml.\n- SKILL.md description expanded to clarify core features, safety defaults, and permission requirements.\n- Permissions section revised and made explicit in all relevant files.\n- skill-card.md removed as part of documentation cleanup.\n- No functional changes to core features or commands.\n\nv99.0.3 | 2026-08-02T20:01:19.814Z | auto\n\nVersion 99.0.3\n\n- Updated documentation in SKILL.md and clawhub.yaml for accuracy and alignment.\n- Removed the redundant skill-card.md file.\n- No functional changes; documentation and metadata only.\n\nv99.0.2 | 2026-08-02T16:46:50.519Z | auto\n\n**Content snippet privacy now opt-in by default.**\n\n- Content snippets in search results are now hidden by default; use --snippets to show them. --quiet is retained for backward compatibility.\n- Permissions are now explicitly documented in SKILL.md.\n- Documentation updated to clarify watch mode, journaling, and permission requirements.\n- Added test script (test/run-tests.js); removed deprecated skill-card.md file.\n\nv2.2.0 | 2026-07-31T20:47:00.496Z | user\n\nv2.2.0: Security audit remediation — search snippets now opt-in (--snippets), --force propagates to watch mode, permissions declared, journal disclosure documented.\n\nv99.0.1 | 2026-07-23T01:28:16.154Z | user\n\nv99.0.1: Retag release — same canonical code as v2.1.0, but semver-higher to take over tags.latest. smart-files.js identical. CHANGELOG.txt updated to explain retag.\n\nv2.1.0 | 2026-07-23T01:06:51.337Z | user\n\nv2.1.0: Reconciliation release — single canonical version that supersedes the 14+ retry attempts (v1.1.3-v2.0.4, v99.0.0, v3.0.0, v3.0.1, v4.0.0) from the fingerprint-match chaos. Carries the same audited smart-files.js (--force in watch mode, --quiet for content suppression, scoped workspace boundary). Version numbers reconciled: clawhub.yaml and SKILL.md both at 2.1.0. CHANGELOG.txt added to ensure unique fingerprint.\n\nv1.1.2 | 2026-07-22T17:48:41.694Z | auto\n\n**Changelog for smart-files v1.1.2**\n\n- Added watch mode (`--watch <dir>`) for continuous, ongoing filesystem monitoring with configurable scan interval and persistent change journal (`memory/smart-files-journal.json`).\n- Watch mode now bypasses workspace boundary checks, allowing monitoring of any directory with caution.\n- Expanded SKILL.md documentation to explain watch mode behavior, usage, caveats, and journal management.\n- Removed outdated `skill-card.md` file.\n\nv1.1.1 | 2026-07-21T18:51:23.286Z | auto\n\nSmart Files 1.1.1\n\n- Improved safety and path validation: All operations now default to the workspace root; `--force` is required to override for paths outside.\n- Consolidated documentation: Updated README and SKILL.md for clarity, removed skill-card.md.\n- Simplified feature descriptions: Watch mode and rename actions are more explicitly marked as dry-run/destructive.\n- Operation journal improvements: Persistent journal file for watch mode is now clearly documented.\n- Enhanced security and warnings: Clearer details on potentially destructive operations and explicit directions on when `--force` is required.\n\nv1.0.0 | 2026-07-18T21:40:34.236Z | user\n\nInitial release: 34/34 self-tests, file analysis, code search, type detection, metadata extraction. module.exports for programmatic use. Zero external dependencies.\n\nArchive index:\n\nArchive v2.2.3: 9 files, 17182 bytes\n\nFiles: CHANGELOG.txt (1770b), clawhub.yaml (910b), README.md (11207b), skill-card.md (2369b), SKILL.md (3034b), smart-files.js (24725b), test/run-tests.js (772b), VET-REPORT.md (551b), _meta.json (130b)\n\nFile v2.2.3:SKILL.md\n\n---\nname: smart-files\ndescription: Secure file search, dedup, organize, and rename for workspace files.\nversion: 2.2.3\npermissions:\n  - fs.read_recursive\n  - fs.watch_persist\n  - fs.external_path\n  - env\n---\n\n# Smart Files v2.2.0\n\n> **NOTE: Search mode reads file contents. Content snippets are hidden by default; use `--snippets` to show them.\n\n## Security Audit Remediation (2026-07-22)\n\n### Fix 1: --force flag now reaches watch mode\nBefore: watchDirectory() ignored --force, checked process.argv directly\nAfter: --force is properly passed as fourth parameter to watchDirectory()\n\n### Fix 2: Content snippets now opt-in (default hidden)\nContent snippets are **hidden by default** — only paths and match scores shown. Add `--snippets` to show matched content. `--quiet` is retained for backward compatibility (same effect as default).\n\n### Fix 3: Documentation alignment (remediation)\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features, and declare explicit permissions. Tests remain in the repo under test/ (excluded from the published bundle via .gitignore/clawhub.yaml packaging).\n\n### Fix 4: Documentation alignment\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features.\n\n### Fix 5: Explicit privacy warnings in SKILL.md\nProminent warnings about content exposure risk and safe usage patterns.\n\n### Fix 6: Watch mode boundary documented\nClear documentation that watch mode with --force monitors arbitrary filesystem paths.\n\n### Fix 7: Journal disclosure documented\nClear documentation that watch mode persists file paths, hashes, and timestamps to memory/smart-files-journal.json.\n\n## Commands\n\n- --search <query> [--snippets] — Content-aware search (snippets opt-in with --snippets)\n- --dedup — Duplicate detection by SHA-256\n- --organize — Read-only file categorization\n- --info <file> — File metadata and type detection\n- --cleanup — Read-only cleanup analysis\n- --status — Workspace overview\n- --rename <file> <old:new> [--force] — Rename (dry run by default)\n- --watch <dir> [interval] [--force] — Filesystem monitoring (long-running)\n- --quiet — Keep content snippets hidden (same as default behavior)\n- --force — Override workspace boundary (use with caution)\n\n## Safe Usage Examples\n\n```bash\n# Privacy-safe: only paths shown (default behavior)\nnode smart-files.js --search \"query\"\n\n# Show matched content snippets\nnode smart-files.js --search \"query\" --snippets\n\n# Watch workspace (safe, default behavior)\nnode smart-files.js --watch ./src 30\n\n# Watch external path (use with caution)\nnode smart-files.js --watch /path --force\n```\n\n## Safety Defaults\n\n| Feature | Default | Override |\n|---------|---------|----------|\n| Binary files | Skipped | Cannot override |\n| File size limit | 10MB | Cannot override |\n| Search results cap | 20 | Cannot override |\n| Workspace boundary | Enforced | --force |\n| Watch mode scope | Workspace | --force |\n| Rename mode | Dry run | --force |\n| Content snippets | Hidden (opt-in) | --snippets |\n\nFile v2.2.3:README.md\n\n# Smart Files 📁\n\n**Content-aware file management for OpenClaw agents — search, dedup, organize, rename, and auto-watch your workspace.**\n\n## Why Smart Files?\n\nYour workspace grows fast. Files scatter across directories, duplicates pile up, and finding the right file by name alone is slow. Smart Files solves this:\n\n- **Search by content** — Find files by what's *inside* them, not just their names\n- **Find duplicates** — SHA-256 content hashing catches identical files anywhere\n- **Auto-organize** — Categorize files by type (code, data, docs, media, archives)\n- **File intelligence** — Detect file types, line/word counts, metadata\n- **Auto-watch** — Monitor a directory and organize new files as they appear\n- **Safe by design** — All search/analysis modes are read-only. Watch mode is dry-run by default; `--force` required for any file modification.\n\n---\n\n## Installation\n\n```bash\n# Already included in OpenClaw workspace at skills/smart-files/\n# No npm install needed — pure Node.js\n```\n\n---\n\n## Quick Start\n\n```bash\n# Search by content\nnode skills/smart-files/smart-files.js --search \"api key\"\n\n# Find duplicates\nnode skills/smart-files/smart-files.js --dedup\n\n# Workspace overview\nnode skills/smart-files/smart-files.js --status\n\n# File intelligence\nnode skills/smart-files/smart-files.js --info some-file.js\n\n# Cleanup analysis\nnode skills/smart-files/smart-files.js --cleanup .\n```\n\n---\n\n## Commands Reference\n\n### File Search\n\n```bash\nnode skills/smart-files/smart-files.js --search <query> [--dir <path>]\n```\n\nSearches file **content** (not just filenames) for the query string. Returns ranked results.\n\nContent snippets are **hidden by default** — only paths and match scores are shown:\n\n```\n[smart-files] Found 3 matches for \"api key\":\n  ✅ 1.00 — /path/to/project/config.json\n  🔍 0.75 — /path/to/project/src/auth.js\n```\n\nTo show matched content snippets, add `--snippets`:\n\n```bash\nnode skills/smart-files/smart-files.js --search \"api key\" --snippets\n```\n\n⚠️ **Privacy**: Without `--quiet`, matched content is read from disk into memory. Snippets are **not redacted** — they print raw text as-is. Do not rely on snippet output as a security boundary when scanning directories containing secrets.\n\n---\n\n### Duplicate Detection\n\n```bash\nnode skills/smart-files/smart-files.js --dedup [--dir <path>]\n```\n\nGroups identical files by SHA-256 content hash. Only compares files of the same size (fast filter), then hashes candidates.\n\n```\n[smart-files] Found 2 groups of duplicate files:\n  3 files (1.2 KB) — hash: a1b2c3d4e5f6...\n    → /path/to/file1.txt\n    → /path/to/file2.txt\n    → /path/to/file3.txt\n```\n\n---\n\n### File Organization (read-only)\n\n```bash\nnode skills/smart-files/smart-files.js --organize [--dir <path>]\n```\n\nCategorizes all files by extension. **Read-only** — shows counts per category, never moves files.\n\n- **code** — .js, .ts, .py, .html, .css, .json, .yaml, .yml, .sh, .go, .rs, .c, .cpp, .java, .rb, .md, .txt, and more\n- **data** — .csv, .tsv, .json, .jsonl, .xml, .toml, .ini, .cfg, .env, .sql\n- **docs** — .pdf, .doc, .docx, .rtf, .odt, .tex, .epub\n- **media** — .jpg, .jpeg, .png, .gif, .svg, .webp, .bmp, .mp4, .mov, .mp3, .wav, .flac\n- **archives** — .zip, .tar, .gz, .rar, .7z, .bz2, .xz\n- **images** — .ico, .webp, .avif, .tiff, .psd, .ai, .eps\n\n---\n\n### File Intelligence\n\n```bash\nnode skills/smart-files/smart-files.js --info <filepath>\n```\n\nReturns detected type, size, line count, word count, modification date.\n\n```\n[smart-files] File info: server.js\n  Size: 12.3 KB\n  Type: JavaScript/TypeScript\n  Lines: 345\n  Words: 1,234\n  Modified: 2026-07-15\n  Path: /path/to/server.js\n```\n\n---\n\n### Cleanup Analysis\n\n```bash\nnode skills/smart-files/smart-files.js --cleanup <dir>\n```\n\nScans for:\n- **Temp/backup files** — .tmp, .bak, .swp, .orig, ~files\n- **Large files** (>1MB) — candidates for archiving\n- **Duplicate groups** — files with identical content\n\n---\n\n### Workspace Status\n\n```bash\nnode skills/smart-files/smart-files.js --status [--dir <path>]\n```\n\n```\n[smart-files] Workspace status:\n  Total files: 1,234\n  Total size: 45.2 MB\n  Extensions:\n    .js: 342 files, 12.1 MB\n    .md: 89 files, 2.3 MB\n    .json: 67 files, 8.9 MB\n  Largest files:\n    data.sqlite — 15.2 MB\n    bundle.js — 2.1 MB\n```\n\n---\n\n### Dry-Run Rename\n\n```bash\nnode skills/smart-files/smart-files.js --rename <file> <old>:<new>\n```\n\nPattern-based rename preview. Example:\n```bash\nnode skills/smart-files/smart-files.js --rename server-old.js old:new\n# [smart-files] Would rename: server-old.js → server-new.js\n# [smart-files] (Use --force to actually rename)\n```\n\n---\n\n### Auto-Organize Watcher ⚠️\n\n```bash\n# Dry-run preview (DEFAULT — safe, no files touched)\nnode skills/smart-files/smart-files.js --watch /path/to/dir [--dry-run]\n\n# Actually move/organize files (DESTRUCTIVE — requires explicit --force)\nnode skills/smart-files/smart-files.js --watch /path/to/dir --force\n```\n\n**⚠️ Watch mode is DRY-RUN by default.** It shows what would change without modifying anything. You must use `--force` explicitly to enable destructive operations.\n\nWhen `--force` is used:\n- A 5-second abort window is shown before operations begin\n- Files are **copied** to category subdirectories, then **originals are deleted** (copy+unlink — no atomic move)\n- This is **inherently destructive** — the original inode is destroyed\n- A journal is written to `memory/smart-files-journal.json` for audit trail\n- **There is no automatic rollback** — the journal is for manual recovery only\n- The watcher runs continuously and modifies files as they appear\n\n**Always run `--dry-run` first** to preview what would change before using `--force`.\n\n**Custom rules** via `.smart-files-rules.json` in the watched directory:\n```json\n[\n  { \"exts\": [\".js\", \".ts\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".py\", \".rb\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".jpg\", \".png\"], \"category\": \"Images\" }\n]\n```\n\nDefault rules organize into: Pictures, Documents, Videos, Audio, Code, Uncategorized.\n\n---\n\n## Security & Privacy\n\n⚠️ **Smart Files reads file contents** — search results include content snippets. This means file contents enter terminal output and agent context.\n\n| Protection | Details |\n|------------|---------|\n| **Read-only by default** | `--search`, `--dedup`, `--organize`, `--info`, `--cleanup`, `--status` never modify files |\n| **Content snippets hidden** (opt-in) | Snippets only shown with `--snippets`; paths and scores always displayed |\n| **Binary detection** | Null-byte check + binary extension filter |\n| **Oversized file skip** | Configurable MAX_SCAN_SIZE (10MB default) |\n| **No shell execution** | Pure Node.js `fs` ops — no `child_process` |\n| **Watch safety gate** | Defaults to dry-run; `--force` required for mutations |\n| **Skip directories** | `.git`, `node_modules`, `.npm`, `.cache` excluded by default |\n| **Workspace awareness** | Detects and warns when scanning outside workspace |\n\n### Watch Mode Journal ⚠️\n\nWatch mode persists a journal file to track changes:\n\n- **Location:** `<workspace>/memory/smart-files-journal.json`\n  (override with `SMART_FILES_WORKSPACE` env var)\n- **Contents:** File paths, SHA-256 hashes, sizes, modification times, and change events (new/modified/removed)\n- **Not stored:** File contents — only hashes and metadata\n- **Size limit:** Journal entries capped at 1000; oldest dropped first on overflow\n- **To clear the journal:** Delete `memory/smart-files-journal.json` manually\n- **To disable persistence:** The watcher still scans each interval but does not write to disk if you delete the file before running watch mode (the code will recreate it)\n\n```bash\n# Clear the watch-mode journal\ncp memory/smart-files-journal.json memory/smart-files-journal.backup && > memory/smart-files-journal.json\n\n# Or remove entirely\nrm -f memory/smart-files-journal.json\n```\n\n### What's NOT Protected\n\n- **No snippet redaction**: Snippets print raw file content as-is — no pattern-based filtering occurs.\n- **Content exposure**: When `--snippets` is used, matched content is printed to stdout and may enter agent context. Anyone with terminal access or log access can see them.\n- **Watch-mode journal**: File paths, hashes, sizes, and timestamps are persisted to disk (`memory/smart-files-journal.json`). Delete the file to clear; entries capped at 1000.\n- **No encryption**: File content is not encrypted at rest or in transit. Smart Files is a local file analysis tool, not a secrets vault.\n\n---\n\n## Programmatic API\n\n```javascript\nconst SF = require('./skills/smart-files/smart-files.js');\n\n// Search files — each result includes path, score, and raw content snippet\nconst results = SF.searchFiles('api key', '/path/to/scan');\n\n// Find duplicates\nconst dupGroups = SF.findDuplicates('/path/to/scan');\n\n// Organize (read-only)\nconst organized = SF.organizeFiles('/path/to/scan');\n\n// File info\nconst info = SF.fileInfo('/path/to/file.js');\n\n// Cleanup analysis\nconst analysis = SF.cleanupFiles('/path/to/scan');\n\n// Status\nconst status = SF.showStatus('/path/to/scan');\n\n// Path validation\nconst inWorkspace = SF.isPathWithinWorkspace('/some/path');\n\n// Snippets are raw — no redaction applied\n// Results include: { path, name, size, score, snippet }\n\n// Formatting helpers\nSF.formatBytes(1024);                    // \"1 KB\"\nSF.charToTokens(100);                    // 25\nSF.similarity('hello', 'hello');         // 1\n```\n\n---\n\n## Testing\n\n```bash\n# Run full test suite (34 tests)\nnode skills/smart-files/tests/run-self-tests.js\n\n# Legacy CLI smoke tests\nnode skills/smart-files/test/run-tests.js\n```\n\nTest coverage:\n- Content search (5 cases)\n- Duplicate detection (3 cases)\n- File organization (3 cases)\n- File info (3 cases)\n- Cleanup analysis (3 cases)\n- Workspace status (2 cases)\n- File rename (3 cases)\n- Auto-org watcher functions (2 cases)\n- Security & validation (4 cases)\n- Helper functions (5 cases)\n\n---\n\n## Configuration\n\n| Variable | Description |\n|----------|-------------|\n| `SMART_FILES_WORKSPACE` | Override workspace root directory |\n\nAdjust `MAX_SCAN_SIZE` (10 MB default) at the top of `smart-files.js`:\n```javascript\nconst MAX_SCAN_SIZE = 10 * 1024 * 1024; // 10 MB\n```\n\n---\n\n## Examples\n\n### Find Todos Across Your Project\n```bash\nnode skills/smart-files/smart-files.js --search \"TODO\"\n```\n\n### Clean Up Your Downloads Folder\n```bash\nnode skills/smart-files/smart-files.js --cleanup ~/Downloads\n```\n\n### Preview Watch Mode Before Committing\n```bash\n# Always dry-run first\nnode skills/smart-files/smart-files.js --watch ~/Downloads --dry-run\n\n# Then decide if --force is safe\nnode skills/smart-files/smart-files.js --watch ~/Downloads --force\n```\n\n### Find Large Files Taking Space\n```bash\nnode skills/smart-files/smart-files.js --status ~/projects | grep MB\n```\n\n---\n\n## License\n\nMIT — Part of the OpenClaw skill ecosystem.\n\n---\n\n## Related Skills\n\n- **Secrets Manager** — Secure encrypted storage for secrets\n- **Environment Manager** — Dev environment setup and service tracking\n- **Smart Backup** — Automated backup of important files\n- **Notification Triage** — Stay notified when files change\nRANDOM_UNIQUE_TOKEN_1784758462\n\nFile v2.2.3:_meta.json\n\n{\n  \"ownerId\": \"kn7b6eyf5vc7khg5fr63pjm8xd82qvw5\",\n  \"slug\": \"smart-files\",\n  \"version\": \"2.2.3\",\n  \"publishedAt\": 1789301955086\n}\n\nFile v2.2.3:skill-card.md\n\n## Description:\n\nSecure file search, dedup, organize, and rename for workspace files.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[jlacroix82](https://clawhub.ai/user/jlacroix82)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to inspect workspace files, search file contents, find duplicates, categorize files, preview renames, and monitor file changes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill has broad local file-read and monitoring access, and the security evidence says workspace boundaries and security claims should be reviewed before trusted use.\n\nMitigation: Install only in workspaces where local file reading and monitoring are acceptable, avoid sensitive directories, and review path validation, symlink handling, and scoping before trusted automation.\n\nRisk: Using snippet output can expose raw file contents, including secrets, to terminal logs or agent context.\n\nMitigation: Keep snippets disabled by default and avoid `--snippets` on directories that may contain credentials, private data, or confidential files.\n\nRisk: `--force` can permit external-path access and watch-mode operations that persist file metadata to a journal.\n\nMitigation: Avoid `--force` unless external access is intentional, run dry-run previews first, and clear or protect `memory/smart-files-journal.json` when path and hash metadata is sensitive.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/jlacroix82/skills/smart-files)\n- [README](README.md)\n- [Vetting report](VET-REPORT.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, shell commands, guidance]\n\n**Output Format:** [Plain text CLI output with optional JavaScript object results when used as a module]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Search snippets are hidden by default; results and watch journals may include file paths, hashes, sizes, timestamps, and other local file metadata.]\n\n## Skill Version(s):\n\n2.2.3 (source: server release metadata, SKILL.md frontmatter, clawhub.yaml)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.2.3:VET-REPORT.md\n\n# Vetting Report: smart-files\n**Date:** 2026-09-13 08:11 EDT\n**Vetter:** JARVIS (skill-vetter skill)\n**Source:** local (/home/jarvis/.openclaw/workspace)\n**Verdict:** PASS\n**Risk score:** 8/100\n\n## Findings\n\n### Critical\n- (none)\n\n### Warnings\n- No description in frontmatter\n\n### Notes\n- (none)\n\n## Permission footprint\n- Tools requested: process read \n\n## Network footprint\n\n\n## Side effects\n- Reads: SKILL.md\n- Writes: VET-REPORT.md (this file)\n- Network: 0 distinct hosts\n\n## Verdict rationale\nScore 8/100 with 0 critical findings and 1 warnings.\n\nFile v2.2.3:clawhub.yaml\n\nslug: smart-files\nname: smart-files\nowner: jlacroix82\ndescription: Secure file search, dedup, organize, and rename for workspace files. Content-aware search that reads file contents and can print snippets to stdout. Watch mode provides continuous monitoring with persistent journaling. Uses --quiet mode for content suppression and --force to override workspace boundary.\nversion: 2.2.3\ntype: skill\nauthor: OpenClaw\nlicense: MIT\nkeywords:\n  - files\n  - analysis\n  - search\n  - code\n  - agent\n  - security\n  - privacy\nentry: SKILL.md\ndependencies: []\npermissions:\n  - name: filesystem.read\n    description: Recursively read file contents from workspace for search and dedup operations\n  - name: filesystem.write\n    description: Write file modification journal to memory/smart-files-journal.json\n  - name: env\n    description: Read SMART_FILES_WORKSPACE environment variable\ncapabilities:\n  - filesystem\n  - env\n\nFile v2.2.3:CHANGELOG.txt\n\nSmart Files v2.2.0 — Security Audit Remediation (2026-07-31)\n\nClawHub security audit fixes (3 HIGH findings):\n  - Content snippets now OPT-IN via --snippets; default search output shows\n    only paths + match scores (no content exposure)\n  - --force flag propagates to watch mode; workspace boundary enforced\n    unless --force is explicit\n  - Permissions declared in clawhub.yaml + SKILL.md frontmatter\n    (fs.read_recursive, fs.write, fs.watch_persist, fs.external_path)\n  - README: removed false \"automatic redaction\" claims; documented that\n    snippets are NOT redacted; added watch-mode journal disclosure\n    (location, contents, how to clear)\n  - SKILL.md: added \"Security Audit Remediation\" section + safety defaults\n    table (content snippets hidden by default)\n\nSmart Files v99.0.1 — Retag Release\n\nThis version is functionally identical to v2.1.0 (same smart-files.js source code), \nbut uses a higher semver (v99.0.1 > v99.0.0) to take over the tags.latest slot \non ClawHub. \n\nAfter this publish, the following cleanup is performed via `clawhub delete --version`:\n  - Delete v99.0.0 (the original tags.latest, no longer canonical)\n  - Delete intermediate chaos versions from the fingerprint-match cascade\n\nFinal state will be: 5 clean versions (v1.0.0, v1.1.0, v1.1.1, v1.1.2, v2.1.0, v99.0.1)\nwith tags.latest = v99.0.1 carrying the canonical security-audit-remediated code.\n\nCode is identical to v2.1.0:\n  - --force flag properly propagated in watchDirectory()\n  - --quiet flag for content suppression\n  - Workspace boundary check honored unless --force is explicit\n  - All security audit findings resolved\n\nCHANGELOG.txt itself is the unique-content file that forces a new fingerprint hash,\nallowing the publish to succeed despite identical source.\n\nArchive v2.2.2: 8 files, 17309 bytes\n\nFiles: CHANGELOG.txt (1544b), clawhub.yaml (1510b), README.md (11330b), skill-card.md (2702b), SKILL.md (3960b), smart-files.js (25444b), test/run-tests.js (772b), _meta.json (130b)\n\nFile v2.2.2:SKILL.md\n\n---\nname: smart-files\ndescription: >-\n  Content-aware file management for workspace files: search (content snippets\n  opt-in via --snippets), dedup, organize, rename, file metadata inspection, and\n  continuous watch mode. Watch mode persists a journal (paths/hashes/sizes/\n  timestamps/change events) to memory/smart-files-journal.json and can monitor\n  paths outside the workspace when --force is passed. All file mutations\n  (organize/rename) require --force and are dry-run by default.\nversion: 2.2.2\npermissions:\n  - name: fs.read_recursive\n    description: Read file contents recursively in workspace for --search, --dedup, --info, --cleanup, --status modes\n  - name: fs.write\n    description: Write organize/rename operations (copy+unlink) and persist watch-mode journal to memory/smart-files-journal.json; requires --force for renames outside dry-run\n  - name: fs.watch_persist\n    description: Continuously monitor directory, persist file paths/hashes/timestamps/change events to journal file\n  - name: fs.external_path\n    description: Scan paths outside workspace root when --force is passed (e.g. external directories)\n---\n\n# Smart Files v2.2.2\n\n> **NOTE: Search mode reads file contents. Content snippets are hidden by default; use `--snippets` to show them.\n\n## Security Audit Remediation (2026-07-22)\n\n### Fix 1: --force flag now reaches watch mode\nBefore: watchDirectory() ignored --force, checked process.argv directly\nAfter: --force is properly passed as fourth parameter to watchDirectory()\n\n### Fix 2: Content snippets now opt-in (default hidden)\nContent snippets are **hidden by default** — only paths and match scores shown. Add `--snippets` to show matched content. `--quiet` is retained for backward compatibility (same effect as default).\n\n### Fix 3: Documentation alignment (remediation)\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features, and declare explicit permissions. Tests remain in the repo under test/ (excluded from the published bundle via .gitignore/clawhub.yaml packaging).\n\n### Fix 4: Documentation alignment\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features.\n\n### Fix 5: Explicit privacy warnings in SKILL.md\nProminent warnings about content exposure risk and safe usage patterns.\n\n### Fix 6: Watch mode boundary documented\nClear documentation that watch mode with --force monitors arbitrary filesystem paths.\n\n### Fix 7: Journal disclosure documented\nClear documentation that watch mode persists file paths, hashes, and timestamps to memory/smart-files-journal.json.\n\n## Commands\n\n- --search <query> [--snippets] — Content-aware search (snippets opt-in with --snippets)\n- --dedup — Duplicate detection by SHA-256\n- --organize — Read-only file categorization\n- --info <file> — File metadata and type detection\n- --cleanup — Read-only cleanup analysis\n- --status — Workspace overview\n- --rename <file> <old:new> [--force] — Rename (dry run by default)\n- --watch <dir> [interval] [--force] — Filesystem monitoring (long-running)\n- --quiet — Keep content snippets hidden (same as default behavior)\n- --force — Override workspace boundary (use with caution)\n\n## Safe Usage Examples\n\n```bash\n# Privacy-safe: only paths shown (default behavior)\nnode smart-files.js --search \"query\"\n\n# Show matched content snippets\nnode smart-files.js --search \"query\" --snippets\n\n# Watch workspace (safe, default behavior)\nnode smart-files.js --watch ./src 30\n\n# Watch external path (use with caution)\nnode smart-files.js --watch /path --force\n```\n\n## Safety Defaults\n\n| Feature | Default | Override |\n|---------|---------|----------|\n| Binary files | Skipped | Cannot override |\n| File size limit | 10MB | Cannot override |\n| Search results cap | 20 | Cannot override |\n| Workspace boundary | Enforced | --force |\n| Watch mode scope | Workspace | --force |\n| Rename mode | Dry run | --force |\n| Content snippets | Hidden (opt-in) | --snippets |\n\nFile v2.2.2:README.md\n\n# Smart Files 📁\n\n**Content-aware file management for OpenClaw agents — search, dedup, organize, rename, and auto-watch your workspace.**\n\n## Why Smart Files?\n\nYour workspace grows fast. Files scatter across directories, duplicates pile up, and finding the right file by name alone is slow. Smart Files solves this:\n\n- **Search by content** — Find files by what's *inside* them, not just their names\n- **Find duplicates** — SHA-256 content hashing catches identical files anywhere\n- **Auto-organize** — Categorize files by type (code, data, docs, media, archives)\n- **File intelligence** — Detect file types, line/word counts, metadata\n- **Auto-watch** — Monitor a directory and organize new files as they appear\n- **Safe by design** — All search/analysis modes are read-only. Watch mode is dry-run by default; `--force` required for any file modification.\n\n---\n\n## Installation\n\n```bash\n# Already included in OpenClaw workspace at skills/smart-files/\n# No npm install needed — pure Node.js\n```\n\n---\n\n## Quick Start\n\n```bash\n# Search by content\nnode skills/smart-files/smart-files.js --search \"api key\"\n\n# Find duplicates\nnode skills/smart-files/smart-files.js --dedup\n\n# Workspace overview\nnode skills/smart-files/smart-files.js --status\n\n# File intelligence\nnode skills/smart-files/smart-files.js --info some-file.js\n\n# Cleanup analysis\nnode skills/smart-files/smart-files.js --cleanup .\n```\n\n---\n\n## Commands Reference\n\n### File Search\n\n```bash\nnode skills/smart-files/smart-files.js --search <query> [--dir <path>]\n```\n\nSearches file **content** (not just filenames) for the query string. Returns ranked results.\n\nContent snippets are **hidden by default** — only paths and match scores are shown:\n\n```\n[smart-files] Found 3 matches for \"api key\":\n  ✅ 1.00 — /path/to/project/config.json\n  🔍 0.75 — /path/to/project/src/auth.js\n```\n\nTo show matched content snippets, add `--snippets`:\n\n```bash\nnode skills/smart-files/smart-files.js --search \"api key\" --snippets\n```\n\n⚠️ **Privacy**: Without `--quiet`, matched content is read from disk into memory. Snippets are **not redacted** — they print raw text as-is. Do not rely on snippet output as a security boundary when scanning directories containing secrets.\n\n---\n\n### Duplicate Detection\n\n```bash\nnode skills/smart-files/smart-files.js --dedup [--dir <path>]\n```\n\nGroups identical files by SHA-256 content hash. Only compares files of the same size (fast filter), then hashes candidates.\n\n```\n[smart-files] Found 2 groups of duplicate files:\n  3 files (1.2 KB) — hash: a1b2c3d4e5f6...\n    → /path/to/file1.txt\n    → /path/to/file2.txt\n    → /path/to/file3.txt\n```\n\n---\n\n### File Organization (read-only)\n\n```bash\nnode skills/smart-files/smart-files.js --organize [--dir <path>]\n```\n\nCategorizes all files by extension. **Read-only** — shows counts per category, never moves files.\n\n- **code** — .js, .ts, .py, .html, .css, .json, .yaml, .yml, .sh, .go, .rs, .c, .cpp, .java, .rb, .md, .txt, and more\n- **data** — .csv, .tsv, .json, .jsonl, .xml, .toml, .ini, .cfg, .env, .sql\n- **docs** — .pdf, .doc, .docx, .rtf, .odt, .tex, .epub\n- **media** — .jpg, .jpeg, .png, .gif, .svg, .webp, .bmp, .mp4, .mov, .mp3, .wav, .flac\n- **archives** — .zip, .tar, .gz, .rar, .7z, .bz2, .xz\n- **images** — .ico, .webp, .avif, .tiff, .psd, .ai, .eps\n\n---\n\n### File Intelligence\n\n```bash\nnode skills/smart-files/smart-files.js --info <filepath>\n```\n\nReturns detected type, size, line count, word count, modification date.\n\n```\n[smart-files] File info: server.js\n  Size: 12.3 KB\n  Type: JavaScript/TypeScript\n  Lines: 345\n  Words: 1,234\n  Modified: 2026-07-15\n  Path: /path/to/server.js\n```\n\n---\n\n### Cleanup Analysis\n\n```bash\nnode skills/smart-files/smart-files.js --cleanup <dir>\n```\n\nScans for:\n- **Temp/backup files** — .tmp, .bak, .swp, .orig, ~files\n- **Large files** (>1MB) — candidates for archiving\n- **Duplicate groups** — files with identical content\n\n---\n\n### Workspace Status\n\n```bash\nnode skills/smart-files/smart-files.js --status [--dir <path>]\n```\n\n```\n[smart-files] Workspace status:\n  Total files: 1,234\n  Total size: 45.2 MB\n  Extensions:\n    .js: 342 files, 12.1 MB\n    .md: 89 files, 2.3 MB\n    .json: 67 files, 8.9 MB\n  Largest files:\n    data.sqlite — 15.2 MB\n    bundle.js — 2.1 MB\n```\n\n---\n\n### Dry-Run Rename\n\n```bash\nnode skills/smart-files/smart-files.js --rename <file> <old>:<new>\n```\n\nPattern-based rename preview. Example:\n```bash\nnode skills/smart-files/smart-files.js --rename server-old.js old:new\n# [smart-files] Would rename: server-old.js → server-new.js\n# [smart-files] (Use --force to actually rename)\n```\n\n---\n\n### Auto-Organize Watcher ⚠️\n\n```bash\n# Dry-run preview (DEFAULT — safe, no files touched)\nnode skills/smart-files/smart-files.js --watch /path/to/dir [--dry-run]\n\n# Actually move/organize files (DESTRUCTIVE — requires explicit --force)\nnode skills/smart-files/smart-files.js --watch /path/to/dir --force\n```\n\n**⚠️ Watch mode is DRY-RUN by default.** It shows what would change without modifying anything. You must use `--force` explicitly to enable destructive operations.\n\nWhen `--force` is used:\n- A 5-second abort window is shown before operations begin\n- Files are **copied** to category subdirectories, then **originals are deleted** (copy+unlink — no atomic move)\n- This is **inherently destructive** — the original inode is destroyed\n- A journal is written to `memory/smart-files-journal.json` for audit trail\n- **There is no automatic rollback** — the journal is for manual recovery only\n- The watcher runs continuously and modifies files as they appear\n\n**Always run `--dry-run` first** to preview what would change before using `--force`.\n\n**Custom rules** via `.smart-files-rules.json` in the watched directory:\n```json\n[\n  { \"exts\": [\".js\", \".ts\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".py\", \".rb\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".jpg\", \".png\"], \"category\": \"Images\" }\n]\n```\n\nDefault rules organize into: Pictures, Documents, Videos, Audio, Code, Uncategorized.\n\n---\n\n## Security & Privacy\n\n⚠️ **Smart Files reads file contents** — search results include content snippets. This means file contents enter terminal output and agent context.\n\n| Protection | Details |\n|------------|---------|\n| **Read-only by default** | `--search`, `--dedup`, `--organize`, `--info`, `--cleanup`, `--status` never modify files |\n| **Content snippets hidden** (opt-in) | Snippets only shown with `--snippets`; paths and scores always displayed |\n| **Binary detection** | Null-byte check + binary extension filter |\n| **Oversized file skip** | Configurable MAX_SCAN_SIZE (10MB default) |\n| **No shell execution** | Pure Node.js `fs` ops — no `child_process` |\n| **Watch safety gate** | Defaults to dry-run; `--force` required for mutations |\n| **Skip directories** | `.git`, `node_modules`, `.npm`, `.cache` excluded by default |\n| **Workspace awareness** | Detects and warns when scanning outside workspace |\n\n### Watch Mode Journal ⚠️\n\nWatch mode persists a journal file to track changes:\n\n- **Location:** `<workspace>/memory/smart-files-journal.json`\n  (override with `SMART_FILES_WORKSPACE` env var)\n- **Contents:** File paths, SHA-256 hashes, sizes, modification times, and change events (new/modified/removed)\n- **Not stored:** File contents — only hashes and metadata\n- **Size limit:** Journal entries capped at 1000; oldest dropped first on overflow\n- **To clear the journal:** Delete `memory/smart-files-journal.json` manually\n- **To disable persistence:** Watch mode always persists change events to the journal (that is its purpose). Deleting the file clears history, but the next change event recreates it. If you need zero disk writes, do not use watch mode — use one-shot commands (`--search`, `--status`) instead.\n\n```bash\n# Clear the watch-mode journal\ncp memory/smart-files-journal.json memory/smart-files-journal.backup && > memory/smart-files-journal.json\n\n# Or remove entirely\nrm -f memory/smart-files-journal.json\n```\n\n### What's NOT Protected\n\n- **No snippet redaction**: Snippets print raw file content as-is — no pattern-based filtering occurs.\n- **Content exposure**: When `--snippets` is used, matched content is printed to stdout and may enter agent context. Anyone with terminal access or log access can see them.\n- **Watch-mode journal**: File paths, hashes, sizes, and timestamps are persisted to disk (`memory/smart-files-journal.json`). Delete the file to clear; entries capped at 1000.\n- **No encryption**: File content is not encrypted at rest or in transit. Smart Files is a local file analysis tool, not a secrets vault.\n\n---\n\n## Programmatic API\n\n```javascript\nconst SF = require('./skills/smart-files/smart-files.js');\n\n// Search files — each result includes path, score, and raw content snippet\nconst results = SF.searchFiles('api key', '/path/to/scan');\n\n// Find duplicates\nconst dupGroups = SF.findDuplicates('/path/to/scan');\n\n// Organize (read-only)\nconst organized = SF.organizeFiles('/path/to/scan');\n\n// File info\nconst info = SF.fileInfo('/path/to/file.js');\n\n// Cleanup analysis\nconst analysis = SF.cleanupFiles('/path/to/scan');\n\n// Status\nconst status = SF.showStatus('/path/to/scan');\n\n// Path validation\nconst inWorkspace = SF.isPathWithinWorkspace('/some/path');\n\n// Snippets are raw — no redaction applied\n// Results include: { path, name, size, score, snippet }\n\n// Formatting helpers\nSF.formatBytes(1024);                    // \"1 KB\"\nSF.charToTokens(100);                    // 25\nSF.similarity('hello', 'hello');         // 1\n```\n\n---\n\n## Testing\n\n```bash\n# Run full test suite (34 tests)\nnode skills/smart-files/tests/run-self-tests.js\n\n# Legacy CLI smoke tests\nnode skills/smart-files/test/run-tests.js\n```\n\nTest coverage:\n- Content search (5 cases)\n- Duplicate detection (3 cases)\n- File organization (3 cases)\n- File info (3 cases)\n- Cleanup analysis (3 cases)\n- Workspace status (2 cases)\n- File rename (3 cases)\n- Auto-org watcher functions (2 cases)\n- Security & validation (4 cases)\n- Helper functions (5 cases)\n\n---\n\n## Configuration\n\n| Variable | Description |\n|----------|-------------|\n| `SMART_FILES_WORKSPACE` | Override workspace root directory |\n\nAdjust `MAX_SCAN_SIZE` (10 MB default) at the top of `smart-files.js`:\n```javascript\nconst MAX_SCAN_SIZE = 10 * 1024 * 1024; // 10 MB\n```\n\n---\n\n## Examples\n\n### Find Todos Across Your Project\n```bash\nnode skills/smart-files/smart-files.js --search \"TODO\"\n```\n\n### Clean Up Your Downloads Folder\n```bash\nnode skills/smart-files/smart-files.js --cleanup ~/Downloads\n```\n\n### Preview Watch Mode Before Committing\n```bash\n# Always dry-run first\nnode skills/smart-files/smart-files.js --watch ~/Downloads --dry-run\n\n# Then decide if --force is safe\nnode skills/smart-files/smart-files.js --watch ~/Downloads --force\n```\n\n### Find Large Files Taking Space\n```bash\nnode skills/smart-files/smart-files.js --status ~/projects | grep MB\n```\n\n---\n\n## License\n\nMIT — Part of the OpenClaw skill ecosystem.\n\n---\n\n## Related Skills\n\n- **Secrets Manager** — Secure encrypted storage for secrets\n- **Environment Manager** — Dev environment setup and service tracking\n- **Smart Backup** — Automated backup of important files\n- **Notification Triage** — Stay notified when files change\nRANDOM_UNIQUE_TOKEN_1784758462\n\nFile v2.2.2:_meta.json\n\n{\n  \"ownerId\": \"kn7b6eyf5vc7khg5fr63pjm8xd82qvw5\",\n  \"slug\": \"smart-files\",\n  \"version\": \"2.2.2\",\n  \"publishedAt\": 1786825022515\n}\n\nFile v2.2.2:skill-card.md\n\n## Description:\n\nSmart Files provides content-aware workspace file management, including content search with opt-in snippets, duplicate detection, read-only organization and cleanup analysis, file metadata inspection, dry-run rename, and watch-mode journaling.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[jlacroix82](https://clawhub.ai/user/jlacroix82)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agent operators use Smart Files to inspect workspace contents, search file text, find duplicates, understand file metadata, and preview organization or cleanup actions before enabling any forced mutation.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Recursive file reading and optional snippets can expose sensitive workspace content in terminal output or agent context.\n\nMitigation: Keep snippets disabled by default, scan only intended workspaces, and avoid running searches over directories that contain secrets unless raw matches may be shown.\n\nRisk: Watch mode records file paths, hashes, sizes, timestamps, and change events to a persistent journal.\n\nMitigation: Use one-shot commands when no disk writes are acceptable, restrict watched paths, and clear memory/smart-files-journal.json when the journal is no longer needed.\n\nRisk: --force and workspace environment overrides can expand scans beyond the current workspace and may affect sensitive external paths.\n\nMitigation: Avoid --force and SMART_FILES_WORKSPACE overrides on sensitive directories unless external scanning is intentional and reviewed.\n\nRisk: Mutation and watch behavior may not fully match the documentation according to the security guidance.\n\nMitigation: Verify behavior in a disposable workspace before relying on rename, organize, or watch mode for operational file changes.\n\n## Reference(s):\n\n- [ClawHub smart-files release page](https://clawhub.ai/jlacroix82/skills/smart-files)\n- [README.md](artifact/README.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline shell commands and local CLI text output]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Search snippets are hidden unless --snippets is used; watch mode persists file metadata journal entries.]\n\n## Skill Version(s):\n\n2.2.2 (source: evidence.release.version and SKILL.md frontmatter)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.2.2:clawhub.yaml\n\nslug: smart-files\nname: smart-files\nowner: jlacroix82\ndescription: >-\n  Content-aware file management for workspace files: search (content snippets\n  opt-in via --snippets), dedup, organize, rename, file metadata inspection, and\n  continuous watch mode. Watch mode persists a journal (paths/hashes/sizes/\n  timestamps/change events) to memory/smart-files-journal.json and can monitor\n  paths outside the workspace when --force is passed. All file mutations\n  (organize/rename) require --force and are dry-run by default.\nversion: 2.2.2\ntype: skill\nauthor: OpenClaw\nlicense: MIT\nkeywords:\n  - files\n  - analysis\n  - search\n  - code\n  - agent\n  - security\n  - privacy\nentry: SKILL.md\ndependencies: []\npermissions:\n  - name: filesystem.read\n    description: Recursively read file contents from workspace for search, dedup, info, cleanup, and status operations\n  - name: filesystem.write\n    description: Persist watch-mode journal to memory/smart-files-journal.json; organize/rename modify files via copy+unlink (requires --force outside dry-run)\n  - name: filesystem.watch\n    description: Continuously monitor a directory and persist file paths/hashes/sizes/timestamps/change events to the journal\n  - name: filesystem.external_path\n    description: Scan paths outside the workspace root when --force is passed (explicit opt-in per invocation)\n  - name: environment.read\n    description: Read SMART_FILES_WORKSPACE environment variable to override the workspace root\ncapabilities:\n  - filesystem\n  - environment\n\nFile v2.2.2:CHANGELOG.txt\n\nSmart Files v2.2.0 — Security Audit Remediation (2026-07-31)\n\nClawHub security audit fixes (3 HIGH findings):\n  - Content snippets now OPT-IN via --snippets; default search output shows\n    only paths + match scores (no content exposure)\n  - --force flag propagates to watch mode; workspace boundary enforced\n    unless --force is explicit\n  - Permissions declared in clawhub.yaml + SKILL.md frontmatter\n    (fs.read_recursive, fs.write, fs.watch_persist, fs.external_path)\n  - README: removed false \"automatic redaction\" claims; documented that\n    snippets are NOT redacted; added watch-mode journal disclosure\n    (location, contents, how to clear)\n  - SKILL.md: added \"Security Audit Remediation\" section + safety defaults\n    table (content snippets hidden by default)\n\nSmart Files v99.0.2 — Canonical Clean Release (2026-08-02)\n\nThis version carries the security-audit-remediated source code (v2.2.0) and\nreclaims the tags.latest slot above the prior v99.0.1 retag artifact.\n\nIncludes all v2.2.0 Security Audit Remediation (3 HIGH findings resolved):\n  - Content snippets OPT-IN via --snippets; default output shows only paths +\n    match scores (no content exposure)\n  - --force flag propagates to watch mode; workspace boundary enforced unless\n    --force is explicit\n  - Permissions declared in clawhub.yaml + SKILL.md frontmatter\n    (fs.read_recursive, fs.write, fs.watch_persist, fs.external_path)\n  - README/SKILL.md document that snippets are NOT redacted; watch-mode journal\n    disclosure (location, contents, how to clear)\n\nArchive v2.2.1: 8 files, 17248 bytes\n\nFiles: CHANGELOG.txt (1544b), clawhub.yaml (1361b), README.md (11330b), skill-card.md (2688b), SKILL.md (3960b), smart-files.js (25444b), test/run-tests.js (772b), _meta.json (130b)\n\nFile v2.2.1:SKILL.md\n\n---\nname: smart-files\ndescription: >-\n  Content-aware file management for workspace files: search (content snippets\n  opt-in via --snippets), dedup, organize, rename, file metadata inspection, and\n  continuous watch mode. Watch mode persists a journal (paths/hashes/sizes/\n  timestamps/change events) to memory/smart-files-journal.json and can monitor\n  paths outside the workspace when --force is passed. All file mutations\n  (organize/rename) require --force and are dry-run by default.\nversion: 2.2.1\npermissions:\n  - name: fs.read_recursive\n    description: Read file contents recursively in workspace for --search, --dedup, --info, --cleanup, --status modes\n  - name: fs.write\n    description: Write organize/rename operations (copy+unlink) and persist watch-mode journal to memory/smart-files-journal.json; requires --force for renames outside dry-run\n  - name: fs.watch_persist\n    description: Continuously monitor directory, persist file paths/hashes/timestamps/change events to journal file\n  - name: fs.external_path\n    description: Scan paths outside workspace root when --force is passed (e.g. external directories)\n---\n\n# Smart Files v2.2.0\n\n> **NOTE: Search mode reads file contents. Content snippets are hidden by default; use `--snippets` to show them.\n\n## Security Audit Remediation (2026-07-22)\n\n### Fix 1: --force flag now reaches watch mode\nBefore: watchDirectory() ignored --force, checked process.argv directly\nAfter: --force is properly passed as fourth parameter to watchDirectory()\n\n### Fix 2: Content snippets now opt-in (default hidden)\nContent snippets are **hidden by default** — only paths and match scores shown. Add `--snippets` to show matched content. `--quiet` is retained for backward compatibility (same effect as default).\n\n### Fix 3: Documentation alignment (remediation)\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features, and declare explicit permissions. Tests remain in the repo under test/ (excluded from the published bundle via .gitignore/clawhub.yaml packaging).\n\n### Fix 4: Documentation alignment\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features.\n\n### Fix 5: Explicit privacy warnings in SKILL.md\nProminent warnings about content exposure risk and safe usage patterns.\n\n### Fix 6: Watch mode boundary documented\nClear documentation that watch mode with --force monitors arbitrary filesystem paths.\n\n### Fix 7: Journal disclosure documented\nClear documentation that watch mode persists file paths, hashes, and timestamps to memory/smart-files-journal.json.\n\n## Commands\n\n- --search <query> [--snippets] — Content-aware search (snippets opt-in with --snippets)\n- --dedup — Duplicate detection by SHA-256\n- --organize — Read-only file categorization\n- --info <file> — File metadata and type detection\n- --cleanup — Read-only cleanup analysis\n- --status — Workspace overview\n- --rename <file> <old:new> [--force] — Rename (dry run by default)\n- --watch <dir> [interval] [--force] — Filesystem monitoring (long-running)\n- --quiet — Keep content snippets hidden (same as default behavior)\n- --force — Override workspace boundary (use with caution)\n\n## Safe Usage Examples\n\n```bash\n# Privacy-safe: only paths shown (default behavior)\nnode smart-files.js --search \"query\"\n\n# Show matched content snippets\nnode smart-files.js --search \"query\" --snippets\n\n# Watch workspace (safe, default behavior)\nnode smart-files.js --watch ./src 30\n\n# Watch external path (use with caution)\nnode smart-files.js --watch /path --force\n```\n\n## Safety Defaults\n\n| Feature | Default | Override |\n|---------|---------|----------|\n| Binary files | Skipped | Cannot override |\n| File size limit | 10MB | Cannot override |\n| Search results cap | 20 | Cannot override |\n| Workspace boundary | Enforced | --force |\n| Watch mode scope | Workspace | --force |\n| Rename mode | Dry run | --force |\n| Content snippets | Hidden (opt-in) | --snippets |\n\nFile v2.2.1:README.md\n\n# Smart Files 📁\n\n**Content-aware file management for OpenClaw agents — search, dedup, organize, rename, and auto-watch your workspace.**\n\n## Why Smart Files?\n\nYour workspace grows fast. Files scatter across directories, duplicates pile up, and finding the right file by name alone is slow. Smart Files solves this:\n\n- **Search by content** — Find files by what's *inside* them, not just their names\n- **Find duplicates** — SHA-256 content hashing catches identical files anywhere\n- **Auto-organize** — Categorize files by type (code, data, docs, media, archives)\n- **File intelligence** — Detect file types, line/word counts, metadata\n- **Auto-watch** — Monitor a directory and organize new files as they appear\n- **Safe by design** — All search/analysis modes are read-only. Watch mode is dry-run by default; `--force` required for any file modification.\n\n---\n\n## Installation\n\n```bash\n# Already included in OpenClaw workspace at skills/smart-files/\n# No npm install needed — pure Node.js\n```\n\n---\n\n## Quick Start\n\n```bash\n# Search by content\nnode skills/smart-files/smart-files.js --search \"api key\"\n\n# Find duplicates\nnode skills/smart-files/smart-files.js --dedup\n\n# Workspace overview\nnode skills/smart-files/smart-files.js --status\n\n# File intelligence\nnode skills/smart-files/smart-files.js --info some-file.js\n\n# Cleanup analysis\nnode skills/smart-files/smart-files.js --cleanup .\n```\n\n---\n\n## Commands Reference\n\n### File Search\n\n```bash\nnode skills/smart-files/smart-files.js --search <query> [--dir <path>]\n```\n\nSearches file **content** (not just filenames) for the query string. Returns ranked results.\n\nContent snippets are **hidden by default** — only paths and match scores are shown:\n\n```\n[smart-files] Found 3 matches for \"api key\":\n  ✅ 1.00 — /path/to/project/config.json\n  🔍 0.75 — /path/to/project/src/auth.js\n```\n\nTo show matched content snippets, add `--snippets`:\n\n```bash\nnode skills/smart-files/smart-files.js --search \"api key\" --snippets\n```\n\n⚠️ **Privacy**: Without `--quiet`, matched content is read from disk into memory. Snippets are **not redacted** — they print raw text as-is. Do not rely on snippet output as a security boundary when scanning directories containing secrets.\n\n---\n\n### Duplicate Detection\n\n```bash\nnode skills/smart-files/smart-files.js --dedup [--dir <path>]\n```\n\nGroups identical files by SHA-256 content hash. Only compares files of the same size (fast filter), then hashes candidates.\n\n```\n[smart-files] Found 2 groups of duplicate files:\n  3 files (1.2 KB) — hash: a1b2c3d4e5f6...\n    → /path/to/file1.txt\n    → /path/to/file2.txt\n    → /path/to/file3.txt\n```\n\n---\n\n### File Organization (read-only)\n\n```bash\nnode skills/smart-files/smart-files.js --organize [--dir <path>]\n```\n\nCategorizes all files by extension. **Read-only** — shows counts per category, never moves files.\n\n- **code** — .js, .ts, .py, .html, .css, .json, .yaml, .yml, .sh, .go, .rs, .c, .cpp, .java, .rb, .md, .txt, and more\n- **data** — .csv, .tsv, .json, .jsonl, .xml, .toml, .ini, .cfg, .env, .sql\n- **docs** — .pdf, .doc, .docx, .rtf, .odt, .tex, .epub\n- **media** — .jpg, .jpeg, .png, .gif, .svg, .webp, .bmp, .mp4, .mov, .mp3, .wav, .flac\n- **archives** — .zip, .tar, .gz, .rar, .7z, .bz2, .xz\n- **images** — .ico, .webp, .avif, .tiff, .psd, .ai, .eps\n\n---\n\n### File Intelligence\n\n```bash\nnode skills/smart-files/smart-files.js --info <filepath>\n```\n\nReturns detected type, size, line count, word count, modification date.\n\n```\n[smart-files] File info: server.js\n  Size: 12.3 KB\n  Type: JavaScript/TypeScript\n  Lines: 345\n  Words: 1,234\n  Modified: 2026-07-15\n  Path: /path/to/server.js\n```\n\n---\n\n### Cleanup Analysis\n\n```bash\nnode skills/smart-files/smart-files.js --cleanup <dir>\n```\n\nScans for:\n- **Temp/backup files** — .tmp, .bak, .swp, .orig, ~files\n- **Large files** (>1MB) — candidates for archiving\n- **Duplicate groups** — files with identical content\n\n---\n\n### Workspace Status\n\n```bash\nnode skills/smart-files/smart-files.js --status [--dir <path>]\n```\n\n```\n[smart-files] Workspace status:\n  Total files: 1,234\n  Total size: 45.2 MB\n  Extensions:\n    .js: 342 files, 12.1 MB\n    .md: 89 files, 2.3 MB\n    .json: 67 files, 8.9 MB\n  Largest files:\n    data.sqlite — 15.2 MB\n    bundle.js — 2.1 MB\n```\n\n---\n\n### Dry-Run Rename\n\n```bash\nnode skills/smart-files/smart-files.js --rename <file> <old>:<new>\n```\n\nPattern-based rename preview. Example:\n```bash\nnode skills/smart-files/smart-files.js --rename server-old.js old:new\n# [smart-files] Would rename: server-old.js → server-new.js\n# [smart-files] (Use --force to actually rename)\n```\n\n---\n\n### Auto-Organize Watcher ⚠️\n\n```bash\n# Dry-run preview (DEFAULT — safe, no files touched)\nnode skills/smart-files/smart-files.js --watch /path/to/dir [--dry-run]\n\n# Actually move/organize files (DESTRUCTIVE — requires explicit --force)\nnode skills/smart-files/smart-files.js --watch /path/to/dir --force\n```\n\n**⚠️ Watch mode is DRY-RUN by default.** It shows what would change without modifying anything. You must use `--force` explicitly to enable destructive operations.\n\nWhen `--force` is used:\n- A 5-second abort window is shown before operations begin\n- Files are **copied** to category subdirectories, then **originals are deleted** (copy+unlink — no atomic move)\n- This is **inherently destructive** — the original inode is destroyed\n- A journal is written to `memory/smart-files-journal.json` for audit trail\n- **There is no automatic rollback** — the journal is for manual recovery only\n- The watcher runs continuously and modifies files as they appear\n\n**Always run `--dry-run` first** to preview what would change before using `--force`.\n\n**Custom rules** via `.smart-files-rules.json` in the watched directory:\n```json\n[\n  { \"exts\": [\".js\", \".ts\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".py\", \".rb\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".jpg\", \".png\"], \"category\": \"Images\" }\n]\n```\n\nDefault rules organize into: Pictures, Documents, Videos, Audio, Code, Uncategorized.\n\n---\n\n## Security & Privacy\n\n⚠️ **Smart Files reads file contents** — search results include content snippets. This means file contents enter terminal output and agent context.\n\n| Protection | Details |\n|------------|---------|\n| **Read-only by default** | `--search`, `--dedup`, `--organize`, `--info`, `--cleanup`, `--status` never modify files |\n| **Content snippets hidden** (opt-in) | Snippets only shown with `--snippets`; paths and scores always displayed |\n| **Binary detection** | Null-byte check + binary extension filter |\n| **Oversized file skip** | Configurable MAX_SCAN_SIZE (10MB default) |\n| **No shell execution** | Pure Node.js `fs` ops — no `child_process` |\n| **Watch safety gate** | Defaults to dry-run; `--force` required for mutations |\n| **Skip directories** | `.git`, `node_modules`, `.npm`, `.cache` excluded by default |\n| **Workspace awareness** | Detects and warns when scanning outside workspace |\n\n### Watch Mode Journal ⚠️\n\nWatch mode persists a journal file to track changes:\n\n- **Location:** `<workspace>/memory/smart-files-journal.json`\n  (override with `SMART_FILES_WORKSPACE` env var)\n- **Contents:** File paths, SHA-256 hashes, sizes, modification times, and change events (new/modified/removed)\n- **Not stored:** File contents — only hashes and metadata\n- **Size limit:** Journal entries capped at 1000; oldest dropped first on overflow\n- **To clear the journal:** Delete `memory/smart-files-journal.json` manually\n- **To disable persistence:** Watch mode always persists change events to the journal (that is its purpose). Deleting the file clears history, but the next change event recreates it. If you need zero disk writes, do not use watch mode — use one-shot commands (`--search`, `--status`) instead.\n\n```bash\n# Clear the watch-mode journal\ncp memory/smart-files-journal.json memory/smart-files-journal.backup && > memory/smart-files-journal.json\n\n# Or remove entirely\nrm -f memory/smart-files-journal.json\n```\n\n### What's NOT Protected\n\n- **No snippet redaction**: Snippets print raw file content as-is — no pattern-based filtering occurs.\n- **Content exposure**: When `--snippets` is used, matched content is printed to stdout and may enter agent context. Anyone with terminal access or log access can see them.\n- **Watch-mode journal**: File paths, hashes, sizes, and timestamps are persisted to disk (`memory/smart-files-journal.json`). Delete the file to clear; entries capped at 1000.\n- **No encryption**: File content is not encrypted at rest or in transit. Smart Files is a local file analysis tool, not a secrets vault.\n\n---\n\n## Programmatic API\n\n```javascript\nconst SF = require('./skills/smart-files/smart-files.js');\n\n// Search files — each result includes path, score, and raw content snippet\nconst results = SF.searchFiles('api key', '/path/to/scan');\n\n// Find duplicates\nconst dupGroups = SF.findDuplicates('/path/to/scan');\n\n// Organize (read-only)\nconst organized = SF.organizeFiles('/path/to/scan');\n\n// File info\nconst info = SF.fileInfo('/path/to/file.js');\n\n// Cleanup analysis\nconst analysis = SF.cleanupFiles('/path/to/scan');\n\n// Status\nconst status = SF.showStatus('/path/to/scan');\n\n// Path validation\nconst inWorkspace = SF.isPathWithinWorkspace('/some/path');\n\n// Snippets are raw — no redaction applied\n// Results include: { path, name, size, score, snippet }\n\n// Formatting helpers\nSF.formatBytes(1024);                    // \"1 KB\"\nSF.charToTokens(100);                    // 25\nSF.similarity('hello', 'hello');         // 1\n```\n\n---\n\n## Testing\n\n```bash\n# Run full test suite (34 tests)\nnode skills/smart-files/tests/run-self-tests.js\n\n# Legacy CLI smoke tests\nnode skills/smart-files/test/run-tests.js\n```\n\nTest coverage:\n- Content search (5 cases)\n- Duplicate detection (3 cases)\n- File organization (3 cases)\n- File info (3 cases)\n- Cleanup analysis (3 cases)\n- Workspace status (2 cases)\n- File rename (3 cases)\n- Auto-org watcher functions (2 cases)\n- Security & validation (4 cases)\n- Helper functions (5 cases)\n\n---\n\n## Configuration\n\n| Variable | Description |\n|----------|-------------|\n| `SMART_FILES_WORKSPACE` | Override workspace root directory |\n\nAdjust `MAX_SCAN_SIZE` (10 MB default) at the top of `smart-files.js`:\n```javascript\nconst MAX_SCAN_SIZE = 10 * 1024 * 1024; // 10 MB\n```\n\n---\n\n## Examples\n\n### Find Todos Across Your Project\n```bash\nnode skills/smart-files/smart-files.js --search \"TODO\"\n```\n\n### Clean Up Your Downloads Folder\n```bash\nnode skills/smart-files/smart-files.js --cleanup ~/Downloads\n```\n\n### Preview Watch Mode Before Committing\n```bash\n# Always dry-run first\nnode skills/smart-files/smart-files.js --watch ~/Downloads --dry-run\n\n# Then decide if --force is safe\nnode skills/smart-files/smart-files.js --watch ~/Downloads --force\n```\n\n### Find Large Files Taking Space\n```bash\nnode skills/smart-files/smart-files.js --status ~/projects | grep MB\n```\n\n---\n\n## License\n\nMIT — Part of the OpenClaw skill ecosystem.\n\n---\n\n## Related Skills\n\n- **Secrets Manager** — Secure encrypted storage for secrets\n- **Environment Manager** — Dev environment setup and service tracking\n- **Smart Backup** — Automated backup of important files\n- **Notification Triage** — Stay notified when files change\nRANDOM_UNIQUE_TOKEN_1784758462\n\nFile v2.2.1:_meta.json\n\n{\n  \"ownerId\": \"kn7b6eyf5vc7khg5fr63pjm8xd82qvw5\",\n  \"slug\": \"smart-files\",\n  \"version\": \"2.2.1\",\n  \"publishedAt\": 1786824609560\n}\n\nFile v2.2.1:skill-card.md\n\n## Description:\n\nContent-aware file management for workspace files: search, duplicate detection, organization analysis, renaming previews, file metadata inspection, cleanup analysis, and continuous watch mode.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[jlacroix82](https://clawhub.ai/user/jlacroix82)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to inspect workspace files, find content and duplicates, summarize file metadata, preview cleanup or rename work, and monitor filesystem changes with explicit safety controls.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill requires broad local filesystem read access and declares write/watch authority.\n\nMitigation: Install only when that access is acceptable, keep scans scoped to the intended workspace, and avoid --force unless external path access is intentional.\n\nRisk: Matched content snippets are raw and may expose secrets or sensitive file contents in terminal output or agent context.\n\nMitigation: Keep the default snippet-hidden mode for sensitive directories and use --snippets only after confirming the searched files are safe to reveal.\n\nRisk: Watch mode persists file paths, hashes, sizes, timestamps, and change events to memory/smart-files-journal.json.\n\nMitigation: Avoid watch mode when persistent metadata is unacceptable, and clear memory/smart-files-journal.json when the audit trail is no longer needed.\n\nRisk: Server security evidence marks the release suspicious because declared write/watch behavior and documentation do not match the inspected code.\n\nMitigation: Review the implementation and test watch-mode behavior before relying on the release for file monitoring or mutation workflows.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/jlacroix82/skills/smart-files)\n- [README.md](artifact/README.md)\n- [SKILL.md](artifact/SKILL.md)\n- [clawhub.yaml](artifact/clawhub.yaml)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Terminal text and Markdown guidance with command examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Search output is capped at 20 results; snippets are hidden by default and shown only with --snippets.]\n\n## Skill Version(s):\n\n2.2.1 (source: server evidence, SKILL.md frontmatter, clawhub.yaml)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.2.1:clawhub.yaml\n\nslug: smart-files\nname: smart-files\nowner: jlacroix82\ndescription: Secure file search, dedup, organize, and rename for workspace files. Content-aware search that reads file contents and can print snippets to stdout. Watch mode provides continuous monitoring with persistent journaling. Uses --quiet mode for content suppression and --force to override workspace boundary.\nversion: 2.2.1\ntype: skill\nauthor: OpenClaw\nlicense: MIT\nkeywords:\n  - files\n  - analysis\n  - search\n  - code\n  - agent\n  - security\n  - privacy\nentry: SKILL.md\ndependencies: []\npermissions:\n  - name: filesystem.read\n    description: Recursively read file contents from workspace for search, dedup, info, cleanup, and status operations\n  - name: filesystem.write\n    description: Persist watch-mode journal to memory/smart-files-journal.json; organize/rename modify files via copy+unlink (requires --force outside dry-run)\n  - name: filesystem.watch\n    description: Continuously monitor a directory and persist file paths/hashes/sizes/timestamps/change events to the journal\n  - name: filesystem.external_path\n    description: Scan paths outside the workspace root when --force is passed (explicit opt-in per invocation)\n  - name: environment.read\n    description: Read SMART_FILES_WORKSPACE environment variable to override the workspace root\ncapabilities:\n  - filesystem\n  - environment\n\nFile v2.2.1:CHANGELOG.txt\n\nSmart Files v2.2.0 — Security Audit Remediation (2026-07-31)\n\nClawHub security audit fixes (3 HIGH findings):\n  - Content snippets now OPT-IN via --snippets; default search output shows\n    only paths + match scores (no content exposure)\n  - --force flag propagates to watch mode; workspace boundary enforced\n    unless --force is explicit\n  - Permissions declared in clawhub.yaml + SKILL.md frontmatter\n    (fs.read_recursive, fs.write, fs.watch_persist, fs.external_path)\n  - README: removed false \"automatic redaction\" claims; documented that\n    snippets are NOT redacted; added watch-mode journal disclosure\n    (location, contents, how to clear)\n  - SKILL.md: added \"Security Audit Remediation\" section + safety defaults\n    table (content snippets hidden by default)\n\nSmart Files v99.0.2 — Canonical Clean Release (2026-08-02)\n\nThis version carries the security-audit-remediated source code (v2.2.0) and\nreclaims the tags.latest slot above the prior v99.0.1 retag artifact.\n\nIncludes all v2.2.0 Security Audit Remediation (3 HIGH findings resolved):\n  - Content snippets OPT-IN via --snippets; default output shows only paths +\n    match scores (no content exposure)\n  - --force flag propagates to watch mode; workspace boundary enforced unless\n    --force is explicit\n  - Permissions declared in clawhub.yaml + SKILL.md frontmatter\n    (fs.read_recursive, fs.write, fs.watch_persist, fs.external_path)\n  - README/SKILL.md document that snippets are NOT redacted; watch-mode journal\n    disclosure (location, contents, how to clear)\n\nArchive v99.0.3: 8 files, 16550 bytes\n\nFiles: CHANGELOG.txt (1544b), clawhub.yaml (824b), README.md (11207b), skill-card.md (2491b), SKILL.md (3576b), smart-files.js (24733b), test/run-tests.js (772b), _meta.json (131b)\n\nFile v99.0.3:SKILL.md\n\n---\nname: smart-files\ndescription: Secure file search, dedup, organize, and rename for workspace files.\nversion: 99.0.3\npermissions:\n  - name: fs.read_recursive\n    description: Read file contents recursively in workspace for --search, --dedup, --info, --cleanup, --status modes\n  - name: fs.write\n    description: Write organize/rename operations (copy+unlink) and persist watch-mode journal to memory/smart-files-journal.json; requires --force for renames outside dry-run\n  - name: fs.watch_persist\n    description: Continuously monitor directory, persist file paths/hashes/timestamps/change events to journal file\n  - name: fs.external_path\n    description: Scan paths outside workspace root when --force is passed (e.g. external directories)\n---\n\n# Smart Files v2.2.0\n\n> **NOTE: Search mode reads file contents. Content snippets are hidden by default; use `--snippets` to show them.\n\n## Security Audit Remediation (2026-07-22)\n\n### Fix 1: --force flag now reaches watch mode\nBefore: watchDirectory() ignored --force, checked process.argv directly\nAfter: --force is properly passed as fourth parameter to watchDirectory()\n\n### Fix 2: Content snippets now opt-in (default hidden)\nContent snippets are **hidden by default** — only paths and match scores shown. Add `--snippets` to show matched content. `--quiet` is retained for backward compatibility (same effect as default).\n\n### Fix 3: Documentation alignment (remediation)\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features, and declare explicit permissions. Tests remain in the repo under test/ (excluded from the published bundle via .gitignore/clawhub.yaml packaging).\n\n### Fix 4: Documentation alignment\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features.\n\n### Fix 5: Explicit privacy warnings in SKILL.md\nProminent warnings about content exposure risk and safe usage patterns.\n\n### Fix 6: Watch mode boundary documented\nClear documentation that watch mode with --force monitors arbitrary filesystem paths.\n\n### Fix 7: Journal disclosure documented\nClear documentation that watch mode persists file paths, hashes, and timestamps to memory/smart-files-journal.json.\n\n## Commands\n\n- --search <query> [--snippets] — Content-aware search (snippets opt-in with --snippets)\n- --dedup — Duplicate detection by SHA-256\n- --organize — Read-only file categorization\n- --info <file> — File metadata and type detection\n- --cleanup — Read-only cleanup analysis\n- --status — Workspace overview\n- --rename <file> <old:new> [--force] — Rename (dry run by default)\n- --watch <dir> [interval] [--force] — Filesystem monitoring (long-running)\n- --quiet — Keep content snippets hidden (same as default behavior)\n- --force — Override workspace boundary (use with caution)\n\n## Safe Usage Examples\n\n```bash\n# Privacy-safe: only paths shown (default behavior)\nnode smart-files.js --search \"query\"\n\n# Show matched content snippets\nnode smart-files.js --search \"query\" --snippets\n\n# Watch workspace (safe, default behavior)\nnode smart-files.js --watch ./src 30\n\n# Watch external path (use with caution)\nnode smart-files.js --watch /path --force\n```\n\n## Safety Defaults\n\n| Feature | Default | Override |\n|---------|---------|----------|\n| Binary files | Skipped | Cannot override |\n| File size limit | 10MB | Cannot override |\n| Search results cap | 20 | Cannot override |\n| Workspace boundary | Enforced | --force |\n| Watch mode scope | Workspace | --force |\n| Rename mode | Dry run | --force |\n| Content snippets | Hidden (opt-in) | --snippets |\n\nFile v99.0.3:README.md\n\n# Smart Files 📁\n\n**Content-aware file management for OpenClaw agents — search, dedup, organize, rename, and auto-watch your workspace.**\n\n## Why Smart Files?\n\nYour workspace grows fast. Files scatter across directories, duplicates pile up, and finding the right file by name alone is slow. Smart Files solves this:\n\n- **Search by content** — Find files by what's *inside* them, not just their names\n- **Find duplicates** — SHA-256 content hashing catches identical files anywhere\n- **Auto-organize** — Categorize files by type (code, data, docs, media, archives)\n- **File intelligence** — Detect file types, line/word counts, metadata\n- **Auto-watch** — Monitor a directory and organize new files as they appear\n- **Safe by design** — All search/analysis modes are read-only. Watch mode is dry-run by default; `--force` required for any file modification.\n\n---\n\n## Installation\n\n```bash\n# Already included in OpenClaw workspace at skills/smart-files/\n# No npm install needed — pure Node.js\n```\n\n---\n\n## Quick Start\n\n```bash\n# Search by content\nnode skills/smart-files/smart-files.js --search \"api key\"\n\n# Find duplicates\nnode skills/smart-files/smart-files.js --dedup\n\n# Workspace overview\nnode skills/smart-files/smart-files.js --status\n\n# File intelligence\nnode skills/smart-files/smart-files.js --info some-file.js\n\n# Cleanup analysis\nnode skills/smart-files/smart-files.js --cleanup .\n```\n\n---\n\n## Commands Reference\n\n### File Search\n\n```bash\nnode skills/smart-files/smart-files.js --search <query> [--dir <path>]\n```\n\nSearches file **content** (not just filenames) for the query string. Returns ranked results.\n\nContent snippets are **hidden by default** — only paths and match scores are shown:\n\n```\n[smart-files] Found 3 matches for \"api key\":\n  ✅ 1.00 — /path/to/project/config.json\n  🔍 0.75 — /path/to/project/src/auth.js\n```\n\nTo show matched content snippets, add `--snippets`:\n\n```bash\nnode skills/smart-files/smart-files.js --search \"api key\" --snippets\n```\n\n⚠️ **Privacy**: Without `--quiet`, matched content is read from disk into memory. Snippets are **not redacted** — they print raw text as-is. Do not rely on snippet output as a security boundary when scanning directories containing secrets.\n\n---\n\n### Duplicate Detection\n\n```bash\nnode skills/smart-files/smart-files.js --dedup [--dir <path>]\n```\n\nGroups identical files by SHA-256 content hash. Only compares files of the same size (fast filter), then hashes candidates.\n\n```\n[smart-files] Found 2 groups of duplicate files:\n  3 files (1.2 KB) — hash: a1b2c3d4e5f6...\n    → /path/to/file1.txt\n    → /path/to/file2.txt\n    → /path/to/file3.txt\n```\n\n---\n\n### File Organization (read-only)\n\n```bash\nnode skills/smart-files/smart-files.js --organize [--dir <path>]\n```\n\nCategorizes all files by extension. **Read-only** — shows counts per category, never moves files.\n\n- **code** — .js, .ts, .py, .html, .css, .json, .yaml, .yml, .sh, .go, .rs, .c, .cpp, .java, .rb, .md, .txt, and more\n- **data** — .csv, .tsv, .json, .jsonl, .xml, .toml, .ini, .cfg, .env, .sql\n- **docs** — .pdf, .doc, .docx, .rtf, .odt, .tex, .epub\n- **media** — .jpg, .jpeg, .png, .gif, .svg, .webp, .bmp, .mp4, .mov, .mp3, .wav, .flac\n- **archives** — .zip, .tar, .gz, .rar, .7z, .bz2, .xz\n- **images** — .ico, .webp, .avif, .tiff, .psd, .ai, .eps\n\n---\n\n### File Intelligence\n\n```bash\nnode skills/smart-files/smart-files.js --info <filepath>\n```\n\nReturns detected type, size, line count, word count, modification date.\n\n```\n[smart-files] File info: server.js\n  Size: 12.3 KB\n  Type: JavaScript/TypeScript\n  Lines: 345\n  Words: 1,234\n  Modified: 2026-07-15\n  Path: /path/to/server.js\n```\n\n---\n\n### Cleanup Analysis\n\n```bash\nnode skills/smart-files/smart-files.js --cleanup <dir>\n```\n\nScans for:\n- **Temp/backup files** — .tmp, .bak, .swp, .orig, ~files\n- **Large files** (>1MB) — candidates for archiving\n- **Duplicate groups** — files with identical content\n\n---\n\n### Workspace Status\n\n```bash\nnode skills/smart-files/smart-files.js --status [--dir <path>]\n```\n\n```\n[smart-files] Workspace status:\n  Total files: 1,234\n  Total size: 45.2 MB\n  Extensions:\n    .js: 342 files, 12.1 MB\n    .md: 89 files, 2.3 MB\n    .json: 67 files, 8.9 MB\n  Largest files:\n    data.sqlite — 15.2 MB\n    bundle.js — 2.1 MB\n```\n\n---\n\n### Dry-Run Rename\n\n```bash\nnode skills/smart-files/smart-files.js --rename <file> <old>:<new>\n```\n\nPattern-based rename preview. Example:\n```bash\nnode skills/smart-files/smart-files.js --rename server-old.js old:new\n# [smart-files] Would rename: server-old.js → server-new.js\n# [smart-files] (Use --force to actually rename)\n```\n\n---\n\n### Auto-Organize Watcher ⚠️\n\n```bash\n# Dry-run preview (DEFAULT — safe, no files touched)\nnode skills/smart-files/smart-files.js --watch /path/to/dir [--dry-run]\n\n# Actually move/organize files (DESTRUCTIVE — requires explicit --force)\nnode skills/smart-files/smart-files.js --watch /path/to/dir --force\n```\n\n**⚠️ Watch mode is DRY-RUN by default.** It shows what would change without modifying anything. You must use `--force` explicitly to enable destructive operations.\n\nWhen `--force` is used:\n- A 5-second abort window is shown before operations begin\n- Files are **copied** to category subdirectories, then **originals are deleted** (copy+unlink — no atomic move)\n- This is **inherently destructive** — the original inode is destroyed\n- A journal is written to `memory/smart-files-journal.json` for audit trail\n- **There is no automatic rollback** — the journal is for manual recovery only\n- The watcher runs continuously and modifies files as they appear\n\n**Always run `--dry-run` first** to preview what would change before using `--force`.\n\n**Custom rules** via `.smart-files-rules.json` in the watched directory:\n```json\n[\n  { \"exts\": [\".js\", \".ts\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".py\", \".rb\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".jpg\", \".png\"], \"category\": \"Images\" }\n]\n```\n\nDefault rules organize into: Pictures, Documents, Videos, Audio, Code, Uncategorized.\n\n---\n\n## Security & Privacy\n\n⚠️ **Smart Files reads file contents** — search results include content snippets. This means file contents enter terminal output and agent context.\n\n| Protection | Details |\n|------------|---------|\n| **Read-only by default** | `--search`, `--dedup`, `--organize`, `--info`, `--cleanup`, `--status` never modify files |\n| **Content snippets hidden** (opt-in) | Snippets only shown with `--snippets`; paths and scores always displayed |\n| **Binary detection** | Null-byte check + binary extension filter |\n| **Oversized file skip** | Configurable MAX_SCAN_SIZE (10MB default) |\n| **No shell execution** | Pure Node.js `fs` ops — no `child_process` |\n| **Watch safety gate** | Defaults to dry-run; `--force` required for mutations |\n| **Skip directories** | `.git`, `node_modules`, `.npm`, `.cache` excluded by default |\n| **Workspace awareness** | Detects and warns when scanning outside workspace |\n\n### Watch Mode Journal ⚠️\n\nWatch mode persists a journal file to track changes:\n\n- **Location:** `<workspace>/memory/smart-files-journal.json`\n  (override with `SMART_FILES_WORKSPACE` env var)\n- **Contents:** File paths, SHA-256 hashes, sizes, modification times, and change events (new/modified/removed)\n- **Not stored:** File contents — only hashes and metadata\n- **Size limit:** Journal entries capped at 1000; oldest dropped first on overflow\n- **To clear the journal:** Delete `memory/smart-files-journal.json` manually\n- **To disable persistence:** The watcher still scans each interval but does not write to disk if you delete the file before running watch mode (the code will recreate it)\n\n```bash\n# Clear the watch-mode journal\ncp memory/smart-files-journal.json memory/smart-files-journal.backup && > memory/smart-files-journal.json\n\n# Or remove entirely\nrm -f memory/smart-files-journal.json\n```\n\n### What's NOT Protected\n\n- **No snippet redaction**: Snippets print raw file content as-is — no pattern-based filtering occurs.\n- **Content exposure**: When `--snippets` is used, matched content is printed to stdout and may enter agent context. Anyone with terminal access or log access can see them.\n- **Watch-mode journal**: File paths, hashes, sizes, and timestamps are persisted to disk (`memory/smart-files-journal.json`). Delete the file to clear; entries capped at 1000.\n- **No encryption**: File content is not encrypted at rest or in transit. Smart Files is a local file analysis tool, not a secrets vault.\n\n---\n\n## Programmatic API\n\n```javascript\nconst SF = require('./skills/smart-files/smart-files.js');\n\n// Search files — each result includes path, score, and raw content snippet\nconst results = SF.searchFiles('api key', '/path/to/scan');\n\n// Find duplicates\nconst dupGroups = SF.findDuplicates('/path/to/scan');\n\n// Organize (read-only)\nconst organized = SF.organizeFiles('/path/to/scan');\n\n// File info\nconst info = SF.fileInfo('/path/to/file.js');\n\n// Cleanup analysis\nconst analysis = SF.cleanupFiles('/path/to/scan');\n\n// Status\nconst status = SF.showStatus('/path/to/scan');\n\n// Path validation\nconst inWorkspace = SF.isPathWithinWorkspace('/some/path');\n\n// Snippets are raw — no redaction applied\n// Results include: { path, name, size, score, snippet }\n\n// Formatting helpers\nSF.formatBytes(1024);                    // \"1 KB\"\nSF.charToTokens(100);                    // 25\nSF.similarity('hello', 'hello');         // 1\n```\n\n---\n\n## Testing\n\n```bash\n# Run full test suite (34 tests)\nnode skills/smart-files/tests/run-self-tests.js\n\n# Legacy CLI smoke tests\nnode skills/smart-files/test/run-tests.js\n```\n\nTest coverage:\n- Content search (5 cases)\n- Duplicate detection (3 cases)\n- File organization (3 cases)\n- File info (3 cases)\n- Cleanup analysis (3 cases)\n- Workspace status (2 cases)\n- File rename (3 cases)\n- Auto-org watcher functions (2 cases)\n- Security & validation (4 cases)\n- Helper functions (5 cases)\n\n---\n\n## Configuration\n\n| Variable | Description |\n|----------|-------------|\n| `SMART_FILES_WORKSPACE` | Override workspace root directory |\n\nAdjust `MAX_SCAN_SIZE` (10 MB default) at the top of `smart-files.js`:\n```javascript\nconst MAX_SCAN_SIZE = 10 * 1024 * 1024; // 10 MB\n```\n\n---\n\n## Examples\n\n### Find Todos Across Your Project\n```bash\nnode skills/smart-files/smart-files.js --search \"TODO\"\n```\n\n### Clean Up Your Downloads Folder\n```bash\nnode skills/smart-files/smart-files.js --cleanup ~/Downloads\n```\n\n### Preview Watch Mode Before Committing\n```bash\n# Always dry-run first\nnode skills/smart-files/smart-files.js --watch ~/Downloads --dry-run\n\n# Then decide if --force is safe\nnode skills/smart-files/smart-files.js --watch ~/Downloads --force\n```\n\n### Find Large Files Taking Space\n```bash\nnode skills/smart-files/smart-files.js --status ~/projects | grep MB\n```\n\n---\n\n## License\n\nMIT — Part of the OpenClaw skill ecosystem.\n\n---\n\n## Related Skills\n\n- **Secrets Manager** — Secure encrypted storage for secrets\n- **Environment Manager** — Dev environment setup and service tracking\n- **Smart Backup** — Automated backup of important files\n- **Notification Triage** — Stay notified when files change\nRANDOM_UNIQUE_TOKEN_1784758462\n\nFile v99.0.3:_meta.json\n\n{\n  \"ownerId\": \"kn7b6eyf5vc7khg5fr63pjm8xd82qvw5\",\n  \"slug\": \"smart-files\",\n  \"version\": \"99.0.3\",\n  \"publishedAt\": 1785700879814\n}\n\nFile v99.0.3:skill-card.md\n\n## Description: <br>\nSecure file search, dedup, organize, and rename for workspace files. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[jlacroix82](https://clawhub.ai/user/jlacroix82) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and agents use Smart Files to search file contents, find duplicates, inspect metadata, analyze cleanup candidates, preview renames, and monitor workspace changes. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Recursive file search and analysis can read sensitive workspace content. <br>\nMitigation: Use the tool only on intended directories, avoid secret-heavy paths, and keep snippets disabled unless raw matched content is explicitly needed. <br>\nRisk: Snippet mode can print unredacted file content to stdout and agent context. <br>\nMitigation: Run searches without --snippets by default and review output handling before enabling snippets. <br>\nRisk: Watch mode persists file paths, hashes, sizes, timestamps, and change events in a local journal. <br>\nMitigation: Run watch mode only where metadata persistence is acceptable and clear memory/smart-files-journal.json when the audit trail is no longer needed. <br>\nRisk: --force can allow scanning outside the workspace and can enable file-moving behavior in watch workflows. <br>\nMitigation: Use --force only for deliberately selected paths after a dry run, and review the affected directory before enabling modifications. <br>\n\n\n## Reference(s): <br>\n- [ClawHub smart-files page](https://clawhub.ai/jlacroix82/skills/smart-files) <br>\n- [README](artifact/README.md) <br>\n- [SKILL.md](artifact/SKILL.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, Shell commands, Configuration, Files] <br>\n**Output Format:** [Terminal text with optional JSON configuration and local file operations] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Search snippets are hidden by default; watch mode can persist path, hash, size, timestamp, and change-event metadata to a local journal.] <br>\n\n## Skill Version(s): <br>\n99.0.3 (source: release evidence and frontmatter) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v99.0.3:clawhub.yaml\n\nslug: smart-files\nname: smart-files\nowner: jlacroix82\ndescription: Secure file search, dedup, organize, and rename for workspace files. Content-aware search that reads file contents and can print snippets to stdout. Watch mode provides continuous monitoring with persistent journaling. Uses --quiet mode for content suppression and --force to override workspace boundary.\nversion: 99.0.3\ntype: skill\nauthor: OpenClaw\nlicense: MIT\nkeywords:\n  - files\n  - analysis\n  - search\n  - code\n  - agent\n  - security\n  - privacy\nentry: SKILL.md\ndependencies: []\npermissions:\n  - name: filesystem.read\n    description: Recursively read file contents from workspace for search and dedup operations\n  - name: filesystem.write\n    description: Write file modification journal to memory/smart-files-journal.json\ncapabilities:\n  - filesystem\n\nFile v99.0.3:CHANGELOG.txt\n\nSmart Files v2.2.0 — Security Audit Remediation (2026-07-31)\n\nClawHub security audit fixes (3 HIGH findings):\n  - Content snippets now OPT-IN via --snippets; default search output shows\n    only paths + match scores (no content exposure)\n  - --force flag propagates to watch mode; workspace boundary enforced\n    unless --force is explicit\n  - Permissions declared in clawhub.yaml + SKILL.md frontmatter\n    (fs.read_recursive, fs.write, fs.watch_persist, fs.external_path)\n  - README: removed false \"automatic redaction\" claims; documented that\n    snippets are NOT redacted; added watch-mode journal disclosure\n    (location, contents, how to clear)\n  - SKILL.md: added \"Security Audit Remediation\" section + safety defaults\n    table (content snippets hidden by default)\n\nSmart Files v99.0.2 — Canonical Clean Release (2026-08-02)\n\nThis version carries the security-audit-remediated source code (v2.2.0) and\nreclaims the tags.latest slot above the prior v99.0.1 retag artifact.\n\nIncludes all v2.2.0 Security Audit Remediation (3 HIGH findings resolved):\n  - Content snippets OPT-IN via --snippets; default output shows only paths +\n    match scores (no content exposure)\n  - --force flag propagates to watch mode; workspace boundary enforced unless\n    --force is explicit\n  - Permissions declared in clawhub.yaml + SKILL.md frontmatter\n    (fs.read_recursive, fs.write, fs.watch_persist, fs.external_path)\n  - README/SKILL.md document that snippets are NOT redacted; watch-mode journal\n    disclosure (location, contents, how to clear)\n\nArchive v99.0.2: 8 files, 16477 bytes\n\nFiles: CHANGELOG.txt (1544b), clawhub.yaml (824b), README.md (11207b), skill-card.md (2296b), SKILL.md (3576b), smart-files.js (24733b), test/run-tests.js (772b), _meta.json (131b)\n\nFile v99.0.2:SKILL.md\n\n---\nname: smart-files\ndescription: Secure file search, dedup, organize, and rename for workspace files.\nversion: 99.0.2\npermissions:\n  - name: fs.read_recursive\n    description: Read file contents recursively in workspace for --search, --dedup, --info, --cleanup, --status modes\n  - name: fs.write\n    description: Write organize/rename operations (copy+unlink) and persist watch-mode journal to memory/smart-files-journal.json; requires --force for renames outside dry-run\n  - name: fs.watch_persist\n    description: Continuously monitor directory, persist file paths/hashes/timestamps/change events to journal file\n  - name: fs.external_path\n    description: Scan paths outside workspace root when --force is passed (e.g. external directories)\n---\n\n# Smart Files v2.2.0\n\n> **NOTE: Search mode reads file contents. Content snippets are hidden by default; use `--snippets` to show them.\n\n## Security Audit Remediation (2026-07-22)\n\n### Fix 1: --force flag now reaches watch mode\nBefore: watchDirectory() ignored --force, checked process.argv directly\nAfter: --force is properly passed as fourth parameter to watchDirectory()\n\n### Fix 2: Content snippets now opt-in (default hidden)\nContent snippets are **hidden by default** — only paths and match scores shown. Add `--snippets` to show matched content. `--quiet` is retained for backward compatibility (same effect as default).\n\n### Fix 3: Documentation alignment (remediation)\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features, and declare explicit permissions. Tests remain in the repo under test/ (excluded from the published bundle via .gitignore/clawhub.yaml packaging).\n\n### Fix 4: Documentation alignment\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features.\n\n### Fix 5: Explicit privacy warnings in SKILL.md\nProminent warnings about content exposure risk and safe usage patterns.\n\n### Fix 6: Watch mode boundary documented\nClear documentation that watch mode with --force monitors arbitrary filesystem paths.\n\n### Fix 7: Journal disclosure documented\nClear documentation that watch mode persists file paths, hashes, and timestamps to memory/smart-files-journal.json.\n\n## Commands\n\n- --search <query> [--snippets] — Content-aware search (snippets opt-in with --snippets)\n- --dedup — Duplicate detection by SHA-256\n- --organize — Read-only file categorization\n- --info <file> — File metadata and type detection\n- --cleanup — Read-only cleanup analysis\n- --status — Workspace overview\n- --rename <file> <old:new> [--force] — Rename (dry run by default)\n- --watch <dir> [interval] [--force] — Filesystem monitoring (long-running)\n- --quiet — Keep content snippets hidden (same as default behavior)\n- --force — Override workspace boundary (use with caution)\n\n## Safe Usage Examples\n\n```bash\n# Privacy-safe: only paths shown (default behavior)\nnode smart-files.js --search \"query\"\n\n# Show matched content snippets\nnode smart-files.js --search \"query\" --snippets\n\n# Watch workspace (safe, default behavior)\nnode smart-files.js --watch ./src 30\n\n# Watch external path (use with caution)\nnode smart-files.js --watch /path --force\n```\n\n## Safety Defaults\n\n| Feature | Default | Override |\n|---------|---------|----------|\n| Binary files | Skipped | Cannot override |\n| File size limit | 10MB | Cannot override |\n| Search results cap | 20 | Cannot override |\n| Workspace boundary | Enforced | --force |\n| Watch mode scope | Workspace | --force |\n| Rename mode | Dry run | --force |\n| Content snippets | Hidden (opt-in) | --snippets |\n\nFile v99.0.2:README.md\n\n# Smart Files 📁\n\n**Content-aware file management for OpenClaw agents — search, dedup, organize, rename, and auto-watch your workspace.**\n\n## Why Smart Files?\n\nYour workspace grows fast. Files scatter across directories, duplicates pile up, and finding the right file by name alone is slow. Smart Files solves this:\n\n- **Search by content** — Find files by what's *inside* them, not just their names\n- **Find duplicates** — SHA-256 content hashing catches identical files anywhere\n- **Auto-organize** — Categorize files by type (code, data, docs, media, archives)\n- **File intelligence** — Detect file types, line/word counts, metadata\n- **Auto-watch** — Monitor a directory and organize new files as they appear\n- **Safe by design** — All search/analysis modes are read-only. Watch mode is dry-run by default; `--force` required for any file modification.\n\n---\n\n## Installation\n\n```bash\n# Already included in OpenClaw workspace at skills/smart-files/\n# No npm install needed — pure Node.js\n```\n\n---\n\n## Quick Start\n\n```bash\n# Search by content\nnode skills/smart-files/smart-files.js --search \"api key\"\n\n# Find duplicates\nnode skills/smart-files/smart-files.js --dedup\n\n# Workspace overview\nnode skills/smart-files/smart-files.js --status\n\n# File intelligence\nnode skills/smart-files/smart-files.js --info some-file.js\n\n# Cleanup analysis\nnode skills/smart-files/smart-files.js --cleanup .\n```\n\n---\n\n## Commands Reference\n\n### File Search\n\n```bash\nnode skills/smart-files/smart-files.js --search <query> [--dir <path>]\n```\n\nSearches file **content** (not just filenames) for the query string. Returns ranked results.\n\nContent snippets are **hidden by default** — only paths and match scores are shown:\n\n```\n[smart-files] Found 3 matches for \"api key\":\n  ✅ 1.00 — /path/to/project/config.json\n  🔍 0.75 — /path/to/project/src/auth.js\n```\n\nTo show matched content snippets, add `--snippets`:\n\n```bash\nnode skills/smart-files/smart-files.js --search \"api key\" --snippets\n```\n\n⚠️ **Privacy**: Without `--quiet`, matched content is read from disk into memory. Snippets are **not redacted** — they print raw text as-is. Do not rely on snippet output as a security boundary when scanning directories containing secrets.\n\n---\n\n### Duplicate Detection\n\n```bash\nnode skills/smart-files/smart-files.js --dedup [--dir <path>]\n```\n\nGroups identical files by SHA-256 content hash. Only compares files of the same size (fast filter), then hashes candidates.\n\n```\n[smart-files] Found 2 groups of duplicate files:\n  3 files (1.2 KB) — hash: a1b2c3d4e5f6...\n    → /path/to/file1.txt\n    → /path/to/file2.txt\n    → /path/to/file3.txt\n```\n\n---\n\n### File Organization (read-only)\n\n```bash\nnode skills/smart-files/smart-files.js --organize [--dir <path>]\n```\n\nCategorizes all files by extension. **Read-only** — shows counts per category, never moves files.\n\n- **code** — .js, .ts, .py, .html, .css, .json, .yaml, .yml, .sh, .go, .rs, .c, .cpp, .java, .rb, .md, .txt, and more\n- **data** — .csv, .tsv, .json, .jsonl, .xml, .toml, .ini, .cfg, .env, .sql\n- **docs** — .pdf, .doc, .docx, .rtf, .odt, .tex, .epub\n- **media** — .jpg, .jpeg, .png, .gif, .svg, .webp, .bmp, .mp4, .mov, .mp3, .wav, .flac\n- **archives** — .zip, .tar, .gz, .rar, .7z, .bz2, .xz\n- **images** — .ico, .webp, .avif, .tiff, .psd, .ai, .eps\n\n---\n\n### File Intelligence\n\n```bash\nnode skills/smart-files/smart-files.js --info <filepath>\n```\n\nReturns detected type, size, line count, word count, modification date.\n\n```\n[smart-files] File info: server.js\n  Size: 12.3 KB\n  Type: JavaScript/TypeScript\n  Lines: 345\n  Words: 1,234\n  Modified: 2026-07-15\n  Path: /path/to/server.js\n```\n\n---\n\n### Cleanup Analysis\n\n```bash\nnode skills/smart-files/smart-files.js --cleanup <dir>\n```\n\nScans for:\n- **Temp/backup files** — .tmp, .bak, .swp, .orig, ~files\n- **Large files** (>1MB) — candidates for archiving\n- **Duplicate groups** — files with identical content\n\n---\n\n### Workspace Status\n\n```bash\nnode skills/smart-files/smart-files.js --status [--dir <path>]\n```\n\n```\n[smart-files] Workspace status:\n  Total files: 1,234\n  Total size: 45.2 MB\n  Extensions:\n    .js: 342 files, 12.1 MB\n    .md: 89 files, 2.3 MB\n    .json: 67 files, 8.9 MB\n  Largest files:\n    data.sqlite — 15.2 MB\n    bundle.js — 2.1 MB\n```\n\n---\n\n### Dry-Run Rename\n\n```bash\nnode skills/smart-files/smart-files.js --rename <file> <old>:<new>\n```\n\nPattern-based rename preview. Example:\n```bash\nnode skills/smart-files/smart-files.js --rename server-old.js old:new\n# [smart-files] Would rename: server-old.js → server-new.js\n# [smart-files] (Use --force to actually rename)\n```\n\n---\n\n### Auto-Organize Watcher ⚠️\n\n```bash\n# Dry-run preview (DEFAULT — safe, no files touched)\nnode skills/smart-files/smart-files.js --watch /path/to/dir [--dry-run]\n\n# Actually move/organize files (DESTRUCTIVE — requires explicit --force)\nnode skills/smart-files/smart-files.js --watch /path/to/dir --force\n```\n\n**⚠️ Watch mode is DRY-RUN by default.** It shows what would change without modifying anything. You must use `--force` explicitly to enable destructive operations.\n\nWhen `--force` is used:\n- A 5-second abort window is shown before operations begin\n- Files are **copied** to category subdirectories, then **originals are deleted** (copy+unlink — no atomic move)\n- This is **inherently destructive** — the original inode is destroyed\n- A journal is written to `memory/smart-files-journal.json` for audit trail\n- **There is no automatic rollback** — the journal is for manual recovery only\n- The watcher runs continuously and modifies files as they appear\n\n**Always run `--dry-run` first** to preview what would change before using `--force`.\n\n**Custom rules** via `.smart-files-rules.json` in the watched directory:\n```json\n[\n  { \"exts\": [\".js\", \".ts\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".py\", \".rb\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".jpg\", \".png\"], \"category\": \"Images\" }\n]\n```\n\nDefault rules organize into: Pictures, Documents, Videos, Audio, Code, Uncategorized.\n\n---\n\n## Security & Privacy\n\n⚠️ **Smart Files reads file contents** — search results include content snippets. This means file contents enter terminal output and agent context.\n\n| Protection | Details |\n|------------|---------|\n| **Read-only by default** | `--search`, `--dedup`, `--organize`, `--info`, `--cleanup`, `--status` never modify files |\n| **Content snippets hidden** (opt-in) | Snippets only shown with `--snippets`; paths and scores always displayed |\n| **Binary detection** | Null-byte check + binary extension filter |\n| **Oversized file skip** | Configurable MAX_SCAN_SIZE (10MB default) |\n| **No shell execution** | Pure Node.js `fs` ops — no `child_process` |\n| **Watch safety gate** | Defaults to dry-run; `--force` required for mutations |\n| **Skip directories** | `.git`, `node_modules`, `.npm`, `.cache` excluded by default |\n| **Workspace awareness** | Detects and warns when scanning outside workspace |\n\n### Watch Mode Journal ⚠️\n\nWatch mode persists a journal file to track changes:\n\n- **Location:** `<workspace>/memory/smart-files-journal.json`\n  (override with `SMART_FILES_WORKSPACE` env var)\n- **Contents:** File paths, SHA-256 hashes, sizes, modification times, and change events (new/modified/removed)\n- **Not stored:** File contents — only hashes and metadata\n- **Size limit:** Journal entries capped at 1000; oldest dropped first on overflow\n- **To clear the journal:** Delete `memory/smart-files-journal.json` manually\n- **To disable persistence:** The watcher still scans each interval but does not write to disk if you delete the file before running watch mode (the code will recreate it)\n\n```bash\n# Clear the watch-mode journal\ncp memory/smart-files-journal.json memory/smart-files-journal.backup && > memory/smart-files-journal.json\n\n# Or remove entirely\nrm -f memory/smart-files-journal.json\n```\n\n### What's NOT Protected\n\n- **No snippet redaction**: Snippets print raw file content as-is — no pattern-based filtering occurs.\n- **Content exposure**: When `--snippets` is used, matched content is printed to stdout and may enter agent context. Anyone with terminal access or log access can see them.\n- **Watch-mode journal**: File paths, hashes, sizes, and timestamps are persisted to disk (`memory/smart-files-journal.json`). Delete the file to clear; entries capped at 1000.\n- **No encryption**: File content is not encrypted at rest or in transit. Smart Files is a local file analysis tool, not a secrets vault.\n\n---\n\n## Programmatic API\n\n```javascript\nconst SF = require('./skills/smart-files/smart-files.js');\n\n// Search files — each result includes path, score, and raw content snippet\nconst results = SF.searchFiles('api key', '/path/to/scan');\n\n// Find duplicates\nconst dupGroups = SF.findDuplicates('/path/to/scan');\n\n// Organize (read-only)\nconst organized = SF.organizeFiles('/path/to/scan');\n\n// File info\nconst info = SF.fileInfo('/path/to/file.js');\n\n// Cleanup analysis\nconst analysis = SF.cleanupFiles('/path/to/scan');\n\n// Status\nconst status = SF.showStatus('/path/to/scan');\n\n// Path validation\nconst inWorkspace = SF.isPathWithinWorkspace('/some/path');\n\n// Snippets are raw — no redaction applied\n// Results include: { path, name, size, score, snippet }\n\n// Formatting helpers\nSF.formatBytes(1024);                    // \"1 KB\"\nSF.charToTokens(100);                    // 25\nSF.similarity('hello', 'hello');         // 1\n```\n\n---\n\n## Testing\n\n```bash\n# Run full test suite (34 tests)\nnode skills/smart-files/tests/run-self-tests.js\n\n# Legacy CLI smoke tests\nnode skills/smart-files/test/run-tests.js\n```\n\nTest coverage:\n- Content search (5 cases)\n- Duplicate detection (3 cases)\n- File organization (3 cases)\n- File info (3 cases)\n- Cleanup analysis (3 cases)\n- Workspace status (2 cases)\n- File rename (3 cases)\n- Auto-org watcher functions (2 cases)\n- Security & validation (4 cases)\n- Helper functions (5 cases)\n\n---\n\n## Configuration\n\n| Variable | Description |\n|----------|-------------|\n| `SMART_FILES_WORKSPACE` | Override workspace root directory |\n\nAdjust `MAX_SCAN_SIZE` (10 MB default) at the top of `smart-files.js`:\n```javascript\nconst MAX_SCAN_SIZE = 10 * 1024 * 1024; // 10 MB\n```\n\n---\n\n## Examples\n\n### Find Todos Across Your Project\n```bash\nnode skills/smart-files/smart-files.js --search \"TODO\"\n```\n\n### Clean Up Your Downloads Folder\n```bash\nnode skills/smart-files/smart-files.js --cleanup ~/Downloads\n```\n\n### Preview Watch Mode Before Committing\n```bash\n# Always dry-run first\nnode skills/smart-files/smart-files.js --watch ~/Downloads --dry-run\n\n# Then decide if --force is safe\nnode skills/smart-files/smart-files.js --watch ~/Downloads --force\n```\n\n### Find Large Files Taking Space\n```bash\nnode skills/smart-files/smart-files.js --status ~/projects | grep MB\n```\n\n---\n\n## License\n\nMIT — Part of the OpenClaw skill ecosystem.\n\n---\n\n## Related Skills\n\n- **Secrets Manager** — Secure encrypted storage for secrets\n- **Environment Manager** — Dev environment setup and service tracking\n- **Smart Backup** — Automated backup of important files\n- **Notification Triage** — Stay notified when files change\nRANDOM_UNIQUE_TOKEN_1784758462\n\nFile v99.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn7b6eyf5vc7khg5fr63pjm8xd82qvw5\",\n  \"slug\": \"smart-files\",\n  \"version\": \"99.0.2\",\n  \"publishedAt\": 1785689210519\n}\n\nFile v99.0.2:skill-card.md\n\n## Description: <br>\nSecure file search, dedup, organize, and rename for workspace files. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[jlacroix82](https://clawhub.ai/user/jlacroix82) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and agents use this skill to inspect workspace files, search file contents, find duplicates, categorize files, review file metadata, and preview or perform controlled rename and watch workflows. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill recursively reads local workspace files and can expose sensitive content when snippets are enabled. <br>\nMitigation: Avoid using --snippets on directories that may contain secrets; keep the default snippet-hidden behavior for routine searches. <br>\nRisk: --force can allow scanning or monitoring paths outside the workspace boundary. <br>\nMitigation: Use --force only for explicitly intended external paths and review the target directory before running long-lived watch mode. <br>\nRisk: Watch mode persists file paths, hashes, timestamps, and change events to memory/smart-files-journal.json. <br>\nMitigation: Review or delete the journal when path metadata or change history is sensitive. <br>\n\n\n## Reference(s): <br>\n- [ClawHub skill page](https://clawhub.ai/jlacroix82/skills/smart-files) <br>\n- [README.md](artifact/README.md) <br>\n- [CHANGELOG.txt](artifact/CHANGELOG.txt) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, shell commands, guidance] <br>\n**Output Format:** [Terminal text and Markdown guidance with inline shell commands] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Search results are capped, binary and oversized files are skipped, snippets are hidden by default, and watch-mode journaling may persist file path and change-history metadata.] <br>\n\n## Skill Version(s): <br>\n99.0.2 (source: evidence.release.version and SKILL.md frontmatter) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v99.0.2:clawhub.yaml\n\nslug: smart-files\nname: smart-files\nowner: jlacroix82\ndescription: Secure file search, dedup, organize, and rename for workspace files. Content-aware search that reads file contents and can print snippets to stdout. Watch mode provides continuous monitoring with persistent journaling. Uses --quiet mode for content suppression and --force to override workspace boundary.\nversion: 99.0.2\ntype: skill\nauthor: OpenClaw\nlicense: MIT\nkeywords:\n  - files\n  - analysis\n  - search\n  - code\n  - agent\n  - security\n  - privacy\nentry: SKILL.md\ndependencies: []\npermissions:\n  - name: filesystem.read\n    description: Recursively read file contents from workspace for search and dedup operations\n  - name: filesystem.write\n    description: Write file modification journal to memory/smart-files-journal.json\ncapabilities:\n  - filesystem\n\nFile v99.0.2:CHANGELOG.txt\n\nSmart Files v2.2.0 — Security Audit Remediation (2026-07-31)\n\nClawHub security audit fixes (3 HIGH findings):\n  - Content snippets now OPT-IN via --snippets; default search output shows\n    only paths + match scores (no content exposure)\n  - --force flag propagates to watch mode; workspace boundary enforced\n    unless --force is explicit\n  - Permissions declared in clawhub.yaml + SKILL.md frontmatter\n    (fs.read_recursive, fs.write, fs.watch_persist, fs.external_path)\n  - README: removed false \"automatic redaction\" claims; documented that\n    snippets are NOT redacted; added watch-mode journal disclosure\n    (location, contents, how to clear)\n  - SKILL.md: added \"Security Audit Remediation\" section + safety defaults\n    table (content snippets hidden by default)\n\nSmart Files v99.0.2 — Canonical Clean Release (2026-08-02)\n\nThis version carries the security-audit-remediated source code (v2.2.0) and\nreclaims the tags.latest slot above the prior v99.0.1 retag artifact.\n\nIncludes all v2.2.0 Security Audit Remediation (3 HIGH findings resolved):\n  - Content snippets OPT-IN via --snippets; default output shows only paths +\n    match scores (no content exposure)\n  - --force flag propagates to watch mode; workspace boundary enforced unless\n    --force is explicit\n  - Permissions declared in clawhub.yaml + SKILL.md frontmatter\n    (fs.read_recursive, fs.write, fs.watch_persist, fs.external_path)\n  - README/SKILL.md document that snippets are NOT redacted; watch-mode journal\n    disclosure (location, contents, how to clear)\n\nArchive v2.2.0: 8 files, 16802 bytes\n\nFiles: CHANGELOG.txt (1770b), clawhub.yaml (823b), README.md (11207b), skill-card.md (2273b), SKILL.md (3575b), smart-files.js (24733b), test/run-tests.js (772b), _meta.json (130b)\n\nFile v2.2.0:SKILL.md\n\n---\nname: smart-files\ndescription: Secure file search, dedup, organize, and rename for workspace files.\nversion: 2.2.0\npermissions:\n  - name: fs.read_recursive\n    description: Read file contents recursively in workspace for --search, --dedup, --info, --cleanup, --status modes\n  - name: fs.write\n    description: Write organize/rename operations (copy+unlink) and persist watch-mode journal to memory/smart-files-journal.json; requires --force for renames outside dry-run\n  - name: fs.watch_persist\n    description: Continuously monitor directory, persist file paths/hashes/timestamps/change events to journal file\n  - name: fs.external_path\n    description: Scan paths outside workspace root when --force is passed (e.g. external directories)\n---\n\n# Smart Files v2.2.0\n\n> **NOTE: Search mode reads file contents. Content snippets are hidden by default; use `--snippets` to show them.\n\n## Security Audit Remediation (2026-07-22)\n\n### Fix 1: --force flag now reaches watch mode\nBefore: watchDirectory() ignored --force, checked process.argv directly\nAfter: --force is properly passed as fourth parameter to watchDirectory()\n\n### Fix 2: Content snippets now opt-in (default hidden)\nContent snippets are **hidden by default** — only paths and match scores shown. Add `--snippets` to show matched content. `--quiet` is retained for backward compatibility (same effect as default).\n\n### Fix 3: Documentation alignment (remediation)\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features, and declare explicit permissions. Tests remain in the repo under test/ (excluded from the published bundle via .gitignore/clawhub.yaml packaging).\n\n### Fix 4: Documentation alignment\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features.\n\n### Fix 5: Explicit privacy warnings in SKILL.md\nProminent warnings about content exposure risk and safe usage patterns.\n\n### Fix 6: Watch mode boundary documented\nClear documentation that watch mode with --force monitors arbitrary filesystem paths.\n\n### Fix 7: Journal disclosure documented\nClear documentation that watch mode persists file paths, hashes, and timestamps to memory/smart-files-journal.json.\n\n## Commands\n\n- --search <query> [--snippets] — Content-aware search (snippets opt-in with --snippets)\n- --dedup — Duplicate detection by SHA-256\n- --organize — Read-only file categorization\n- --info <file> — File metadata and type detection\n- --cleanup — Read-only cleanup analysis\n- --status — Workspace overview\n- --rename <file> <old:new> [--force] — Rename (dry run by default)\n- --watch <dir> [interval] [--force] — Filesystem monitoring (long-running)\n- --quiet — Keep content snippets hidden (same as default behavior)\n- --force — Override workspace boundary (use with caution)\n\n## Safe Usage Examples\n\n```bash\n# Privacy-safe: only paths shown (default behavior)\nnode smart-files.js --search \"query\"\n\n# Show matched content snippets\nnode smart-files.js --search \"query\" --snippets\n\n# Watch workspace (safe, default behavior)\nnode smart-files.js --watch ./src 30\n\n# Watch external path (use with caution)\nnode smart-files.js --watch /path --force\n```\n\n## Safety Defaults\n\n| Feature | Default | Override |\n|---------|---------|----------|\n| Binary files | Skipped | Cannot override |\n| File size limit | 10MB | Cannot override |\n| Search results cap | 20 | Cannot override |\n| Workspace boundary | Enforced | --force |\n| Watch mode scope | Workspace | --force |\n| Rename mode | Dry run | --force |\n| Content snippets | Hidden (opt-in) | --snippets |\n\nFile v2.2.0:README.md\n\n# Smart Files 📁\n\n**Content-aware file management for OpenClaw agents — search, dedup, organize, rename, and auto-watch your workspace.**\n\n## Why Smart Files?\n\nYour workspace grows fast. Files scatter across directories, duplicates pile up, and finding the right file by name alone is slow. Smart Files solves this:\n\n- **Search by content** — Find files by what's *inside* them, not just their names\n- **Find duplicates** — SHA-256 content hashing catches identical files anywhere\n- **Auto-organize** — Categorize files by type (code, data, docs, media, archives)\n- **File intelligence** — Detect file types, line/word counts, metadata\n- **Auto-watch** — Monitor a directory and organize new files as they appear\n- **Safe by design** — All search/analysis modes are read-only. Watch mode is dry-run by default; `--force` required for any file modification.\n\n---\n\n## Installation\n\n```bash\n# Already included in OpenClaw workspace at skills/smart-files/\n# No npm install needed — pure Node.js\n```\n\n---\n\n## Quick Start\n\n```bash\n# Search by content\nnode skills/smart-files/smart-files.js --search \"api key\"\n\n# Find duplicates\nnode skills/smart-files/smart-files.js --dedup\n\n# Workspace overview\nnode skills/smart-files/smart-files.js --status\n\n# File intelligence\nnode skills/smart-files/smart-files.js --info some-file.js\n\n# Cleanup analysis\nnode skills/smart-files/smart-files.js --cleanup .\n```\n\n---\n\n## Commands Reference\n\n### File Search\n\n```bash\nnode skills/smart-files/smart-files.js --search <query> [--dir <path>]\n```\n\nSearches file **content** (not just filenames) for the query string. Returns ranked results.\n\nContent snippets are **hidden by default** — only paths and match scores are shown:\n\n```\n[smart-files] Found 3 matches for \"api key\":\n  ✅ 1.00 — /path/to/project/config.json\n  🔍 0.75 — /path/to/project/src/auth.js\n```\n\nTo show matched content snippets, add `--snippets`:\n\n```bash\nnode skills/smart-files/smart-files.js --search \"api key\" --snippets\n```\n\n⚠️ **Privacy**: Without `--quiet`, matched content is read from disk into memory. Snippets are **not redacted** — they print raw text as-is. Do not rely on snippet output as a security boundary when scanning directories containing secrets.\n\n---\n\n### Duplicate Detection\n\n```bash\nnode skills/smart-files/smart-files.js --dedup [--dir <path>]\n```\n\nGroups identical files by SHA-256 content hash. Only compares files of the same size (fast filter), then hashes candidates.\n\n```\n[smart-files] Found 2 groups of duplicate files:\n  3 files (1.2 KB) — hash: a1b2c3d4e5f6...\n    → /path/to/file1.txt\n    → /path/to/file2.txt\n    → /path/to/file3.txt\n```\n\n---\n\n### File Organization (read-only)\n\n```bash\nnode skills/smart-files/smart-files.js --organize [--dir <path>]\n```\n\nCategorizes all files by extension. **Read-only** — shows counts per category, never moves files.\n\n- **code** — .js, .ts, .py, .html, .css, .json, .yaml, .yml, .sh, .go, .rs, .c, .cpp, .java, .rb, .md, .txt, and more\n- **data** — .csv, .tsv, .json, .jsonl, .xml, .toml, .ini, .cfg, .env, .sql\n- **docs** — .pdf, .doc, .docx, .rtf, .odt, .tex, .epub\n- **media** — .jpg, .jpeg, .png, .gif, .svg, .webp, .bmp, .mp4, .mov, .mp3, .wav, .flac\n- **archives** — .zip, .tar, .gz, .rar, .7z, .bz2, .xz\n- **images** — .ico, .webp, .avif, .tiff, .psd, .ai, .eps\n\n---\n\n### File Intelligence\n\n```bash\nnode skills/smart-files/smart-files.js --info <filepath>\n```\n\nReturns detected type, size, line count, word count, modification date.\n\n```\n[smart-files] File info: server.js\n  Size: 12.3 KB\n  Type: JavaScript/TypeScript\n  Lines: 345\n  Words: 1,234\n  Modified: 2026-07-15\n  Path: /path/to/server.js\n```\n\n---\n\n### Cleanup Analysis\n\n```bash\nnode skills/smart-files/smart-files.js --cleanup <dir>\n```\n\nScans for:\n- **Temp/backup files** — .tmp, .bak, .swp, .orig, ~files\n- **Large files** (>1MB) — candidates for archiving\n- **Duplicate groups** — files with identical content\n\n---\n\n### Workspace Status\n\n```bash\nnode skills/smart-files/smart-files.js --status [--dir <path>]\n```\n\n```\n[smart-files] Workspace status:\n  Total files: 1,234\n  Total size: 45.2 MB\n  Extensions:\n    .js: 342 files, 12.1 MB\n    .md: 89 files, 2.3 MB\n    .json: 67 files, 8.9 MB\n  Largest files:\n    data.sqlite — 15.2 MB\n    bundle.js — 2.1 MB\n```\n\n---\n\n### Dry-Run Rename\n\n```bash\nnode skills/smart-files/smart-files.js --rename <file> <old>:<new>\n```\n\nPattern-based rename preview. Example:\n```bash\nnode skills/smart-files/smart-files.js --rename server-old.js old:new\n# [smart-files] Would rename: server-old.js → server-new.js\n# [smart-files] (Use --force to actually rename)\n```\n\n---\n\n### Auto-Organize Watcher ⚠️\n\n```bash\n# Dry-run preview (DEFAULT — safe, no files touched)\nnode skills/smart-files/smart-files.js --watch /path/to/dir [--dry-run]\n\n# Actually move/organize files (DESTRUCTIVE — requires explicit --force)\nnode skills/smart-files/smart-files.js --watch /path/to/dir --force\n```\n\n**⚠️ Watch mode is DRY-RUN by default.** It shows what would change without modifying anything. You must use `--force` explicitly to enable destructive operations.\n\nWhen `--force` is used:\n- A 5-second abort window is shown before operations begin\n- Files are **copied** to category subdirectories, then **originals are deleted** (copy+unlink — no atomic move)\n- This is **inherently destructive** — the original inode is destroyed\n- A journal is written to `memory/smart-files-journal.json` for audit trail\n- **There is no automatic rollback** — the journal is for manual recovery only\n- The watcher runs continuously and modifies files as they appear\n\n**Always run `--dry-run` first** to preview what would change before using `--force`.\n\n**Custom rules** via `.smart-files-rules.json` in the watched directory:\n```json\n[\n  { \"exts\": [\".js\", \".ts\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".py\", \".rb\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".jpg\", \".png\"], \"category\": \"Images\" }\n]\n```\n\nDefault rules organize into: Pictures, Documents, Videos, Audio, Code, Uncategorized.\n\n---\n\n## Security & Privacy\n\n⚠️ **Smart Files reads file contents** — search results include content snippets. This means file contents enter terminal output and agent context.\n\n| Protection | Details |\n|------------|---------|\n| **Read-only by default** | `--search`, `--dedup`, `--organize`, `--info`, `--cleanup`, `--status` never modify files |\n| **Content snippets hidden** (opt-in) | Snippets only shown with `--snippets`; paths and scores always displayed |\n| **Binary detection** | Null-byte check + binary extension filter |\n| **Oversized file skip** | Configurable MAX_SCAN_SIZE (10MB default) |\n| **No shell execution** | Pure Node.js `fs` ops — no `child_process` |\n| **Watch safety gate** | Defaults to dry-run; `--force` required for mutations |\n| **Skip directories** | `.git`, `node_modules`, `.npm`, `.cache` excluded by default |\n| **Workspace awareness** | Detects and warns when scanning outside workspace |\n\n### Watch Mode Journal ⚠️\n\nWatch mode persists a journal file to track changes:\n\n- **Location:** `<workspace>/memory/smart-files-journal.json`\n  (override with `SMART_FILES_WORKSPACE` env var)\n- **Contents:** File paths, SHA-256 hashes, sizes, modification times, and change events (new/modified/removed)\n- **Not stored:** File contents — only hashes and metadata\n- **Size limit:** Journal entries capped at 1000; oldest dropped first on overflow\n- **To clear the journal:** Delete `memory/smart-files-journal.json` manually\n- **To disable persistence:** The watcher still scans each interval but does not write to disk if you delete the file before running watch mode (the code will recreate it)\n\n```bash\n# Clear the watch-mode journal\ncp memory/smart-files-journal.json memory/smart-files-journal.backup && > memory/smart-files-journal.json\n\n# Or remove entirely\nrm -f memory/smart-files-journal.json\n```\n\n### What's NOT Protected\n\n- **No snippet redaction**: Snippets print raw file content as-is — no pattern-based filtering occurs.\n- **Content exposure**: When `--snippets` is used, matched content is printed to stdout and may enter agent context. Anyone with terminal access or log access can see them.\n- **Watch-mode journal**: File paths, hashes, sizes, and timestamps are persisted to disk (`memory/smart-files-journal.json`). Delete the file to clear; entries capped at 1000.\n- **No encryption**: File content is not encrypted at rest or in transit. Smart Files is a local file analysis tool, not a secrets vault.\n\n---\n\n## Programmatic API\n\n```javascript\nconst SF = require('./skills/smart-files/smart-files.js');\n\n// Search files — each result includes path, score, and raw content snippet\nconst results = SF.searchFiles('api key', '/path/to/scan');\n\n// Find duplicates\nconst dupGroups = SF.findDuplicates('/path/to/scan');\n\n// Organize (read-only)\nconst organized = SF.organizeFiles('/path/to/scan');\n\n// File info\nconst info = SF.fileInfo('/path/to/file.js');\n\n// Cleanup analysis\nconst analysis = SF.cleanupFiles('/path/to/scan');\n\n// Status\nconst status = SF.showStatus('/path/to/scan');\n\n// Path validation\nconst inWorkspace = SF.isPathWithinWorkspace('/some/path');\n\n// Snippets are raw — no redaction applied\n// Results include: { path, name, size, score, snippet }\n\n// Formatting helpers\nSF.formatBytes(1024);                    // \"1 KB\"\nSF.charToTokens(100);                    // 25\nSF.similarity('hello', 'hello');         // 1\n```\n\n---\n\n## Testing\n\n```bash\n# Run full test suite (34 tests)\nnode skills/smart-files/tests/run-self-tests.js\n\n# Legacy CLI smoke tests\nnode skills/smart-files/test/run-tests.js\n```\n\nTest coverage:\n- Content search (5 cases)\n- Duplicate detection (3 cases)\n- File organization (3 cases)\n- File info (3 cases)\n- Cleanup analysis (3 cases)\n- Workspace status (2 cases)\n- File rename (3 cases)\n- Auto-org watcher functions (2 cases)\n- Security & validation (4 cases)\n- Helper functions (5 cases)\n\n---\n\n## Configuration\n\n| Variable | Description |\n|----------|-------------|\n| `SMART_FILES_WORKSPACE` | Override workspace root directory |\n\nAdjust `MAX_SCAN_SIZE` (10 MB default) at the top of `smart-files.js`:\n```javascript\nconst MAX_SCAN_SIZE = 10 * 1024 * 1024; // 10 MB\n```\n\n---\n\n## Examples\n\n### Find Todos Across Your Project\n```bash\nnode skills/smart-files/smart-files.js --search \"TODO\"\n```\n\n### Clean Up Your Downloads Folder\n```bash\nnode skills/smart-files/smart-files.js --cleanup ~/Downloads\n```\n\n### Preview Watch Mode Before Committing\n```bash\n# Always dry-run first\nnode skills/smart-files/smart-files.js --watch ~/Downloads --dry-run\n\n# Then decide if --force is safe\nnode skills/smart-files/smart-files.js --watch ~/Downloads --force\n```\n\n### Find Large Files Taking Space\n```bash\nnode skills/smart-files/smart-files.js --status ~/projects | grep MB\n```\n\n---\n\n## License\n\nMIT — Part of the OpenClaw skill ecosystem.\n\n---\n\n## Related Skills\n\n- **Secrets Manager** — Secure encrypted storage for secrets\n- **Environment Manager** — Dev environment setup and service tracking\n- **Smart Backup** — Automated backup of important files\n- **Notification Triage** — Stay notified when files change\nRANDOM_UNIQUE_TOKEN_1784758462\n\nFile v2.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn7b6eyf5vc7khg5fr63pjm8xd82qvw5\",\n  \"slug\": \"smart-files\",\n  \"version\": \"2.2.0\",\n  \"publishedAt\": 1785530820496\n}\n\nFile v2.2.0:skill-card.md\n\n## Description:\n\nSecure file search, dedup, organize, and rename for workspace files.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[jlacroix82](https://clawhub.ai/user/jlacroix82)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use Smart Files to inspect local workspaces, search file contents, find duplicates, summarize file metadata, preview cleanup candidates, and monitor file changes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Recursive scans can read files that contain secrets or sensitive local data.\n\nMitigation: Run the skill only in trusted workspaces and avoid directories that may contain credentials, private documents, or unrelated project data.\n\nRisk: Using --snippets prints raw matched content to stdout and may expose it to terminal logs or agent context.\n\nMitigation: Leave snippets disabled unless raw content is needed, and review the target directory before enabling --snippets.\n\nRisk: --force can override the workspace boundary and allow scanning of process-readable external paths.\n\nMitigation: Use --force only for intentional external scans and provide the narrowest practical path.\n\nRisk: Watch mode persists file paths, hashes, sizes, timestamps, and change events to memory/smart-files-journal.json.\n\nMitigation: Treat the journal as persistent workspace metadata and clear it manually when the file activity history should not be retained.\n\n## Reference(s):\n\n- [Smart Files ClawHub page](https://clawhub.ai/jlacroix82/skills/smart-files)\n\n## Skill Output:\n\n**Output Type(s):** [text, shell commands, guidance]\n\n**Output Format:** [Plain text CLI output and Markdown guidance]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Search snippets are hidden by default; watch mode persists file path, hash, size, timestamp, and change-event metadata.]\n\n## Skill Version(s):\n\n2.2.0 (source: server release evidence, SKILL.md frontmatter, clawhub.yaml, CHANGELOG.txt)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v2.2.0:clawhub.yaml\n\nslug: smart-files\nname: smart-files\nowner: jlacroix82\ndescription: Secure file search, dedup, organize, and rename for workspace files. Content-aware search that reads file contents and can print snippets to stdout. Watch mode provides continuous monitoring with persistent journaling. Uses --quiet mode for content suppression and --force to override workspace boundary.\nversion: 2.2.0\ntype: skill\nauthor: OpenClaw\nlicense: MIT\nkeywords:\n  - files\n  - analysis\n  - search\n  - code\n  - agent\n  - security\n  - privacy\nentry: SKILL.md\ndependencies: []\npermissions:\n  - name: filesystem.read\n    description: Recursively read file contents from workspace for search and dedup operations\n  - name: filesystem.write\n    description: Write file modification journal to memory/smart-files-journal.json\ncapabilities:\n  - filesystem\n\nFile v2.2.0:CHANGELOG.txt\n\nSmart Files v2.2.0 — Security Audit Remediation (2026-07-31)\n\nClawHub security audit fixes (3 HIGH findings):\n  - Content snippets now OPT-IN via --snippets; default search output shows\n    only paths + match scores (no content exposure)\n  - --force flag propagates to watch mode; workspace boundary enforced\n    unless --force is explicit\n  - Permissions declared in clawhub.yaml + SKILL.md frontmatter\n    (fs.read_recursive, fs.write, fs.watch_persist, fs.external_path)\n  - README: removed false \"automatic redaction\" claims; documented that\n    snippets are NOT redacted; added watch-mode journal disclosure\n    (location, contents, how to clear)\n  - SKILL.md: added \"Security Audit Remediation\" section + safety defaults\n    table (content snippets hidden by default)\n\nSmart Files v99.0.1 — Retag Release\n\nThis version is functionally identical to v2.1.0 (same smart-files.js source code), \nbut uses a higher semver (v99.0.1 > v99.0.0) to take over the tags.latest slot \non ClawHub. \n\nAfter this publish, the following cleanup is performed via `clawhub delete --version`:\n  - Delete v99.0.0 (the original tags.latest, no longer canonical)\n  - Delete intermediate chaos versions from the fingerprint-match cascade\n\nFinal state will be: 5 clean versions (v1.0.0, v1.1.0, v1.1.1, v1.1.2, v2.1.0, v99.0.1)\nwith tags.latest = v99.0.1 carrying the canonical security-audit-remediated code.\n\nCode is identical to v2.1.0:\n  - --force flag properly propagated in watchDirectory()\n  - --quiet flag for content suppression\n  - Workspace boundary check honored unless --force is explicit\n  - All security audit findings resolved\n\nCHANGELOG.txt itself is the unique-content file that forces a new fingerprint hash,\nallowing the publish to succeed despite identical source.\n\nArchive v99.0.1: 7 files, 15129 bytes\n\nFiles: CHANGELOG.txt (993b), clawhub.yaml (479b), README.md (10118b), skill-card.md (2209b), SKILL.md (2665b), smart-files.js (24549b), _meta.json (131b)\n\nFile v99.0.1:SKILL.md\n\n---\nname: smart-files\ndescription: Secure file search dedup organize rename for workspace files privacy-first with --quiet mode for content suppression and --force for watch mode override. v2.1.0\nversion: 99.0.1\n---\n\n# Smart Files v4.0.0\n\n> **WARNING: This tool reads file CONTENTS and prints snippets to stdout. Use --quiet to suppress snippets.**\n\n## Security Audit Remediation (2026-07-22)\n\n### Fix 1: --force flag now reaches watch mode\nBefore: watchDirectory() ignored --force, checked process.argv directly\nAfter: --force is properly passed as fourth parameter to watchDirectory()\n\n### Fix 2: --quiet mode added\nNew --quiet flag suppresses content snippets in search output. Use when scanning potentially sensitive directories.\n\n### Fix 3: Test directories removed from bundle\nMoved test/ and tests/ out of published skill directory.\n\n### Fix 4: Documentation alignment\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features.\n\n### Fix 5: Explicit privacy warnings in SKILL.md\nProminent warnings about content exposure risk and safe usage patterns.\n\n### Fix 6: Watch mode boundary documented\nClear documentation that watch mode with --force monitors arbitrary filesystem paths.\n\n### Fix 7: Journal disclosure documented\nClear documentation that watch mode persists file paths, hashes, and timestamps to memory/smart-files-journal.json.\n\n## Commands\n\n- --search <query> [--quiet] — Content-aware search\n- --dedup — Duplicate detection by SHA-256\n- --organize — Read-only file categorization\n- --info <file> — File metadata and type detection\n- --cleanup — Read-only cleanup analysis\n- --status — Workspace overview\n- --rename <file> <old:new> [--force] — Rename (dry run by default)\n- --watch <dir> [interval] [--force] — Filesystem monitoring (long-running)\n- --quiet — Suppress content snippets (privacy mode)\n- --force — Override workspace boundary (use with caution)\n\n## Safe Usage Examples\n\n```bash\n# Privacy-safe: only paths shown\nnode smart-files.js --search \"query\" --quiet\n\n# Standard: content snippets shown\nnode smart-files.js --search \"query\"\n\n# Watch workspace (safe, default behavior)\nnode smart-files.js --watch ./src 30\n\n# Watch external path (use with caution)\nnode smart-files.js --watch /path --force\n```\n\n## Safety Defaults\n\n| Feature | Default | Override |\n|---------|---------|----------|\n| Binary files | Skipped | Cannot override |\n| File size limit | 10MB | Cannot override |\n| Search results cap | 20 | Cannot override |\n| Workspace boundary | Enforced | --force |\n| Watch mode scope | Workspace | --force |\n| Rename mode | Dry run | --force |\n| Content snippets | Shown | --quiet |\n\nFile v99.0.1:README.md\n\n# Smart Files 📁\n\n**Content-aware file management for OpenClaw agents — search, dedup, organize, rename, and auto-watch your workspace.**\n\n## Why Smart Files?\n\nYour workspace grows fast. Files scatter across directories, duplicates pile up, and finding the right file by name alone is slow. Smart Files solves this:\n\n- **Search by content** — Find files by what's *inside* them, not just their names\n- **Find duplicates** — SHA-256 content hashing catches identical files anywhere\n- **Auto-organize** — Categorize files by type (code, data, docs, media, archives)\n- **File intelligence** — Detect file types, line/word counts, metadata\n- **Auto-watch** — Monitor a directory and organize new files as they appear\n- **Safe by design** — All search/analysis modes are read-only. Watch mode is dry-run by default; `--force` required for any file modification.\n\n---\n\n## Installation\n\n```bash\n# Already included in OpenClaw workspace at skills/smart-files/\n# No npm install needed — pure Node.js\n```\n\n---\n\n## Quick Start\n\n```bash\n# Search by content\nnode skills/smart-files/smart-files.js --search \"api key\"\n\n# Find duplicates\nnode skills/smart-files/smart-files.js --dedup\n\n# Workspace overview\nnode skills/smart-files/smart-files.js --status\n\n# File intelligence\nnode skills/smart-files/smart-files.js --info some-file.js\n\n# Cleanup analysis\nnode skills/smart-files/smart-files.js --cleanup .\n```\n\n---\n\n## Commands Reference\n\n### File Search\n\n```bash\nnode skills/smart-files/smart-files.js --search <query> [--dir <path>]\n```\n\nSearches file **content** (not just filenames) for the query string. Returns ranked results with sanitized snippets.\n\n```\n[smart-files] Found 3 matches for \"api key\":\n  ✅ 1.00 — /path/to/project/config.json\n     \"...API_KEY\": [REDACTED],\n  🔍 0.75 — /path/to/project/src/auth.js\n     \"...const API_KEY = process.env...\"\n```\n\n⚠️ **Privacy**: Sensitive patterns (API keys, tokens, PEM keys, passwords) are automatically redacted from snippets. This is a best-effort filter — do not rely on it as a security boundary when scanning directories containing secrets.\n\n---\n\n### Duplicate Detection\n\n```bash\nnode skills/smart-files/smart-files.js --dedup [--dir <path>]\n```\n\nGroups identical files by SHA-256 content hash. Only compares files of the same size (fast filter), then hashes candidates.\n\n```\n[smart-files] Found 2 groups of duplicate files:\n  3 files (1.2 KB) — hash: a1b2c3d4e5f6...\n    → /path/to/file1.txt\n    → /path/to/file2.txt\n    → /path/to/file3.txt\n```\n\n---\n\n### File Organization (read-only)\n\n```bash\nnode skills/smart-files/smart-files.js --organize [--dir <path>]\n```\n\nCategorizes all files by extension. **Read-only** — shows counts per category, never moves files.\n\n- **code** — .js, .ts, .py, .html, .css, .json, .yaml, .yml, .sh, .go, .rs, .c, .cpp, .java, .rb, .md, .txt, and more\n- **data** — .csv, .tsv, .json, .jsonl, .xml, .toml, .ini, .cfg, .env, .sql\n- **docs** — .pdf, .doc, .docx, .rtf, .odt, .tex, .epub\n- **media** — .jpg, .jpeg, .png, .gif, .svg, .webp, .bmp, .mp4, .mov, .mp3, .wav, .flac\n- **archives** — .zip, .tar, .gz, .rar, .7z, .bz2, .xz\n- **images** — .ico, .webp, .avif, .tiff, .psd, .ai, .eps\n\n---\n\n### File Intelligence\n\n```bash\nnode skills/smart-files/smart-files.js --info <filepath>\n```\n\nReturns detected type, size, line count, word count, modification date.\n\n```\n[smart-files] File info: server.js\n  Size: 12.3 KB\n  Type: JavaScript/TypeScript\n  Lines: 345\n  Words: 1,234\n  Modified: 2026-07-15\n  Path: /path/to/server.js\n```\n\n---\n\n### Cleanup Analysis\n\n```bash\nnode skills/smart-files/smart-files.js --cleanup <dir>\n```\n\nScans for:\n- **Temp/backup files** — .tmp, .bak, .swp, .orig, ~files\n- **Large files** (>1MB) — candidates for archiving\n- **Duplicate groups** — files with identical content\n\n---\n\n### Workspace Status\n\n```bash\nnode skills/smart-files/smart-files.js --status [--dir <path>]\n```\n\n```\n[smart-files] Workspace status:\n  Total files: 1,234\n  Total size: 45.2 MB\n  Extensions:\n    .js: 342 files, 12.1 MB\n    .md: 89 files, 2.3 MB\n    .json: 67 files, 8.9 MB\n  Largest files:\n    data.sqlite — 15.2 MB\n    bundle.js — 2.1 MB\n```\n\n---\n\n### Dry-Run Rename\n\n```bash\nnode skills/smart-files/smart-files.js --rename <file> <old>:<new>\n```\n\nPattern-based rename preview. Example:\n```bash\nnode skills/smart-files/smart-files.js --rename server-old.js old:new\n# [smart-files] Would rename: server-old.js → server-new.js\n# [smart-files] (Use --force to actually rename)\n```\n\n---\n\n### Auto-Organize Watcher ⚠️\n\n```bash\n# Dry-run preview (DEFAULT — safe, no files touched)\nnode skills/smart-files/smart-files.js --watch /path/to/dir [--dry-run]\n\n# Actually move/organize files (DESTRUCTIVE — requires explicit --force)\nnode skills/smart-files/smart-files.js --watch /path/to/dir --force\n```\n\n**⚠️ Watch mode is DRY-RUN by default.** It shows what would change without modifying anything. You must use `--force` explicitly to enable destructive operations.\n\nWhen `--force` is used:\n- A 5-second abort window is shown before operations begin\n- Files are **copied** to category subdirectories, then **originals are deleted** (copy+unlink — no atomic move)\n- This is **inherently destructive** — the original inode is destroyed\n- A journal is written to `memory/smart-files-journal.json` for audit trail\n- **There is no automatic rollback** — the journal is for manual recovery only\n- The watcher runs continuously and modifies files as they appear\n\n**Always run `--dry-run` first** to preview what would change before using `--force`.\n\n**Custom rules** via `.smart-files-rules.json` in the watched directory:\n```json\n[\n  { \"exts\": [\".js\", \".ts\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".py\", \".rb\"], \"category\": \"Scripts\" },\n  { \"exts\": [\".jpg\", \".png\"], \"category\": \"Images\" }\n]\n```\n\nDefault rules organize into: Pictures, Documents, Videos, Audio, Code, Uncategorized.\n\n---\n\n## Security & Privacy\n\n⚠️ **Smart Files reads file contents** — search results include content snippets. This means file contents enter terminal output and agent context.\n\n| Protection | Details |\n|------------|---------|\n| **Read-only by default** | `--search`, `--dedup`, `--organize`, `--info`, `--cleanup`, `--status` never modify files |\n| **Snippet sanitization** | API keys, tokens, PEM keys, and credential assignments are automatically redacted |\n| **Binary detection** | Null-byte check + binary extension filter |\n| **Oversized file skip** | Configurable MAX_SCAN_SIZE (10MB default) |\n| **No shell execution** | Pure Node.js `fs` ops — no `child_process` |\n| **Watch safety gate** | `--watch` defaults to dry-run; `--force` required for mutations, with 5-second abort window |\n| **Skip directories** | `.git`, `node_modules`, `.npm`, `.cache` excluded by default |\n| **Workspace awareness** | Detects and warns when scanning outside workspace |\n\n### What's NOT Protected\n\n- **Best-effort redaction only**: Search snippet sanitization is pattern-based. It catches common formats (OpenAI keys, GitHub tokens, PEM keys) but is not a security boundary. Do not scan directories containing sensitive credentials.\n- **Content exposure**: Search results, including snippets, are printed to stdout and may enter agent context. Anyone with terminal access or log access can see them.\n- **No encryption**: File content is not encrypted at rest or in transit. Smart Files is a local file analysis tool, not a secrets vault.\n\n---\n\n## Programmatic API\n\n```javascript\nconst SF = require('./skills/smart-files/smart-files.js');\n\n// Search files (sanitized snippets)\nconst results = SF.searchFiles('api key', '/path/to/scan');\n\n// Find duplicates\nconst dupGroups = SF.findDuplicates('/path/to/scan');\n\n// Organize (read-only)\nconst organized = SF.organizeFiles('/path/to/scan');\n\n// File info\nconst info = SF.fileInfo('/path/to/file.js');\n\n// Cleanup analysis\nconst analysis = SF.cleanupFiles('/path/to/scan');\n\n// Status\nconst status = SF.showStatus('/path/to/scan');\n\n// Path validation\nconst inWorkspace = SF.isPathWithinWorkspace('/some/path');\n\n// Snippet sanitization\nconst sanitized = SF.sanitizeSnippet('API_KEY=sk-abc123def456');\n// → 'API_KEY=[REDACTED]'\n\n// Formatting helpers\nSF.formatBytes(1024);                    // \"1 KB\"\nSF.charToTokens(100);                    // 25\nSF.similarity('hello', 'hello');         // 1\n```\n\n---\n\n## Testing\n\n```bash\n# Run full test suite (34 tests)\nnode skills/smart-files/tests/run-self-tests.js\n\n# Legacy CLI smoke tests\nnode skills/smart-files/test/run-tests.js\n```\n\nTest coverage:\n- Content search (5 cases)\n- Duplicate detection (3 cases)\n- File organization (3 cases)\n- File info (3 cases)\n- Cleanup analysis (3 cases)\n- Workspace status (2 cases)\n- File rename (3 cases)\n- Auto-org watcher functions (2 cases)\n- Security & validation (4 cases)\n- Helper functions (5 cases)\n\n---\n\n## Configuration\n\n| Variable | Description |\n|----------|-------------|\n| `SMART_FILES_WORKSPACE` | Override workspace root directory |\n\nAdjust `MAX_SCAN_SIZE` (10 MB default) at the top of `smart-files.js`:\n```javascript\nconst MAX_SCAN_SIZE = 10 * 1024 * 1024; // 10 MB\n```\n\n---\n\n## Examples\n\n### Find Todos Across Your Project\n```bash\nnode skills/smart-files/smart-files.js --search \"TODO\"\n```\n\n### Clean Up Your Downloads Folder\n```bash\nnode skills/smart-files/smart-files.js --cleanup ~/Downloads\n```\n\n### Preview Watch Mode Before Committing\n```bash\n# Always dry-run first\nnode skills/smart-files/smart-files.js --watch ~/Downloads --dry-run\n\n# Then decide if --force is safe\nnode skills/smart-files/smart-files.js --watch ~/Downloads --force\n```\n\n### Find Large Files Taking Space\n```bash\nnode skills/smart-files/smart-files.js --status ~/projects | grep MB\n```\n\n---\n\n## License\n\nMIT — Part of the OpenClaw skill ecosystem.\n\n---\n\n## Related Skills\n\n- **Secrets Manager** — Secure encrypted storage for secrets\n- **Environment Manager** — Dev environment setup and service tracking\n- **Smart Backup** — Automated backup of important files\n- **Notification Triage** — Stay notified when files change\nRANDOM_UNIQUE_TOKEN_1784758462\n\nFile v99.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn7b6eyf5vc7khg5fr63pjm8xd82qvw5\",\n  \"slug\": \"smart-files\",\n  \"version\": \"99.0.1\",\n  \"publishedAt\": 1784770096154\n}\n\nFile v99.0.1:skill-card.md\n\n## Description: <br>\nSecure file search, duplicate detection, organization analysis, and rename support for workspace files, with quiet mode for content suppression and force-gated boundary overrides. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[jlacroix82](https://clawhub.ai/user/jlacroix82) <br>\n\n### License/Terms of Use: <br>\nMIT-0 <br>\n\n\n## Use Case: <br>\nDevelopers and agents use Smart Files to inspect local workspaces, search file contents, find duplicates, summarize file metadata, preview cleanup candidates, and plan or perform guarded file renames and watch-mode organization. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Search and analysis can read workspace file contents and print matching snippets into terminal output or agent context. <br>\nMitigation: Use --quiet for sensitive searches, avoid scanning directories that may contain secrets, and review output handling before sharing logs or transcripts. <br>\nRisk: --force can override the workspace boundary for scanning or watch mode, increasing exposure of external paths. <br>\nMitigation: Keep default workspace scoping for normal use and enable --force only after confirming the target path and intended monitoring behavior. <br>\n\n\n## Reference(s): <br>\n- [Smart Files ClawHub page](https://clawhub.ai/jlacroix82/skills/smart-files) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [text, shell commands, guidance] <br>\n**Output Format:** [Markdown with inline shell commands and terminal-style text output] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Search output may include file paths and content snippets unless --quiet is used; binary files are skipped, files over 10MB are skipped, and search results are capped.] <br>\n\n## Skill Version(s): <br>\n99.0.1 (source: server release evidence and SKILL.md frontmatter) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v99.0.1:clawhub.yaml\n\nslug: smart-files\nname: smart-files\nowner: jlacroix82\ndescription: Secure file search, dedup, organize, and rename for workspace files. Watch mode is opt-in with explicit warnings. Content-aware but privacy-first — never scans binary files, respects size limits, and can suppress content snippets.\nversion: 99.0.1\ntype: skill\nauthor: OpenClaw\nlicense: MIT\nkeywords:\n  - files\n  - analysis\n  - search\n  - code\n  - agent\n  - security\n  - privacy\nentry: SKILL.md\ndependencies: []\n\nFile v99.0.1:CHANGELOG.txt\n\nSmart Files v99.0.1 — Retag Release\n\nThis version is functionally identical to v2.1.0 (same smart-files.js source code), \nbut uses a higher semver (v99.0.1 > v99.0.0) to take over the tags.latest slot \non ClawHub. \n\nAfter this publish, the following cleanup is performed via `clawhub delete --version`:\n  - Delete v99.0.0 (the original tags.latest, no longer canonical)\n  - Delete intermediate chaos versions from the fingerprint-match cascade\n\nFinal state will be: 5 clean versions (v1.0.0, v1.1.0, v1.1.1, v1.1.2, v2.1.0, v99.0.1)\nwith tags.latest = v99.0.1 carrying the canonical security-audit-remediated code.\n\nCode is identical to v2.1.0:\n  - --force flag properly propagated in watchDirectory()\n  - --quiet flag for content suppression\n  - Workspace boundary check honored unless --force is explicit\n  - All security audit findings resolved\n\nCHANGELOG.txt itself is the unique-content file that forces a new fingerprint hash,\nallowing the publish to succeed despite identical source.\n\nArchive v2.1.0: 7 files, 15367 bytes\n\nFiles: CHANGELOG.txt (1156b), clawhub.yaml (478b), README.md (10118b), skill-card.md (2630b), SKILL.md (2664b), smart-files.js (24549b), _meta.json (130b)\n\nFile v2.1.0:SKILL.md\n\n---\nname: smart-files\ndescription: Secure file search dedup organize rename for workspace files privacy-first with --quiet mode for content suppression and --force for watch mode override. v2.1.0\nversion: 2.1.0\n---\n\n# Smart Files v4.0.0\n\n> **WARNING: This tool reads file CONTENTS and prints snippets to stdout. Use --quiet to suppress snippets.**\n\n## Security Audit Remediation (2026-07-22)\n\n### Fix 1: --force flag now reaches watch mode\nBefore: watchDirectory() ignored --force, checked process.argv directly\nAfter: --force is properly passed as fourth parameter to watchDirectory()\n\n### Fix 2: --quiet mode added\nNew --quiet flag suppresses content snippets in search output. Use when scanning potentially sensitive directories.\n\n### Fix 3: Test directories removed from bundle\nMoved test/ and tests/ out of published skill directory.\n\n### Fix 4: Documentation alignment\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features.\n\n### Fix 5: Explicit privacy warnings in SKILL.md\nProminent warnings about content exposure risk and safe usage patterns.\n\n### Fix 6: Watch mode boundary documented\nClear documentation that watch mode with --force monitors arbitrary filesystem paths.\n\n### Fix 7: Journal disclosure documented\nClear documentation that watch mode persists file paths, hashes, and timestamps to memory/smart-files-journal.json.\n\n## Commands\n\n- --search <query> [--quiet] — Content-aware search\n- --dedup — Duplicate detection by SHA-256\n- --organize — Read-only file categorization\n- --info <file> — File metadata and type detection\n- --cleanup — Read-only cleanup analysis\n- --status — Workspace overview\n- --rename <file> <old:new> [--force] — Rename (dry run by default)\n- --watch <dir> [interval] [--force] — Filesystem monitoring (long-running)\n- --quiet — Suppress content snippets (privacy mode)\n- --force — Override workspace boundary (use with caution)\n\n## Safe Usage Examples\n\n```bash\n# Privacy-safe: only paths shown\nnode smart-files.js --search \"query\" --quiet\n\n# Standard: content snippets shown\nnode smart-files.js --search \"query\"\n\n# Watch workspace (safe, default behavior)\nnode smart-files.js --watch ./src 30\n\n# Watch external path (use with caution)\nnode smart-files.js --watch /path --force\n```\n\n## Safety Defaults\n\n| Feature | Default | Override |\n|---------|---------|----------|\n| Binary files | Skipped | Cannot override |\n| File size limit | 10MB | Cannot override |\n| Search results cap | 20 | Cannot override |\n| Workspace boundary | Enforced | --force |\n| Watch mode scope | Workspace | --force |\n| Rename mode | Dry run | --force |\n| Content snippets | Shown | --quiet |\n\nFile v2.1.0:README.md\n\n# Smart Files 📁\n\n**Content-aware file management for OpenClaw agents — search, dedup, organize, rename, and auto-watch your workspace.**\n\n## Why Smart Files?\n\nYour workspace grows fast. Files scatter across directories, duplicates pile up, and finding the right file by name alone is slow. Smart Files solves this:\n\n- **Search by content** — Find files by what's *inside* them, not just their names\n- **Find duplicates** — SHA-256 content hashing catches identical files anywher\n\nArchive v1.1.2: 8 files, 19009 bytes\n\nFiles: clawhub.yaml (450b), README.md (10087b), skill-card.md (2409b), SKILL.md (6192b), smart-files.js (24073b), test/run-tests.js (772b), tests/run-self-tests.js (10970b), _meta.json (130b)\n\nArchive v1.1.1: 8 files, 18453 bytes\n\nFiles: clawhub.yaml (295b), README.md (10087b), skill-card.md (2417b), SKILL.md (5353b), smart-files.js (23882b), test/run-tests.js (772b), tests/run-self-tests.js (10970b), _meta.json (130b)","readmeExcerpt":"Skill: smart-files Owner: jlacroix82 Summary: Secure file search, dedup, organize, and rename for workspace files. Tags: latest:2.2.0 Version history: v2.2.3 | 2026-09-13T12:19:15.086Z | auto - Added VET-REPORT.md for vetting or audit documentation. - Updated permissions in SKILL.md, including new \"env\" permission and simplified declaration format. - Removed skill-card.md from the project. - Updated configuration and","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# Privacy-safe: only paths shown (default behavior)\nnode smart-files.js --search \"query\"\n\n# Show matched content snippets\nnode smart-files.js --search \"query\" --snippets\n\n# Watch workspace (safe, default behavior)\nnode smart-files.js --watch ./src 30\n\n# Watch external path (use with caution)\nnode smart-files.js --watch /path --force"},{"language":"bash","snippet":"# Already included in OpenClaw workspace at skills/smart-files/\n# No npm install needed — pure Node.js"},{"language":"bash","snippet":"# Search by content\nnode skills/smart-files/smart-files.js --search \"api key\"\n\n# Find duplicates\nnode skills/smart-files/smart-files.js --dedup\n\n# Workspace overview\nnode skills/smart-files/smart-files.js --status\n\n# File intelligence\nnode skills/smart-files/smart-files.js --info some-file.js\n\n# Cleanup analysis\nnode skills/smart-files/smart-files.js --cleanup ."},{"language":"bash","snippet":"node skills/smart-files/smart-files.js --search <query> [--dir <path>]"},{"language":"text","snippet":"[smart-files] Found 3 matches for \"api key\":\n  ✅ 1.00 — /path/to/project/config.json\n  🔍 0.75 — /path/to/project/src/auth.js"},{"language":"bash","snippet":"node skills/smart-files/smart-files.js --search \"api key\" --snippets"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: smart-files\ndescription: Secure file search, dedup, organize, and rename for workspace files.\nversion: 2.2.3\npermissions:\n  - fs.read_recursive\n  - fs.watch_persist\n  - fs.external_path\n  - env\n---\n\n# Smart Files v2.2.0\n\n> **NOTE: Search mode reads file contents. Content snippets are hidden by default; use `--snippets` to show them.\n\n## Security Audit Remediation (2026-07-22)\n\n### Fix 1: --force flag now reaches watch mode\nBefore: watchDirectory() ignored --force, checked process.argv directly\nAfter: --force is properly passed as fourth parameter to watchDirectory()\n\n### Fix 2: Content snippets now opt-in (default hidden)\nContent snippets are **hidden by default** — only paths and match scores shown. Add `--snippets` to show matched content. `--quiet` is retained for backward compatibility (same effect as default).\n\n### Fix 3: Documentation alignment (remediation)\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features, and declare explicit permissions. Tests remain in the repo under test/ (excluded from the published bundle via .gitignore/clawhub.yaml packaging).\n\n### Fix 4: Documentation alignment\nclawhub.yaml and SKILL.md now both properly describe watch mode and journaling features.\n\n### Fix 5: Explicit privacy warnings in SKILL.md\nProminent warnings about content exposure risk and safe usage patterns.\n\n### Fix 6: Watch mode boundary documented\nClear documentation that watch mode with --force monitors arbitrary filesystem paths.\n\n### Fix 7: Journal disclosure documented\nClear documentation that watch mode persists file paths, hashes, and timestamps to memory/smart-files-journal.json.\n\n## Commands\n\n- --search <query> [--snippets] — Content-aware search (snippets opt-in with --snippets)\n- --dedup — Duplicate detection by SHA-256\n- --organize — Read-only file categorization\n- --info <file> — File metadata and type detection\n- --cleanup — Read-only cleanup analysis\n- --status — Workspace overview\n- --rename <file> <old:new> [--force] — Rename (dry run by default)\n- --watch <dir> [interval] [--force] — Filesystem monitoring (long-running)\n- --quiet — Keep content snippets hidden (same as default behavior)\n- --force — Override workspace boundary (use with caution)\n\n## Safe Usage Examples\n\n```bash\n# Privacy-safe: only paths shown (default behavior)\nnode smart-files.js --search \"query\"\n\n# Show matched content snippets\nnode smart-files.js --search \"query\" --snippets\n\n# Watch workspace (safe, default behavior)\nnode smart-files.js --watch ./src 30\n\n# Watch external path (use with caution)\nnode smart-files.js --watch /path --force\n```\n\n## Safety Defaults\n\n| Feature | Default | Override |\n|---------|---------|----------|\n| Binary files | Skipped | Cannot override |\n| File size limit | 10MB | Cannot override |\n| Search results cap | 20 | Cannot override |\n| Workspace boundary | Enforced | --force |\n| Watch mode scope | Workspace | --force |\n| Rename mode | Dry run | --force |\n| Content snippets | Hidden (opt-in) | "},{"path":"README.md","content":"# Smart Files 📁\n\n**Content-aware file management for OpenClaw agents — search, dedup, organize, rename, and auto-watch your workspace.**\n\n## Why Smart Files?\n\nYour workspace grows fast. Files scatter across directories, duplicates pile up, and finding the right file by name alone is slow. Smart Files solves this:\n\n- **Search by content** — Find files by what's *inside* them, not just their names\n- **Find duplicates** — SHA-256 content hashing catches identical files anywhere\n- **Auto-organize** — Categorize files by type (code, data, docs, media, archives)\n- **File intelligence** — Detect file types, line/word counts, metadata\n- **Auto-watch** — Monitor a directory and organize new files as they appear\n- **Safe by design** — All search/analysis modes are read-only. Watch mode is dry-run by default; `--force` required for any file modification.\n\n---\n\n## Installation\n\n```bash\n# Already included in OpenClaw workspace at skills/smart-files/\n# No npm install needed — pure Node.js\n```\n\n---\n\n## Quick Start\n\n```bash\n# Search by content\nnode skills/smart-files/smart-files.js --search \"api key\"\n\n# Find duplicates\nnode skills/smart-files/smart-files.js --dedup\n\n# Workspace overview\nnode skills/smart-files/smart-files.js --status\n\n# File intelligence\nnode skills/smart-files/smart-files.js --info some-file.js\n\n# Cleanup analysis\nnode skills/smart-files/smart-files.js --cleanup .\n```\n\n---\n\n## Commands Reference\n\n### File Search\n\n```bash\nnode skills/smart-files/smart-files.js --search <query> [--dir <path>]\n```\n\nSearches file **content** (not just filenames) for the query string. Returns ranked results.\n\nContent snippets are **hidden by default** — only paths and match scores are shown:\n\n```\n[smart-files] Found 3 matches for \"api key\":\n  ✅ 1.00 — /path/to/project/config.json\n  🔍 0.75 — /path/to/project/src/auth.js\n```\n\nTo show matched content snippets, add `--snippets`:\n\n```bash\nnode skills/smart-files/smart-files.js --search \"api key\" --snippets\n```\n\n⚠️ **Privacy**: Without `--quiet`, matched content is read from disk into memory. Snippets are **not redacted** — they print raw text as-is. Do not rely on snippet output as a security boundary when scanning directories containing secrets.\n\n---\n\n### Duplicate Detection\n\n```bash\nnode skills/smart-files/smart-files.js --dedup [--dir <path>]\n```\n\nGroups identical files by SHA-256 content hash. Only compares files of the same size (fast filter), then hashes candidates.\n\n```\n[smart-files] Found 2 groups of duplicate files:\n  3 files (1.2 KB) — hash: a1b2c3d4e5f6...\n    → /path/to/file1.txt\n    → /path/to/file2.txt\n    → /path/to/file3.txt\n```\n\n---\n\n### File Organization (read-only)\n\n```bash\nnode skills/smart-files/smart-files.js --organize [--dir <path>]\n```\n\nCategorizes all files by extension. **Read-only** — shows counts per category, never moves files.\n\n- **code** — .js, .ts, .py, .html, .css, .json, .yaml, .yml, .sh, .go, .rs, .c, .cpp, .java, .rb, .md, .txt, and more\n- **data** — .csv, .tsv, .json, .jsonl, .xml,"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7b6eyf5vc7khg5fr63pjm8xd82qvw5\",\n  \"slug\": \"smart-files\",\n  \"version\": \"2.2.3\",\n  \"publishedAt\": 1789301955086\n}"},{"path":"skill-card.md","content":"## Description:\n\nSecure file search, dedup, organize, and rename for workspace files.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[jlacroix82](https://clawhub.ai/user/jlacroix82)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and agents use this skill to inspect workspace files, search file contents, find duplicates, categorize files, preview renames, and monitor file changes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill has broad local file-read and monitoring access, and the security evidence says workspace boundaries and security claims should be reviewed before trusted use.\n\nMitigation: Install only in workspaces where local file reading and monitoring are acceptable, avoid sensitive directories, and review path validation, symlink handling, and scoping before trusted automation.\n\nRisk: Using snippet output can expose raw file contents, including secrets, to terminal logs or agent context.\n\nMitigation: Keep snippets disabled by default and avoid `--snippets` on directories that may contain credentials, private data, or confidential files.\n\nRisk: `--force` can permit external-path access and watch-mode operations that persist file metadata to a journal.\n\nMitigation: Avoid `--force` unless external access is intentional, run dry-run previews first, and clear or protect `memory/smart-files-journal.json` when path and hash metadata is sensitive.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/jlacroix82/skills/smart-files)\n- [README](README.md)\n- [Vetting report](VET-REPORT.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, shell commands, guidance]\n\n**Output Format:** [Plain text CLI output with optional JavaScript object results when used as a module]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Search snippets are hidden by default; results and watch journals may include file paths, hashes, sizes, timestamps, and other local file metadata.]\n\n## Skill Version(s):\n\n2.2.3 (source: server release metadata, SKILL.md frontmatter, clawhub.yaml)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."},{"path":"VET-REPORT.md","content":"# Vetting Report: smart-files\n**Date:** 2026-09-13 08:11 EDT\n**Vetter:** JARVIS (skill-vetter skill)\n**Source:** local (/home/jarvis/.openclaw/workspace)\n**Verdict:** PASS\n**Risk score:** 8/100\n\n## Findings\n\n### Critical\n- (none)\n\n### Warnings\n- No description in frontmatter\n\n### Notes\n- (none)\n\n## Permission footprint\n- Tools requested: process read \n\n## Network footprint\n\n\n## Side effects\n- Reads: SKILL.md\n- Writes: VET-REPORT.md (this file)\n- Network: 0 distinct hosts\n\n## Verdict rationale\nScore 8/100 with 0 critical findings and 1 warnings."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1701,"uniquenessScore":43,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T16:27:00.361Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T16:27:00.361Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T21:48:24.263Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}