v5.0 — Restructure stops being a report

Restructure stops being a report. It could recognise one thing — a family of folders organised
more than one way — and all it could do was say so. It now recognises eight kinds of structural
drift, turns most of them into a plan you review name by name, applies that plan, and writes the way
back to disk before it starts.

Requires macOS 26, unchanged from the 4.x line. Coming from 3.x or 2.x, read the v4.0 section first.

What Restructure finds

• Eight kinds of finding where there was one: siblings shaped differently; a year with files and
  no folders yet; a year hiding inside a name (IRS Docs - 2023); two names for one thing
  (Form W-2 beside Form W2); a folder in an inbox mirroring a real destination; files parked
  above a run of year folders; a leaf sitting beside the folder that owns its concept; and two
  branches holding the same documents under parallel names. Each card names what it saw and the
  class of change that would fix it, so a rename reads differently from a merge before any sheet opens.
• Crowding is counted, not accused. Pass-through folders, single-file folders and empty ones get
  three counts above the findings — no badges, no cards, because every real tree has them. Only the
  empty count offers to act.
• The badge counts what you can drive to zero. Findings that hand off to another surface, and the
  crowding counts, stay out of it.
• "Nothing is wrong" and "I could not check" never share words. A clean result says how many
  folders it checked; a missing survey says it has nothing to read.
• The lens says when the tree was last looked at, and offers a Rescan once that stamp is old
  enough to matter. It used to report only how many folders it covered.

Planning a new shape

• One mapping, applied to every member. The sheet lists every distinct folder name the family
  uses, once, each defaulting to keep — so you answer "what should this be called" a couple of dozen
  times instead of dragging hundreds of files.
• Nothing is pre-selected. The shapes on offer are the ones actually in use, each naming the
  siblings that vouch for it. Where the newest members all disagree, the sheet says outright that
  there is no current shape to continue.
• The cost of a choice is shown where the choice is made. Point two names at one target and the
  row says it is a merge, and in how many members.
• Every operation is derived, never typed. The review lists them in run order, each naming its
  member and the files it carries, beside a before-and-after of one member's folders.
• Nothing is dropped to make the shape fit, and collisions keep both. A folder the target has no
  slot for stays where it is and is listed as kept; a file whose name is already taken arrives under
  a new one. Never an overwrite.
• Optional refinement with Claude, on the names only. It answers row by row against your mapping
  and declines where a folder says nothing about itself. Accepting a row edits your mapping and the
  plan is re-derived — there is no path from a suggestion to the disk that skips the review.
• "Export plan…" is the safe way to stop. It writes the plan as a dated JSON file beside your
  survey and keeps it, so the card offers "Review N operations" afterwards, even after you quit.

Applying, and taking it back

• Apply is the only thing here that writes, and you can watch it run. It refuses to start while a
  scan or another file operation is running — with a sentence, not a queue. The reversal is written
  to disk before the first folder moves.
• Every claim is re-probed at the moment of the action. A folder holding a file the plan never
  listed is skipped and named while the rest of the plan runs; a destination taken since gets a new
  name rather than an overwrite.
• The result is checked by a second code path, independent of the code that did the work, with
  the verdict on the card. A mismatch is reported and never rolled back automatically.
• A finding disappears because the tree was re-read, not because it was marked done. The landing
  ends by re-deriving the survey from a fresh walk. If that step fails, the card says so in its own
  words rather than borrowing the success sentence.
• Removing folders is separate, opt-in, and folders only. No file is deleted by Restructure at
  any stage. The sheet prints every path in full and moves what you tick to the Trash.
• Two undos, and the card says which is which. ⌘Z takes the whole landing back as one step and
  is gone once you quit. "Undo this reorganisation" replays a reversal kept on disk through the
  same guards and re-probing, and survives quitting — it can partly fail, and it names what it could
  not put back.

Setting up a new year

• "Set up like its siblings" creates the folders and moves nothing — the folders the rest of the
  series has, each justified by how many siblings already have it. ⌘Z removes them again. The loose
  files go to To File, scoped to that folder alone.
• The Organize overview raises it the month it happens rather than waiting for you to go looking,
  and remembers being dismissed.

Getting to Organize

• The Organize menu learns the new verbs. "Plan This Folder's Shape…" and "Set Up Like Its
  Siblings" join it, aimed at whatever the focused pane has selected.
• "Undo This Reorganisation" is deliberately not in Edit. It is not ⌘Z — it replays an inverse
  from disk and can partly fail — so putting it beside Undo would have been the most misleading
  place available. It is the one item there that needs no selection.
• "Check This Folder's Shape" is in a folder's row menu and in ⌘K, aimed at the folder you are
  already standing on.

Duplicates

• Name-only matches are gone. A group of same-named, different-content folders was a warning
  with no resolution attached, and it crowded out the findings that had one. Folders now join an
  overlapping group on their own merits rather than on an average across everything sharing their
  name — so a genuine twin is no longer lost to three unrelated folders that happen to share its name.
• The pills that name a subset are the filter now. They looked interactive and were inert. The
  figures that are not subsets stopped dressing like filters: the reclaimable total is plain text.
• The badge says what you need to do, not what the match was. Byte-identical groups carry no
  badge at all — their certainty reads in the green reclaim figure, and the space goes to the file's
  icon and name. The rest say "needs review".
• Picking a different copy to keep no longer reorders the list, so there is still a before and
  after to compare, and the row under the pointer is the row you clicked.

On the command line

• synccloud restructure reports the whole detector set over a surveyed tree, with --json for
  the full report and --profiles-dir to read a survey from elsewhere. It never touches the disk it
  describes.

Known limitations

• The document survey is not in this release. The folder half — the tree walk Restructure reads —
  ships in setup's Folders step. Reading page one of every document is an hours-long background pass
  and is deliberately not here.
• The command line stops at report. There is no --apply and no --plan: Apply's guarantees are
  about a person reading a plan before anything moves, and a flag that skips the reading skips the
  guarantees.
• Two branches under parallel names are reported, not planned. That finding names the pair and
  the documents they share; converging them is not something v5.0 offers to do for you.
• The structure trend starts empty. It draws the finding counts the survey has recorded, so it
  has nothing to show until this release has been running for a while.

---

Full changelog: v4.6...v5.0