@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/housekeep-files/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: housekeep-files
+description: >
+  Copy-not-move organizer for document trees: hash inventory, dry run,
+  labeled copies, search catalog, verify every source survived. Use when
+  "organize my Downloads", "sort my company folders", or "file my receipts".
+  Repo cleanup → workflow-housekeep.
+license: MIT
+---
+
+# housekeep-files — File the documents, keep every original
+
+**Degree of freedom: MIXED.** Which owner, area, and doc type a file belongs
+to, and which layout option fits the person `[HIGH freedom]`. The
+copy-not-move rule, the hash inventory before the first copy, and the
+verify gate `[LOW freedom — run exactly]`.
+
+Apply-now for one drifted **file tree**: a Downloads pile, a cloud folder
+named for one company that holds two, receipts spread across three places.
+The output is an added, labeled copy of the documents plus a catalog an
+agent can grep. The input tree is left complete. Retiring the duplicates
+later is a separate, human-run decision.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **housekeep-files** (this) | Personal / business document trees on disk or a synced drive |
+| `workflow-housekeep` | A git repository: README, dead artifacts, dependencies |
+| `housekeep-backlog` | Parked work register, not files |
+| `plan-data-integrity` | Database destructive-op safety |
+| `plan-secrets-audit` | Finding leaked keys; this skill only refuses to copy them |
+
+## How to reason (every file)
+
+1. **Owner** — which legal entity or person pays for or signs this? Two
+   companies are two sets of books, even when one person runs both; a CV
+   or an ID scan belongs to neither company.
+2. **Area** — company / finance / product / client / site / tax / identity.
+3. **Doc type and date** — invoice, receipt, contract, tax-return, payroll,
+   registration, lease, cv, brand, plan, correspondence, other. Date from
+   the filename first, then the parent folder, else `undated`.
+4. **Copy or index** — signing keys, credentials, media over the size cap,
+   installers: never copied, only cataloged where they already are.
+
+An ambiguous file goes to `90_inbox` with its best-guess tags. Guessing an
+owner wrong files company A's receipt under company B; `90_inbox` files it
+nowhere wrong.
+
+## Worked example
+
+> **Owner:** `Form 9 - Certificate.pdf` sits in a folder named for
+> company B; the form is company B's incorporation paper → `acme-uk`.
+> **Area / type:** company / registration; no date in the name → `undated`.
+> **Copy or index:** PDF, 80 KB → copy.
+> **Label:** `acme-uk_company_undated_registration__Form 9 - Certificate.pdf`
+> — original name kept after `__` so the old string still matches search.
+> **Catalog line:** entity, area, doc_type, tags `["acme","companies-house","incorporation"]`,
+> `original_path`, `canonical_path`, `sha256`, `persist: copied-source-kept`.
+> **Neighbor:** `AuthKey_XXXX.p8` in an app folder → `indexed-in-place`,
+> reason `secret`; the catalog records its folder, not its bytes.
+
+---
+
+## Phase 0 — Inventory the tree, then pick the layout with the human
+
+Read before moving anything: the top two levels of every source root,
+which folders already exist at the destination, and which names repeat
+in more than one place. Then offer the options below and let the person
+choose; each is a different tree, so the plan cannot be written first.
+
+### Option A — Root per owner (default)
+
+```
+<Drive>/<Owner-A>/   00_company  10_finance  20_<site-or-venture>  30_products  40_clients  90_inbox
+<Drive>/<Owner-B>/   00_company  10_finance  90_inbox
+<Drive>/_personal/   tax  identity  job-search  family
+```
+
+Best when owners are separate legal entities or the accountant for one
+must never see the other. Two or three levels deep. Numbered areas keep a
+fixed order without freezing IDs the way full Johnny.Decimal does.
+
+### Option B — One root, owners inside
+
+```
+<Drive>/Documents/<Owner-A>/…   <Drive>/Documents/<Owner-B>/…   <Drive>/Documents/_personal/…
+```
+
+Best when one root folder is already shared or synced and re-sharing is
+costly. Same area folders inside each owner.
+
+### Option C — PARA-lite for a single owner
+
+```
+<Drive>/10_projects  20_areas  30_resources  40_archive
+```
+
+Best for one person with no company split. Active work moves between
+projects and archive; areas hold the standing responsibilities.
+
+### Label and metadata options (combine with any layout)
+
+| Option | When |
+|---|---|
+| Catalog only (`_ai-catalog.jsonl`, names untouched) | Names already carry date and subject, or apps read files by name |
+| Catalog + prefix on vague names (`prefix=yes` rows) | Loose files like `Form 9.pdf`, `scan001.jpg`; original kept after `__` |
+| Folder rename only | Whole folders like `#projectX` → `30_products/project-x`, internals untouched |
+
+Why these and not cloud properties or hidden sidecars: cloud custom
+properties are API fields, not files; hidden sidecar folders often do not
+sync. A visible catalog plus an ASCII prefix is what a later agent on any
+machine can grep. Sources and the exact schema:
+[references/naming-and-catalog.md](references/naming-and-catalog.md).
+
+### Move instead of copy
+
+Only when the human states that the source tree may lose paths and the
+target is on the same volume. Even then run `inventory` first and `verify`
+after. The bundled scripts do not move; a move is a manual step the
+person performs after `verify` passes on the copies.
+
+## Phase 1 — Write `plan.tsv`  [HIGH freedom]
+
+One row per source folder or loose file. Tab-separated, header row:
+
+```
+source	destination	entity	area	project	doc_type	tags	prefix	catalog_root
+```
+
+- `source` — existing file or folder. A folder row copies its whole tree
+  under `destination`, internals unrenamed.
+- `entity` — short ASCII token per owner (`acme-uk`, `acme-sg`, `personal`).
+- `prefix` — `yes` only for loose files whose name says neither owner nor
+  date. Folder rows are `no`.
+- `tags` — comma-separated, English plus the person's own language, words
+  they would actually type: `acme,invoice,請求書`.
+- `catalog_root` — the owner root that gets a `_ai-catalog.jsonl`.
+- `exclude` (optional 10th column) — `;`-separated relative-path substrings
+  inside a folder row to catalog in place instead of copying: a code
+  checkout beside its own zip, a cache. `node_modules`, `.git`,
+  `__pycache__`, `.venv`, `.next`, `.cache` are always skipped.
+
+Keep dated expense month-folders and app folders exactly as named. Do not
+plan rows for RAW, video, camera-card dumps, or installers; list those
+folders in `count-only.txt` so the verify gate proves they were untouched.
+
+## Phase 2 — Inventory, dry run, apply, verify  [LOW freedom — this order]
+
+Windows (PowerShell 5.1+):
+
+```powershell
+$S = "$HOME\.cursor\skills\housekeep-files\scripts\housekeep-files.ps1"
+& $S -Mode inventory -Plan .\plan.tsv -Out .\work -CountOnly .\count-only.txt
+& $S -Mode dry-run   -Plan .\plan.tsv -Out .\work      # read work\preview.tsv, fix the plan, rerun
+& $S -Mode apply     -Plan .\plan.tsv -Out .\work
+& $S -Mode verify    -Plan .\plan.tsv -Out .\work -CountOnly .\count-only.txt
+```
+
+macOS / Linux (bash, `shasum` or `sha256sum`):
+
+```bash
+S="$HOME/.cursor/skills/housekeep-files/scripts/housekeep-files.sh"
+"$S" inventory plan.tsv work count-only.txt
+"$S" dry-run   plan.tsv work
+"$S" apply     plan.tsv work
+"$S" verify    plan.tsv work count-only.txt
+```
+
+What the scripts enforce, identically on both platforms:
+
+- `inventory` writes `work/inventory.csv` (path, bytes, sha256) for every
+  source file in the plan — hash for files that will be copied, size only
+  for in-place items so a streaming drive never downloads media — and
+  `work/count-only.csv` for the untouched folders. `apply` refuses to run
+  without it.
+- `dry-run` writes `work/preview.tsv` with one of `copy`,
+  `indexed-in-place` (reason `secret`, `excluded`, `artifact`, `ext`,
+  `size`), or `skipped-exists` per file, plus the proposed name. Nothing on
+  disk changes. A folder row that expands to thousands of files is a code
+  checkout to `exclude`, not a document set.
+- `apply` copies only when the destination path is absent, hashes the
+  copy, and marks a mismatch `failed` with the source untouched. It never
+  calls a delete. It appends `_ai-catalog.jsonl` at each `catalog_root`
+  and at `work/catalog.jsonl`, and drops a `_SEARCH.md` where none exists.
+- `verify` re-checks every inventory path (exists, same size), re-hashes
+  every copy, recounts every count-only folder, and exits non-zero on the
+  first missing file. Its `work/verify-report.txt` is the evidence.
+
+Leave a `README-MOVED.txt` in the old root naming the new roots and
+stating that the old tree was not removed.
+
+## Self-critique before reporting
+
+- **Inventory predates the first copy** — `inventory.csv` mtime is earlier
+  than the first `copied-source-kept` line.
+- **Zero deletes** — the scripts were run unmodified; `apply-log.tsv` has
+  no `removed` action; every `count-only` folder count is unchanged.
+- **Every source path in `inventory.csv` still exists** at its original
+  size — `verify` exit code 0, report listed.
+- **No secret gained a second copy** — every `.p8 / .p12 / keystore /
+  credentials` row reads `indexed-in-place`.
+- **Prefixed names keep the original after `__`**, and no new path exceeds
+  the length cap.
+- **Storage growth stated** — total bytes copied, so the human can decide
+  when to retire the originals.
+- **Nothing person-specific leaked into shared artifacts** — the catalog
+  holds paths and labels; the skill and its examples hold placeholders.
+
+## Output format
+
+1. **Layout chosen** — option letter, roots created, area folders
+2. **Counts** — copied | skipped-exists | indexed-in-place by reason | failed
+3. **Verify** — exit code, source paths checked, hashes matched,
+   count-only folders unchanged
+4. **Catalog** — where `_ai-catalog.jsonl` and `_SEARCH.md` landed, line count
+5. **Left for the human** — duplicates to retire later, `90_inbox` items
+
+The turn may end after `verify` exits 0 and the report is written; a
+non-zero verify is a finding to fix, never a reason to delete anything.

package/skills/housekeep-files/references/naming-and-catalog.md

@@ -0,0 +1,86 @@
+# Naming, catalog schema, and sources
+
+## Filename label
+
+Applied only to a copied file whose row has `prefix=yes` and whose name
+does not already start with a date (`20YYMMDD`, `20YY-MM`, `20YY_`) or an
+entity token. The original name is kept after `__`.
+
+```
+{entity}_{area}_{yyyy-mm-dd|yyyy-mm|undated}_{doc-type}__{original-file-name}
+```
+
+| Slot | Values |
+|---|---|
+| entity | short ASCII per legal entity or person, e.g. `acme-uk`, `acme-sg`, `personal` |
+| area | `company`, `finance`, `product`, `client`, `site`, `tax`, `identity`, `job`, `family`, `inbox` |
+| doc-type | `invoice`, `receipt`, `tax-return`, `payroll`, `contract`, `insurance`, `registration`, `lease`, `cv`, `seal`, `brand`, `plan`, `correspondence`, `statement`, `other` |
+| date | from the filename, else the parent folder name, else `undated` |
+
+Skip the prefix when the new full path would exceed the length cap
+(default 200 characters). Windows tools misbehave near 260; a synced drive
+adds its own folder depth on the other machine.
+
+Never rename inside an app or build folder: `google-services.json`,
+`assetlinks.json`, provisioning profiles, keystores are read by name.
+
+## What is never copied (indexed in place)
+
+| Reason | Rule |
+|---|---|
+| `secret` | path matches `credential`, `keystore`, `.p8`, `.p12`, `.pem`, `.key`, `.jks`, `mobileprovision`, `.cer`, `.der`, `certsigningrequest`, `.b64`, `service-account`, `client_secret`, `google-services.json`, `googleservice-info`, `oauth`, `private-key`, `backup_code`, `.env`, `play-publisher`, `apple-credentials`, `env-backups`, `recovery`, `2fa`, `mfa`, `totp`, `アクセスキー` |
+| `excluded` | relative path contains a substring from the row's `exclude` column |
+| `artifact` | path contains `node_modules`, `.git`, `__pycache__`, `.venv`, `.next`, or `.cache` |
+| `ext` | extension outside the document allowlist: `pdf doc docx xls xlsx xlsm ppt pptx csv txt md html htm xtx xml data zip jpg jpeg png heic svg gif webp rtf odt ods eml msg` |
+| `size` | larger than the cap (default 200 MB) |
+
+A second copy of a signing key is a second thing to rotate. A video is a
+Drive upload the human did not ask for. Both still get a catalog line so
+search finds where they already live.
+
+## Catalog line (`_ai-catalog.jsonl`, one JSON object per line)
+
+```json
+{"run":"2026-01-15T03:40:12Z","entity":"acme-uk","area":"company","project":"","doc_type":"registration",
+ "date":"undated","tags":["acme","companies-house","incorporation"],
+ "original_path":"D:\\Drive\\Old Mixed Folder\\Form 9 - Certificate.pdf",
+ "original_name":"Form 9 - Certificate.pdf",
+ "canonical_path":"D:\\Drive\\Acme_UK\\00_company\\acme-uk_company_undated_registration__Form 9 - Certificate.pdf",
+ "bytes":80123,"sha256":"…","persist":"copied-source-kept","reason":""}
+```
+
+`persist` ∈ `copied-source-kept` | `indexed-in-place` | `skipped-exists` |
+`failed`. The catalog stores paths and labels only; never file contents,
+account numbers, or key material.
+
+`_SEARCH.md` at each root tells a later agent: grep `_ai-catalog.jsonl`
+first, then the prefixed filename, then the original name after `__`.
+
+## Verify report
+
+`verify` fails on the first of: an inventory path missing or resized, a
+copy whose SHA-256 differs from the inventory, an in-place row whose file
+is gone, a count-only folder whose file count changed. The report lists
+each check with its count and the first offending path.
+
+## Sources
+
+- Multi-entity bookkeeping keeps one set of books per legal entity —
+  numetix.ai, "Multi-Entity Accounting for Service Firms".
+- Drive structure two to three levels deep, date-first names, quarterly
+  archive rather than delete — drdaveheath.com, "Google Drive folder
+  structure best practices (2026 guide)".
+- Johnny.Decimal caps each level at ten and freezes IDs — johnnydecimal.com
+  documentation; its forum's official stance is not to mix it with PARA.
+- Drive custom properties are API metadata capped at 124 bytes per
+  property, not files — developers.google.com Drive API "Add custom file
+  properties".
+- Tags embedded in filenames survive Dropbox and Google Drive sync; hidden
+  sidecar folders may not — docs.tagspaces.org "Organizing Files and
+  Folders with Tags".
+- Do not use robocopy `/MOV` or `/MIR` when avoiding data loss; robocopy
+  does not verify the copy by hash — learn.microsoft.com "Use Robocopy to
+  Preseed Files for DFS Replication".
+- Moving a folder inside My Drive keeps the file ID and share links;
+  inherited permissions change — Google Workspace Admin Help, "Moving
+  content from Drive shared folders".

package/skills/housekeep-files/scripts/housekeep-files.ps1

@@ -0,0 +1,360 @@
+<#
+FILE: housekeep-files.ps1
+PURPOSE: Copy-not-move document organizer with a hash inventory, dry run,
+         labeled copies, a JSONL catalog, and a verify gate. Windows twin of
+         housekeep-files.sh (same plan.tsv, same outputs).
+
+OVERVIEW:
+- inventory : sha256 + size of every source file in plan.tsv -> work\inventory.csv;
+              file counts of count-only folders -> work\count-only.csv
+- dry-run   : work\preview.tsv with the action per file; no disk change
+- apply     : Copy-Item only when the destination is absent, hash the copy,
+              append _ai-catalog.jsonl at each catalog_root and work\catalog.jsonl,
+              write apply-log.tsv. Never deletes.
+- verify    : every inventory path exists at the same size, every copy re-hashes
+              equal, every in-place file exists, count-only counts unchanged.
+              Exit 1 on the first failure. -> work\verify-report.txt
+
+DEPENDENCIES: Windows PowerShell 5.1 or PowerShell 7. No modules.
+
+USAGE:
+  .\housekeep-files.ps1 -Mode inventory -Plan plan.tsv -Out work -CountOnly count-only.txt
+  .\housekeep-files.ps1 -Mode dry-run   -Plan plan.tsv -Out work
+  .\housekeep-files.ps1 -Mode apply     -Plan plan.tsv -Out work
+  .\housekeep-files.ps1 -Mode verify    -Plan plan.tsv -Out work -CountOnly count-only.txt
+
+plan.tsv header (tab-separated; `exclude` is optional):
+  source  destination  entity  area  project  doc_type  tags  prefix  catalog_root  exclude
+  exclude = ';'-separated relative-path substrings to catalog in place instead of copying
+  (code checkouts, caches). node_modules/.git/__pycache__/.venv/.next/.cache are always skipped.
+
+NOTES:
+- There is no Remove-Item, Move-Item, or robocopy in this file by design.
+- -LiteralPath everywhere: folder names carry #, spaces, CJK, brackets.
+- Keep this file ASCII. Windows PowerShell 5.1 decodes a BOM-less script with the
+  ANSI code page, so a literal CJK or em-dash character breaks parsing (cp1252) or
+  silently garbles a pattern (cp932). Write non-ASCII as a regex \uXXXX escape.
+- Output files are UTF-8 without BOM so other tools and the bash twin read them.
+#>
+[CmdletBinding()]
+param(
+  [Parameter(Mandatory = $true)][ValidateSet('inventory', 'dry-run', 'apply', 'verify')][string]$Mode,
+  [Parameter(Mandatory = $true)][string]$Plan,
+  [Parameter(Mandatory = $true)][string]$Out,
+  [string]$CountOnly = '',
+  [int]$MaxMB = 200,
+  [int]$MaxPath = 200
+)
+
+Set-StrictMode -Version 2
+$ErrorActionPreference = 'Stop'
+$Utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+
+$DocExt = @('.pdf', '.doc', '.docx', '.xls', '.xlsx', '.xlsm', '.ppt', '.pptx', '.csv', '.txt', '.md',
+  '.html', '.htm', '.xtx', '.xml', '.data', '.zip', '.jpg', '.jpeg', '.png', '.heic', '.svg', '.gif',
+  '.webp', '.rtf', '.odt', '.ods', '.eml', '.msg')
+$SecretRe = 'credential|keystore|\.p8$|\.p12$|\.pem$|\.key$|\.jks$|mobileprovision|\.cer$|\.der$|certsigningrequest|\.b64$|service-account|client_secret|google-services\.json|googleservice-info|oauth|private-key|backup_code|\.env$|play-publisher|apple-credentials|env-backups|recovery|2fa|mfa|totp|\u30A2\u30AF\u30BB\u30B9\u30AD\u30FC'
+$ArtifactRe = '\\(node_modules|\.git|__pycache__|\.venv|\.next|\.cache)\\'
+$DatedNameRe = '^(20\d{6}|20\d{2}-\d{2}|20\d{2}_)'
+$RunStamp = (Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ')
+
+function Write-Utf8Lines([string]$Path, [string[]]$Lines) {
+  [System.IO.File]::WriteAllLines($Path, $Lines, $Utf8NoBom)
+}
+function Append-Utf8Lines([string]$Path, [string[]]$Lines) {
+  [System.IO.File]::AppendAllLines($Path, [string[]]$Lines, $Utf8NoBom)
+}
+function Get-Sha256([string]$LiteralPath) {
+  (Get-FileHash -LiteralPath $LiteralPath -Algorithm SHA256).Hash.ToLowerInvariant()
+}
+function Read-Tsv([string]$Path) {
+  $lines = [System.IO.File]::ReadAllLines($Path, [System.Text.Encoding]::UTF8) | Where-Object { $_.Trim() -ne '' }
+  $header = $lines[0].Split("`t")
+  $rows = @()
+  foreach ($line in $lines[1..($lines.Count - 1)]) {
+    if ($line.TrimStart().StartsWith('#')) { continue }
+    $cells = $line.Split("`t")
+    $row = @{}
+    for ($i = 0; $i -lt $header.Count; $i++) {
+      $val = ''
+      if ($i -lt $cells.Count) { $val = $cells[$i].Trim() }
+      $row[$header[$i].Trim()] = $val
+    }
+    $rows += , $row
+  }
+  return $rows
+}
+function Get-DateToken([string]$Name, [string]$ParentName) {
+  foreach ($candidate in @($Name, $ParentName)) {
+    if ([string]::IsNullOrEmpty($candidate)) { continue }
+    $m = [regex]::Match($candidate, '(20\d{2})[-_.]?(\d{2})[-_.]?(\d{2})(?!\d)')
+    if ($m.Success) {
+      $mo = [int]$m.Groups[2].Value; $d = [int]$m.Groups[3].Value
+      if ($mo -ge 1 -and $mo -le 12 -and $d -ge 1 -and $d -le 31) { return ('{0}-{1:00}-{2:00}' -f $m.Groups[1].Value, $mo, $d) }
+    }
+    $m = [regex]::Match($candidate, '(20\d{2})[-_]?(\d{2})(?!\d)')
+    if ($m.Success) {
+      $mo = [int]$m.Groups[2].Value
+      if ($mo -ge 1 -and $mo -le 12) { return ('{0}-{1:00}' -f $m.Groups[1].Value, $mo) }
+    }
+  }
+  return 'undated'
+}
+function Json-Escape([string]$s) {
+  if ($null -eq $s) { return '' }
+  return $s.Replace('\', '\\').Replace('"', '\"').Replace("`r", '\r').Replace("`n", '\n').Replace("`t", '\t')
+}
+function To-CatalogLine($item) {
+  $tags = @()
+  foreach ($t in ($item.tags -split ',')) { if ($t.Trim() -ne '') { $tags += ('"' + (Json-Escape $t.Trim()) + '"') } }
+  $fields = @(
+    ('"run":"' + $RunStamp + '"'),
+    ('"entity":"' + (Json-Escape $item.entity) + '"'),
+    ('"area":"' + (Json-Escape $item.area) + '"'),
+    ('"project":"' + (Json-Escape $item.project) + '"'),
+    ('"doc_type":"' + (Json-Escape $item.doc_type) + '"'),
+    ('"date":"' + $item.date + '"'),
+    ('"tags":[' + ($tags -join ',') + ']'),
+    ('"original_path":"' + (Json-Escape $item.source) + '"'),
+    ('"original_name":"' + (Json-Escape $item.name) + '"'),
+    ('"canonical_path":"' + (Json-Escape $item.canonical) + '"'),
+    ('"bytes":' + $item.bytes),
+    ('"sha256":"' + $item.sha256 + '"'),
+    ('"persist":"' + $item.persist + '"'),
+    ('"reason":"' + $item.reason + '"')
+  )
+  return '{' + ($fields -join ',') + '}'
+}
+
+# Expand plan rows into per-file items with a proposed action.
+function Expand-Plan($rows) {
+  $items = @()
+  foreach ($row in $rows) {
+    $src = $row['source']
+    if (-not (Test-Path -LiteralPath $src)) { Write-Warning "plan source missing, skipped: $src"; continue }
+    $srcItem = Get-Item -LiteralPath $src
+    $files = @()
+    if ($srcItem.PSIsContainer) {
+      $files = Get-ChildItem -LiteralPath $src -Recurse -File -Force
+    } else {
+      $files = @($srcItem)
+    }
+    foreach ($f in $files) {
+      # OS / sync-client metadata files are recreated and removed by the client itself; never inventory them.
+      if ($f.Name -in @('desktop.ini', '.DS_Store', 'Thumbs.db')) { continue }
+      $rel = $f.Name
+      if ($srcItem.PSIsContainer) {
+        $rel = $f.FullName.Substring($srcItem.FullName.Length).TrimStart('\')
+      }
+      $destDir = $row['destination']
+      $relDir = [System.IO.Path]::GetDirectoryName($rel)
+      if ($relDir) { $destDir = Join-Path $destDir $relDir }
+      $lowerPath = $f.FullName.ToLowerInvariant()
+      $ext = $f.Extension.ToLowerInvariant()
+      $action = 'copy'; $reason = ''
+      $excluded = $false
+      foreach ($pat in (($row['exclude']) -split ';')) {
+        if ($pat.Trim() -ne '' -and $rel.ToLowerInvariant().Contains($pat.Trim().ToLowerInvariant())) { $excluded = $true; break }
+      }
+      if ($lowerPath -match $SecretRe) { $action = 'indexed-in-place'; $reason = 'secret' }
+      elseif ($excluded) { $action = 'indexed-in-place'; $reason = 'excluded' }
+      elseif ($lowerPath -match $ArtifactRe) { $action = 'indexed-in-place'; $reason = 'artifact' }
+      elseif ($DocExt -notcontains $ext) { $action = 'indexed-in-place'; $reason = 'ext' }
+      elseif ($f.Length -gt ($MaxMB * 1MB)) { $action = 'indexed-in-place'; $reason = 'size' }
+
+      # Parent-folder date only inside a folder row; a loose file's parent is the old root, whose name says nothing about the file.
+      $parentForDate = ''
+      if ($srcItem.PSIsContainer -and $f.Directory.FullName -ne $srcItem.FullName) { $parentForDate = $f.Directory.Name }
+      $date = Get-DateToken $f.Name $parentForDate
+      $newName = $f.Name
+      if ($action -eq 'copy' -and $row['prefix'] -eq 'yes') {
+        $entityTok = $row['entity']
+        if ($f.Name -notmatch $DatedNameRe -and -not $f.Name.StartsWith($entityTok + '_')) {
+          $cand = '{0}_{1}_{2}_{3}__{4}' -f $entityTok, $row['area'], $date, $row['doc_type'], $f.Name
+          if ((Join-Path $destDir $cand).Length -le $MaxPath) { $newName = $cand }
+        }
+      }
+      $canonical = ''
+      if ($action -eq 'copy') { $canonical = Join-Path $destDir $newName }
+      $items += , @{
+        source = $f.FullName; name = $f.Name; bytes = $f.Length; destDir = $destDir; newName = $newName
+        canonical = $canonical; action = $action; reason = $reason; date = $date
+        entity = $row['entity']; area = $row['area']; project = $row['project']; doc_type = $row['doc_type']
+        tags = $row['tags']; catalog_root = $row['catalog_root']; sha256 = ''; persist = ''
+      }
+    }
+  }
+  return $items
+}
+
+function Read-CountOnly([string]$Path) {
+  if ([string]::IsNullOrEmpty($Path)) { return @() }
+  return [System.IO.File]::ReadAllLines($Path, [System.Text.Encoding]::UTF8) | Where-Object { $_.Trim() -ne '' -and -not $_.TrimStart().StartsWith('#') } | ForEach-Object { $_.Trim() }
+}
+function Count-Files([string]$Folder) {
+  if (-not (Test-Path -LiteralPath $Folder)) { return -1 }
+  return @(Get-ChildItem -LiteralPath $Folder -Recurse -File -Force | Where-Object { $_.Name -notin @('desktop.ini', '.DS_Store', 'Thumbs.db') }).Count
+}
+
+New-Item -ItemType Directory -Force -Path $Out | Out-Null
+$Out = (Resolve-Path -LiteralPath $Out).Path
+$Plan = (Resolve-Path -LiteralPath $Plan).Path
+if ($CountOnly) { $CountOnly = (Resolve-Path -LiteralPath $CountOnly).Path }
+$inventoryPath = Join-Path $Out 'inventory.csv'
+$countPath = Join-Path $Out 'count-only.csv'
+$previewPath = Join-Path $Out 'preview.tsv'
+$catalogPath = Join-Path $Out 'catalog.jsonl'
+$applyLogPath = Join-Path $Out 'apply-log.tsv'
+$verifyPath = Join-Path $Out 'verify-report.txt'
+
+$rows = Read-Tsv $Plan
+Write-Host ("plan rows: {0}" -f $rows.Count)
+
+switch ($Mode) {
+  'inventory' {
+    $items = Expand-Plan $rows
+    $lines = @('path,bytes,sha256')
+    $i = 0
+    foreach ($it in $items) {
+      $i++
+      if ($i % 50 -eq 0) { Write-Host ("hashing {0}/{1}" -f $i, $items.Count) }
+      # Hash only what will be copied; in-place items (media, secrets, installers) are size-checked
+      # so a streaming cloud drive is not forced to download them.
+      $h = ''
+      if ($it.action -eq 'copy') { $h = Get-Sha256 $it.source }
+      $lines += ('"' + $it.source.Replace('"', '""') + '",' + $it.bytes + ',' + $h)
+    }
+    Write-Utf8Lines $inventoryPath $lines
+    $clines = @('folder,files')
+    foreach ($folder in (Read-CountOnly $CountOnly)) {
+      $clines += ('"' + $folder.Replace('"', '""') + '",' + (Count-Files $folder))
+    }
+    Write-Utf8Lines $countPath $clines
+    Write-Host ("inventory: {0} files -> {1}; count-only folders: {2} -> {3}" -f $items.Count, $inventoryPath, ($clines.Count - 1), $countPath)
+  }
+  'dry-run' {
+    $items = Expand-Plan $rows
+    $lines = @("action`treason`tsource`tdestination`tnew_name`tentity`tarea`tproject`tdoc_type`tdate`ttags")
+    $counts = @{}
+    foreach ($it in $items) {
+      $action = $it.action
+      if ($action -eq 'copy' -and (Test-Path -LiteralPath $it.canonical)) { $action = 'skipped-exists' }
+      $key = $action; if ($it.reason) { $key = $action + ':' + $it.reason }
+      if (-not $counts.ContainsKey($key)) { $counts[$key] = 0 }
+      $counts[$key]++
+      $lines += ($action, $it.reason, $it.source, $it.destDir, $it.newName, $it.entity, $it.area, $it.project, $it.doc_type, $it.date, $it.tags) -join "`t"
+    }
+    Write-Utf8Lines $previewPath $lines
+    Write-Host ("preview -> {0}" -f $previewPath)
+    foreach ($k in ($counts.Keys | Sort-Object)) { Write-Host ("  {0,-24} {1}" -f $k, $counts[$k]) }
+  }
+  'apply' {
+    if (-not (Test-Path -LiteralPath $inventoryPath)) { throw "inventory.csv missing under $Out - run -Mode inventory first" }
+    $inv = @{}
+    foreach ($r in (Import-Csv -LiteralPath $inventoryPath -Encoding UTF8)) { $inv[$r.path] = $r }
+    $items = Expand-Plan $rows
+    $log = @("action`tsource`tcanonical`tbytes`tsha256")
+    $catalogLines = @()
+    $perRoot = @{}
+    $counts = @{ 'copied-source-kept' = 0; 'skipped-exists' = 0; 'indexed-in-place' = 0; 'failed' = 0 }
+    $copiedBytes = [long]0
+    $n = 0
+    foreach ($it in $items) {
+      $n++
+      if ($n % 50 -eq 0) { Write-Host ("apply {0}/{1}" -f $n, $items.Count) }
+      if (-not $inv.ContainsKey($it.source)) { throw "source not in inventory (plan changed after inventory?): $($it.source)" }
+      $it.sha256 = $inv[$it.source].sha256
+      if ($it.action -eq 'indexed-in-place') {
+        $it.persist = 'indexed-in-place'; $it.canonical = $it.source
+      }
+      elseif (Test-Path -LiteralPath $it.canonical) {
+        $it.persist = 'skipped-exists'
+      }
+      else {
+        try {
+          New-Item -ItemType Directory -Force -Path $it.destDir | Out-Null
+          Copy-Item -LiteralPath $it.source -Destination $it.canonical
+          $destHash = Get-Sha256 $it.canonical
+          if ($destHash -eq $it.sha256) { $it.persist = 'copied-source-kept'; $copiedBytes += [long]$it.bytes }
+          else { $it.persist = 'failed'; $it.reason = 'hash-mismatch' }
+        } catch {
+          $it.persist = 'failed'; $it.reason = ('copy-error: ' + $_.Exception.Message.Replace("`n", ' '))
+        }
+      }
+      $counts[$it.persist]++
+      $log += ($it.persist, $it.source, $it.canonical, $it.bytes, $it.sha256) -join "`t"
+      $line = To-CatalogLine $it
+      $catalogLines += $line
+      if ($it.catalog_root) {
+        if (-not $perRoot.ContainsKey($it.catalog_root)) { $perRoot[$it.catalog_root] = @() }
+        $perRoot[$it.catalog_root] += $line
+      }
+    }
+    Write-Utf8Lines $applyLogPath $log
+    Append-Utf8Lines $catalogPath $catalogLines
+    $searchMd = @(
+      '# _SEARCH.md - how to find a file here',
+      '',
+      '1. grep `_ai-catalog.jsonl` in this folder: tags, entity, area, doc_type, date, original_name.',
+      '2. Search the prefixed filename: `{entity}_{area}_{date}_{doc_type}__{original name}`.',
+      '3. Search the original name after `__`; it is unchanged.',
+      '',
+      'persist values: copied-source-kept (original still at original_path), indexed-in-place (only copy is at original_path), skipped-exists, failed.',
+      'Keys, credentials, videos, and installers are never copied here; the catalog points to where they already live.'
+    )
+    foreach ($root in $perRoot.Keys) {
+      New-Item -ItemType Directory -Force -Path $root | Out-Null
+      Append-Utf8Lines (Join-Path $root '_ai-catalog.jsonl') $perRoot[$root]
+      $sp = Join-Path $root '_SEARCH.md'
+      if (-not (Test-Path -LiteralPath $sp)) { Write-Utf8Lines $sp $searchMd }
+    }
+    Write-Host ("apply done: copied={0} skipped-exists={1} indexed-in-place={2} failed={3} copiedMB={4:N1}" -f $counts['copied-source-kept'], $counts['skipped-exists'], $counts['indexed-in-place'], $counts['failed'], ($copiedBytes / 1MB))
+    Write-Host ("log -> {0}`ncatalog -> {1}" -f $applyLogPath, $catalogPath)
+    if ($counts['failed'] -gt 0) { exit 2 }
+  }
+  'verify' {
+    if (-not (Test-Path -LiteralPath $inventoryPath)) { throw "inventory.csv missing under $Out" }
+    $report = @("verify run $RunStamp")
+    $fail = 0
+    $checked = 0
+    foreach ($r in (Import-Csv -LiteralPath $inventoryPath -Encoding UTF8)) {
+      $checked++
+      if (-not (Test-Path -LiteralPath $r.path)) { $fail++; $report += "MISSING source: $($r.path)"; continue }
+      $len = (Get-Item -LiteralPath $r.path -Force).Length
+      if ([string]$len -ne [string]$r.bytes) { $fail++; $report += "RESIZED source: $($r.path) $($r.bytes) -> $len" }
+    }
+    $report += "sources checked: $checked"
+    $copies = 0; $inplace = 0
+    if (Test-Path -LiteralPath $catalogPath) {
+      foreach ($line in [System.IO.File]::ReadAllLines($catalogPath, [System.Text.Encoding]::UTF8)) {
+        if ($line.Trim() -eq '') { continue }
+        $o = $line | ConvertFrom-Json
+        if ($o.persist -eq 'copied-source-kept') {
+          $copies++
+          if (-not (Test-Path -LiteralPath $o.canonical_path)) { $fail++; $report += "MISSING copy: $($o.canonical_path)"; continue }
+          $h = Get-Sha256 $o.canonical_path
+          if ($h -ne $o.sha256) { $fail++; $report += "HASH MISMATCH copy: $($o.canonical_path)" }
+        } elseif ($o.persist -eq 'indexed-in-place') {
+          $inplace++
+          if (-not (Test-Path -LiteralPath $o.original_path)) { $fail++; $report += "MISSING in-place: $($o.original_path)" }
+        }
+      }
+    }
+    $report += "copies re-hashed: $copies"
+    $report += "in-place files present-checked: $inplace"
+    if (Test-Path -LiteralPath $countPath) {
+      $cc = 0
+      foreach ($r in (Import-Csv -LiteralPath $countPath -Encoding UTF8)) {
+        $cc++
+        $now = Count-Files $r.folder
+        if ([string]$now -ne [string]$r.files) { $fail++; $report += "COUNT CHANGED: $($r.folder) $($r.files) -> $now" }
+      }
+      $report += "count-only folders rechecked: $cc"
+    }
+    $report += "failures: $fail"
+    $report += $(if ($fail -eq 0) { 'RESULT: PASS - every source present, every copy hash-equal, media counts unchanged' } else { 'RESULT: FAIL' })
+    Write-Utf8Lines $verifyPath $report
+    $report | ForEach-Object { Write-Host $_ }
+    if ($fail -gt 0) { exit 1 }
+  }
+}