folder_structure — Util Upgrade

What Was Done

Upgraded the flat generate_folder_structure.py script into a standalone Windows-native Python project with Rich wizard UX, config-driven presets, and WSL path support.

Project: D:\FSS\Software\Utils\PythonUtils\folder_structure\ (v1.2.0)

Launch: launch-folder-structure.bat or uv run folder-structure

Decisions

Topic	Decision
Runtime	Windows-native — KB vaults on NTFS; WSL paths accepted as input
UI	Rich terminal wizard (web-deploy pattern), not a GUI modal
Utils location	WSL for web/dev pipelines; Windows `PythonUtils` for KB/filesystem utils
KB docs	`Core/Utils/Custom/` (mine) vs `Core/Utils/External/` (third-party)
Output naming	Fixed prefixes + configurable suffix: `Folder_Structure-{suffix}.md`, `FolderFile_Structure-{suffix}.md`
Exclude patterns	Primary home in `config.yaml`; wizard allows session-only edit
Logging	File-only (`logs/folder_structure.log`); no console INFO output

Key Features

KB vault presets (kb-root, kb-business, kb-core, kb-mbr, kb-sdc)
Typer CLI: run, list, --preset, --dry-run, --filename-root
tkinter [B]rowse folder picker at source/output prompts
Segment-based exclude matching (not substring)
Default output: D:/FSS/KB/Core/Misc/

WSL Path Handling

Input	Scan method	Speed
`D:/FSS/KB`	Native Windows	<1s
`/mnt/d/FSS/KB`	Rewritten to `D:\...`	<1s
`\\wsl$\...\mnt\d\...`	Rewritten to `D:\...`	<1s
`\\wsl$\...\home\ta\.claude`	WSL native `find`	~1-2s

Gotcha: Scanning pure Linux paths through the \\wsl$\ bridge without WSL-native find takes ~30s. The util auto-detects and uses wsl find for /home/... paths.

Filename gotcha: Folder_Structure-D:/FSS/KB is invalid on Windows (: and / forbidden). Auto suffix uses path parts: D_FSS_KB.

KB Documentation

Core/Utils/Custom/Generate Folder Structure.md — user-facing docs
Core/Utils/Custom/My_Backup System.md — moved from Processes
Core/Utils/External/Utilities.md — moved from Processes

Legacy

generate_folder_structure.py — deprecated with startup warning
Warp workflow generate-kb-folder-structure.yaml — superseded (can remove when verified)

Files Changed

PythonUtils git repo:

folder_structure/ — new project
generate_folder_structure.py — deprecation notice

KB (Obsidian, not git):

Core/Utils/ — new structure + moved notes
Core/Logs/System/2026-06-08_folder-structure-util-upgrade.md — this log