docs(WIP_tools): add repoCmdFiles README and structure

WIP_tools/WIPTools-README.md

@@ -0,0 +1,95 @@
+# WIP Tools — Deployment & Workflow (Windows)
+
+**NOTE**: this README assumes the repo project name is **hatpro-schema-temp**. If the repo is different project, then change the information in this file according
+
+Authoritative copies of the **repo command files** live in this repo under `WIPTools/`.
+You **run** them from your WIP area:
+
+```
+C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles\
+```
+
+## 1) First-time install (copy from repo → WIP)
+
+> Replace `<REPO>` with your local repo path if different.
+
+```bat
+robocopy "<REPO>\WIPTools\scripts" "C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles" *.bat /E /R:2 /W:2
+robocopy "<REPO>\WIPTools\docs"    "C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles\docs" *.*  /E /R:2 /W:2
+```
+
+**Preview only (no writes):**
+```bat
+robocopy "<REPO>\WIPTools\scripts" "C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles" *.bat /E /L /R:1 /W:1
+robocopy "<REPO>\WIPTools\docs"    "C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles\docs" *.*  /E /L /R:1 /W:1
+```
+- `/E` = include subfolders
+- `/L` = list only (dry run)
+- `/R:2 /W:2` = retry/wait limits (faster)
+
+---
+
+## 2) Daily WIP workflow (your canonical flow)
+
+1. **Work in WIP**  
+   Edit files under `...\hatpro-schema-temp-WIP\repoCmdFiles\` (and `docs\`).
+
+2. **(Optional) Merge from repo copy**  
+   If needed, manually merge changes from `WIPTools/source/...` into your WIP copy.
+
+3. **Overwrite the repo copy with your WIP result**  
+   When your WIP change is ready to publish back to the repo:
+
+   ```bat
+   robocopy "C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles" "<REPO>\WIPTools\source\scripts" *.bat /E
+   robocopy "C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles\docs" "<REPO>\WIPTools\source\docs" *.* /E
+   ```
+
+   *Tip:* use `/XO` if you want to **skip** overwriting newer files in the destination, or `/L` first to preview.
+
+4. **Commit & PR (from repo)**  
+   - In GitHub Desktop: stage changed files under `WIPTools/source/...`
+   - Commit with a clear message (e.g., `chore(WIPTools): update Merge-WIP-to-Repo.bat and docs`)
+   - Push → Open Pull Request
+
+---
+
+## 3) Updating WIP from repo later
+
+When the repo’s authoritative files change and you want them in WIP:
+
+```bat
+robocopy "<REPO>\WIPTools\scripts" "C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles" *.bat /E
+robocopy "<REPO>\WIPTools\docs" "C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles\docs" *.*  /E
+```
+
+**Preview first:**
+```bat
+robocopy "<REPO>\WIPTools\scripts" "C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles" *.bat /E /L
+robocopy "<REPO>\WIPTools\docs" "C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles\docs" *.*  /E /L
+```
+
+---
+
+## 4) Safety tips
+
+- Use **`/L`** to preview before copying (dry run).
+- Keep batch files CRLF in Git: add to `.gitattributes`:
+  ```
+  WIPTools/**/*.bat text eol=crlf
+  ```
+- Consider adding a quick **snapshot** command you run from WIP before risky ops (optional).
+
+---
+
+## 5) Paths used in examples
+
+- Repo (local):  
+  `C:\Users\nthomson\Projects\hatpro-schema-temp`
+- WIP runtime:  
+  `C:\Users\nthomson\Projects\hatpro-schema-temp-WIP\repoCmdFiles\`
+- Authoritative repo copies:  
+  - Scripts: `WIPTools\source\scripts\`
+  - Docs: `WIPTools\source\docs\`
+
+> If your local paths differ, replace them in the commands above.

WIP_tools/docs/User Manual for WIP-Manager-bat.md

@@ -0,0 +1,67 @@
+Here’s the plain-English summary for the three actions in WIP-Manager.bat (and the identical single-purpose .bat files). This is exactly what they do and how they protect work-in-progress:
+
+## Snapshot REPO → _snapshots\YYYYMMDD_HHMMSS\
+What it does:
+Makes a full, read-only copy of your repo into a brand-new timestamped folder under …\hatpro-schema-temp-WIP\_snapshots\.
+Why it’s safe:
+
+
+It never touches your live WIP folder or your repo — it only writes into a new folder.
+
+
+Uses robocopy /MIR only to mirror repo → that new snapshot location.
+
+
+Excludes junk like .git, node_modules, etc.
+
+
+
+## Preview WIP → REPO (dry run)
+What it does:
+Shows what would be copied from your WIP into your repo — without copying anything.
+Why it’s safe:
+
+
+It’s a dry run (/L flag). It prints the list but makes no changes.
+
+
+Lets you confirm exactly which files would be updated before you do anything real.
+
+
+## Merge WIP → REPO (copy only newer WIP files; no deletes)
+What it does:
+Copies your edits from WIP into the repo so you can review/commit in GitHub Desktop.
+Why it avoids clobbering work:
+
+
+Uses robocopy /E /XO
+
+
+/XO = Exclude Older source files → only newer files in WIP can overwrite files in the repo.
+
+
+If the repo’s copy is newer, it is left alone.
+
+
+
+
+No /MIR here → it never deletes files in the repo. It’s additive/overwriting only when WIP is newer.
+
+
+You’ll still review diffs in GitHub Desktop before committing, so you have a final gate.
+
+
+
+# Quick mental model
+
+
+Snapshot = copy repo ➜ new archive folder (write-only to a new place).
+
+
+Preview = “show me what would happen” (no changes).
+
+
+Merge = copy WIP ➜ repo, but only when WIP files are newer, and never delete repo files.
+
+
+These steps do not depend on Git staging or commits; they operate on the filesystem, so GitHub Desktop’s staged/unstaged state won’t cause partial copies.

WIP_tools/docs/When_and_Why_to_Run_a_Snapshot_REPO.md

@@ -0,0 +1,71 @@
+# When and Why to Run a Snapshot REPO
+
+## The Rule of Thumb
+
+Do **Snapshot REPO** **before** any action that could change or delete files in your local repo working tree **without your explicit per-file control**.
+
+---
+
+## When to Snapshot (YES)
+
+- **Before `pull` (merge or rebase) when you have local edits**  
+  *Why:* an incoming change could conflict and force resolutions or overwrites.
+
+- **Before switching branches with uncommitted work**  
+  *Why:* checkout may refuse or you may discard to proceed.
+
+- **Before running “clean”/generator tasks** (`npm run clean`, codegen that rewrites files)  
+  *Why:* these can delete or regenerate folders.
+
+- **Before “Discard changes” in GitHub Desktop**  
+  *Why:* discard deletes local edits to tracked files.
+
+- **Before a large refactor/rename sweep**  
+  *Why:* many paths will change; easy to misplace something.
+
+- **Before resolving messy merge conflicts**  
+  *Why:* you may experiment and want an easy revert.
+
+---
+
+## When a Snapshot Is Optional / Usually Not Needed (NO)
+
+- **After `fetch`** — only updates remote refs, does not touch files.  
+  → **No snapshot needed**.
+
+- **After a simple `push`** — uploads your commits.  
+  → **No snapshot needed**.
+
+- **`pull` into a clean tree with no local edits** (fast-forward).  
+  → **No snapshot needed**.
+
+---
+
+## Simple Decision Tree
+
+| Question | Action |
+|-----------|---------|
+| Do I have uncommitted or untracked local changes? | **Yes → Snapshot before pull / branch switch / clean / discard** |
+| | **No → Safe to pull or switch without snapshot** |
+
+---
+
+## Why Do It Before Pull (Not After)?
+
+- A snapshot taken **before** the pull preserves the exact pre-pull state, so if the pull introduces conflicts or regenerations, you can restore or diff easily.  
+- A snapshot taken **after** a pull won’t help you revert to the pre-pull state if something went wrong during the pull.
+
+---
+
+## Quick Scenarios
+
+| Situation | Recommended Action |
+|------------|--------------------|
+| Edited schemas or examples; want to pull team updates | Run **Snapshot REPO** first, then pull |
+| About to run `npm run clean` | Run **Snapshot REPO** first |
+| Switching from `chore/local-sync-2025-10-30` to `main` with local changes | Run **Snapshot REPO** first, then switch (or commit/stash) |
+
+---
+
+**Summary:**  
+Snapshot **before** risky, file-changing operations; skip it for **fetch/push** and most **pulls on a clean tree**.

WIP_tools/scripts/Merge-WIP-to-Repo.bat

@@ -0,0 +1,6 @@
+@echo off
+set "WIP=C:\Projects\hatpro-schema-temp-WIP"
+set "REPO=C:\Projects\hatpro-schema-temp"
+robocopy "%WIP%" "%REPO%" /E /XO /R:2 /W:2 /NFL /NDL /NP
+echo Done. Review in GitHub Desktop, then commit.
+pause

WIP_tools/scripts/Preview-WIP-to-Repo.bat

@@ -0,0 +1,5 @@
+@echo off
+set "WIP=C:\Users\nthomson\Projects\hatpro-schema-temp-WIP"
+set "REPO=C:\Users\nthomson\Projects\hatpro-schema-temp"
+robocopy "%WIP%" "%REPO%" /E /XO /L /NFL /NDL /NP
+pause

WIP_tools/scripts/Snapshot-Repo.bat

@@ -0,0 +1,10 @@
+@echo off
+set "REPO=C:\Users\nthomson\Projects\hatpro-schema-temp"
+set "WIP=C:\Users\nthomson\Projects\hatpro-schema-temp-WIP"
+set "SNAPROOT=%WIP%\_snapshots"
+for /f %%i in ('powershell -NoProfile -Command "Get-Date -Format yyyyMMdd_HHmmss"') do set TS=%%i
+set "DEST=%SNAPROOT%\%TS%"
+mkdir "%DEST%" >nul 2>&1
+robocopy "%REPO%" "%DEST%" /MIR /XD ".git" "node_modules" ".idea" ".vscode" "dist" "build" ".cache" ".next" /R:2 /W:2 /NFL /NDL /NP
+echo Snapshot: %DEST%
+pause

WIP_tools/scripts/WIP-Manager.bat

@@ -0,0 +1,59 @@
+@echo off
+REM === WIP Manager ===
+REM Store this file in: C:\Projects\hatpro-schema-temp-WIP\repoCmdFiles
+
+REM Set project paths (UPDATE THESE TWO)
+set "REPO=C:\Users\nthomson\Projects\hatpro-schema-temp"
+set "WIP=C:\Users\nthomson\Projects\hatpro-schema-temp-WIP"
+
+REM Ensure WIP and _snapshots exist
+if not exist "%WIP%" mkdir "%WIP%"
+set "SNAPROOT=%WIP%\_snapshots"
+if not exist "%SNAPROOT%" mkdir "%SNAPROOT%"
+
+:menu
+cls
+echo ==============================
+echo   WIP Manager
+echo ==============================
+echo [1] Snapshot REPO -> _snapshots\YYYYMMDD_HHMMSS
+echo [2] Preview WIP -> REPO (dry run)
+echo [3] Merge WIP -> REPO (copy only newer WIP files; no deletes)
+echo [4] Exit
+echo.
+set /p choice=Choose 1-4: 
+
+if "%choice%"=="1" goto snapshot
+if "%choice%"=="2" goto preview
+if "%choice%"=="3" goto merge
+if "%choice%"=="4" goto end
+goto menu
+
+:snapshot
+for /f %%i in ('powershell -NoProfile -Command "Get-Date -Format yyyyMMdd_HHmmss"') do set TS=%%i
+set "DEST=%SNAPROOT%\%TS%"
+mkdir "%DEST%" >nul 2>&1
+echo Creating snapshot: "%DEST%"
+robocopy "%REPO%" "%DEST%" /MIR ^
+  /XD ".git" "node_modules" ".idea" ".vscode" "dist" "build" ".cache" ".next" ^
+  /R:2 /W:2 /NFL /NDL /NP
+echo Snapshot created: "%DEST%"
+pause
+goto menu
+
+:preview
+echo Preview (dry run): newer files that WOULD copy from WIP -> REPO
+robocopy "%WIP%" "%REPO%" /E /XO /L /NFL /NDL /NP
+echo (Nothing copied; this was a preview.)
+pause
+goto menu
+
+:merge
+echo Copying ONLY newer files from WIP -> REPO (no deletes)...
+robocopy "%WIP%" "%REPO%" /E /XO /R:2 /W:2 /NFL /NDL /NP
+echo Done. Review diffs in GitHub Desktop, then commit.
+pause
+goto menu
+
+:end
+exit /b 0