elliot-stack 1.0.29 → 1.0.33

package/skills/estack-migrate-claude-session-history/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: estack-migrate-claude-session-history
+version: 1.0.0
+description: (migrate-claude-session-history) Use whenever the user wants to move a Claude Code session (the .jsonl transcript plus its subagent sidecar files) from one project to another so that /resume picks it up under the new project. Triggers on phrases like "migrate this session", "move this session to <project>", "convert session X to be in project Y instead of Z", "transfer chat history to another project", "this session belongs under <project>", or when the user names a session UUID and a different target project. Handles the full workflow: backup, sidecar-aware copying, rewriting all 9 path-encoding variants in every entry, appending a visible user-message migration note, and end-to-end verification. Use this even if the user only describes the intent loosely (e.g. "this conversation should live under the personal-health project") — do not try to do this by hand with raw file moves; subtle cwd / encoded-path bugs will break /resume.
+---
+
+# Migrate Claude Session History
+
+## When this skill applies
+
+The user wants a specific session (or a handful of sessions) that currently lives under Project A in `~/.claude/projects/` to instead live under Project B, so that `claude --resume` and `/resume` find it under B and the conversation's recorded working directory matches B.
+
+This is **not** the right skill for:
+
+- Listing / searching / reading sessions → use `read-claude-session-history`
+- Recovering deleted sessions from backups → use the `.claude-backups` snapshots via `read-claude-session-history`
+- Renaming a project's working directory and moving **all** of its sessions at once → use `scripts/migrate-claude-history.js` directly without the `--session` flag (it has a full-project mode)
+- A brand-new conversation in a different folder → just start a fresh Claude Code session there
+
+## Why this is not a one-liner
+
+A Claude Code session is keyed by the project's working directory, which gets encoded into the project folder name under `~/.claude/projects/`. The session's `.jsonl` transcript contains hundreds of references to that directory across **nine** path-encoding variants (JSON-escaped backslash, plain backslash, forward slash, MSYS, hyphenated project-dir name — each in upper/lower drive-letter forms). A `cwd` field exists on most entries. There is also a sidecar directory (`<uuid>/subagents/`) holding subagent transcripts that must move together.
+
+Just `mv` will not work. The bundled script handles all of this; the workflow below ties it together with a backup, a visible migration note, and verification.
+
+See `references/path-encoding.md` for the encoding reference.
+
+## Workflow
+
+Work through these steps in order. Skipping the plan / backup / verification steps is exactly how a migration goes wrong silently — the script reports success, but `/resume` fails to find the session or loads it under the wrong project.
+
+### 1. Resolve the inputs
+
+You need three things. Treat the conversation as the primary source — only ask the user for what is genuinely missing.
+
+| Input | How to resolve |
+|---|---|
+| **Session UUID** | If the user gave a UUID, use it. If they gave a session file path, take the basename without `.jsonl`. If they only described the session ("the one where we did X"), use `read-claude-session-history --mode search --all-projects --query "<keywords>"` to find candidates and confirm with the user. |
+| **Source project path** (the real cwd) | Run `python <read-claude-session-history>/scripts/read_transcript.py --mode lookup --uuid <prefix>` to get the source `.jsonl` path. Reverse the encoded folder name back into a real Windows path: drop the leading `C--` (becomes `C:\`) and convert each `-` between path segments back to `\`. Confirm by reading the `cwd` field of any entry in the file. |
+| **Target project path** (where the session should live) | Ask the user, unless the conversation already named it (e.g. "move it to `~\Foo\Bar`"). The target project directory under `~/.claude/projects/` does **not** need to exist yet — the script creates it. The encoded folder name is derived from the path. |
+
+If the source and target encoded folder names are identical, the migration is a no-op — tell the user.
+
+### 2. Present the plan and confirm
+
+Before touching anything, show the user a short plan with:
+
+- Source `.jsonl` path
+- Target `.jsonl` path
+- Old cwd → New cwd (the values that will be rewritten)
+- Backup location (default: `<source-real-path>\session-backups\<timestamp>-pre-migration\`, or a path the user prefers)
+- A note that the script will also append a visible user-message migration note to the migrated transcript (on by default; see step 6)
+
+Wait for explicit "go ahead." Migrations touch files Claude Code reads on every `/resume`; a wrong target is annoying to recover from. The backup is the safety net, but confirming first means we usually don't need to use it.
+
+### 3. Back up both project directories — full copies, both sides
+
+Robocopy is the right tool on Windows — fast and resilient with large dirs:
+
+```powershell
+$ts = Get-Date -Format "yyyy-MM-dd-HHmmss"
+$backupRoot = "<chosen-backup-root>\$ts-pre-migration"
+New-Item -ItemType Directory -Force -Path $backupRoot | Out-Null
+robocopy "<source-project-dir>" "$backupRoot\<source-folder-name>" /E /NFL /NDL /NJH /NJS /NP /MT:8 | Out-Null
+robocopy "<target-project-dir>" "$backupRoot\<target-folder-name>" /E /NFL /NDL /NJH /NJS /NP /MT:8 | Out-Null
+```
+
+Back up the **entire** source project dir **and** the **entire** target project dir, even if the target only has one or two unrelated sessions. These backups serve two purposes, and the second one is the one people forget:
+
+1. **Rollback safety net.** If anything in the migration goes wrong, you can restore both sides to their pre-migration state in one command.
+2. **Ground truth for validation.** The backup of the source dir is the only authoritative record of what the original transcript looked like — every entry, every path string, every sidecar file. After migration, step 7 will diff the migrated content against the backup to prove that **every** old-path occurrence was rewritten (no encoding variant was missed) and **no** entries were lost, duplicated, or reordered. The backup of the target dir proves you only **added** files to it — you didn't accidentally overwrite anything that was already there. Without both backups, "the migration worked" is hope, not verification.
+
+Robocopy's exit codes are non-standard — exit 1 means "files copied successfully," not an error. After it finishes, report the file counts and sizes from `Get-ChildItem ... -Recurse | Measure-Object` so the user sees the backup actually contains something.
+
+### 4. Dry-run, then execute
+
+```bash
+node <skill-dir>/scripts/migrate-claude-history.js \
+  --old-repo "<source-project-real-path>" \
+  --new-repo "<target-project-real-path>" \
+  --session <session-uuid> \
+  --dry-run
+```
+
+The dry-run prints:
+
+- Which `.jsonl` plus how many sidecar files would be copied
+- Replacement counts per path-encoding variant (most sessions hit only pattern A — JSON-escaped backslash, upper-drive — because that's what `cwd` fields use)
+
+If the dry-run output looks wrong (zero sidecar files when there should be subagents, wildly different replacement counts than expected, or zero replacements at all), stop and investigate before running for real. See `references/troubleshooting.md`.
+
+Then run without `--dry-run` to execute. The script:
+
+- Copies the `<uuid>.jsonl` to the target project dir, applying all 9 path replacements
+- Copies the entire `<uuid>/subagents/` sidecar tree (subagent transcripts + meta files) with the same replacements
+- Appends a visible migration note as a regular user message to the main `.jsonl` (see step 6)
+- Runs its own stale-reference verifier and reports any matches
+
+### 5. Handle the "stale reference" warning
+
+When the **new** project path contains the **old** project path as a prefix (e.g. moving from `Other Claude Code` → `Other Claude Code\Personal-Health-Project`), the script's verifier will warn about "stale references" in the migrated file. These are **false positives**: every occurrence of the old path is now actually inside a new-path string (since the new path begins with the old path).
+
+Confirm it really is a false positive by counting genuine stale references — occurrences of the old path that are **not** followed by the new path's added segment. A Python check is in `references/troubleshooting.md`. If true-stale count is zero, ignore the warning.
+
+If true-stale count is non-zero, **do not** declare success. Investigate which pattern the script missed and either fix the script or hand-patch the file.
+
+### 6. The migration note
+
+By default, the script appends a `type: "user"` entry (no `isMeta`) as the last entry of the migrated `.jsonl`. This entry:
+
+- Tells future-Claude (and the user, when scrolling the conversation) that the session was migrated, what was rewritten, and how to recover when a rewritten path no longer exists on disk
+- Is intentionally **not** `isMeta: true` — the user wants both themselves and the AI to see it on `/resume`
+- Is duplicate-safe — the script's append routine checks the last few entries for an existing `<session-migration-note>` block and refuses to add a second
+
+Users can opt out with `--no-migration-note`, but the script prints a warning that this is strongly discouraged. Do not pass `--no-migration-note` unless the user has explicitly asked for it.
+
+### 7. Verify end-to-end — and validate against the backup
+
+Run the bundled validation script. It consolidates every structural, schema, path-consistency, sidecar, and (optional) backup-cross-validation check into one invocation, prints a per-check PASS/FAIL table, and exits non-zero on any failure.
+
+```bash
+python <skill-dir>/scripts/validate-migration.py \
+  "<target-project-encoded-dir>/<uuid>.jsonl" \
+  --old-repo "<source-real-path>" \
+  --new-repo "<target-real-path>" \
+  --source-backup "<backup-root>/<source-folder-name>/<uuid>.jsonl" \
+  --target-backup-dir "<backup-root>/<target-folder-name>"
+```
+
+The script runs these checks in order — most of them require no flags, the path checks need `--old-repo` and `--new-repo`, and the cross-validation checks need `--source-backup` (with `--target-backup-dir` enabling the "target untouched" sub-check):
+
+| Check | What it validates | Needs flags |
+|---|---|---|
+| JSONL parse integrity | Every line is valid JSON | — |
+| Schema consistency | Each entry has `type`; user/assistant entries have well-formed `message`; uuids and parentUuids are UUID-shaped | — |
+| Session ID consistency | Every entry's `sessionId` matches the file's UUID | — |
+| Parent UUID chains | Every non-null `parentUuid` resolves to a uuid present in the file | — |
+| CWD field consistency | All non-empty `cwd` values are identical (and equal `--new-repo` if passed) | optionally `--new-repo` |
+| Migration note present | Exactly one `<session-migration-note>` entry exists, is `type: "user"`, no `isMeta` | — |
+| Stale path references | No "truly-stale" old-path references in entries that existed at migration time (post-note entries are skipped — those are later activity that can legitimately reference the old path) | `--old-repo` + `--new-repo` |
+| Sidecar integrity | Every subagent `.jsonl` in `<uuid>/` parses and shares the parent `sessionId` | — |
+| Backup cross-validation | Source backup parses; entry count = source + 1; every source uuid present in order; sidecar count matches; pre-existing target files unchanged | `--source-backup` (+ `--target-backup-dir`) |
+
+If anything fails, stop. Read the failed check's detail line — it points at the specific entry index or file. The backup is right there; if recovery is needed: `robocopy <backup-dir> <live-dir> /MIR`.
+
+All checks must pass before declaring success. The script's final line is the summary you report back to the user.
+
+### 8. Tell the user what's next, and tear down the safety net
+
+After verification, the user still has work to do. Walk them through these in order — each one unlocks the next.
+
+1. **Test `/resume` in the new project's working directory.** This is the real validation. The migrated session should appear in the resume picker and load with the full conversation history. If it doesn't, **stop** — do not delete anything. See `references/troubleshooting.md` → "/resume doesn't show the session under the new project" for diagnosis.
+
+   Give the user a ready-to-run command they can copy directly. Format it in a fenced code block:
+
+   ```
+   cd "<target-project-real-path>";claude -r <session-uuid>
+   ```
+
+   Example: `cd "C:\Users\2supe\Other Claude Code\Personal-Health-Project";claude -r ef382169-d56b-4850-b092-8084a52983ef`
+
+2. **Once `/resume` works, delete the original session from the source project.** Until they do, `--mode lookup` will report the UUID as ambiguous, and Claude Code may still find the session under the old project. Ask the user before running these yourself — deletion is irreversible:
+   ```powershell
+   Remove-Item "<source-project-encoded-dir>\<uuid>.jsonl"
+   Remove-Item -Recurse "<source-project-encoded-dir>\<uuid>"  # sidecar dir
+   ```
+
+### 9. Clean up the backups — the final step
+
+Once both of the above are done, **the migration is locked in** and the pre-migration backup folder created in step 3 is just bloat. Robocopy backups of `.claude/projects/` directories run hundreds of megabytes; do not let them accumulate. Delete the entire backup folder created for this migration:
+
+```powershell
+Remove-Item -Recurse -Force "<backup-root>"
+```
+
+Confirm with the user before deleting and report the freed size. Do **not** skip this step or default to "keep it for a few days" — if `/resume` worked and the source copy is gone, the backup has done its job. Keeping it costs disk and clutters the workspace.
+
+The only reason to keep a backup is if you have not yet verified `/resume` works **or** you have not yet deleted the source copy. In either of those cases, you are still in steps 1-2, not step 9.
+
+## Common pitfalls
+
+These are the failure modes that have actually happened — read `references/troubleshooting.md` for the fixes.
+
+- Forgetting the sidecar dir — the main `.jsonl` migrates but the subagent transcripts get left behind, so the migrated brief shows `subagents: 0` even though the original had many. The script's `--session` mode now handles this automatically, but verify with the subagent-list check.
+- Treating "stale reference" warnings as real when the new path is a subdir of the old path.
+- Running the migration without `--session`, which migrates **every** session in the source project (the constants/CLI default is full-project mode).
+- Source-path encoding mismatch — Claude Code creates `C--Foo` on Windows but case-insensitive filesystems can produce `c--Foo`. The script tries both.
+- Forgetting to rewrite `gitBranch` / `version` consistency on the appended note — the script copies these from the last uuid-bearing entry; do not invent values.
+
+## Files in this skill
+
+- `scripts/migrate-claude-history.js` — the migration script. Supports full-project and single-session modes, CLI overrides for old/new repo, auto-append of the migration note (on by default), `--no-migration-note` opt-out, and `--dry-run`. Run `node scripts/migrate-claude-history.js --help` for the full CLI.
+- `scripts/validate-migration.py` — post-migration validator. Runs structural, schema, path-consistency, sidecar, and (optional) backup-cross-validation checks on a migrated `.jsonl`. Exits 0 if every check passes, 1 otherwise. Run `python scripts/validate-migration.py --help` for the full CLI. Use this in step 7 instead of writing ad-hoc Python.
+- `scripts/test-append-note.js` — a self-contained smoke test for the note-append routine. Run with `node scripts/test-append-note.js`. Useful if you edit the migration script and want to sanity-check the duplicate-detection and non-meta entry shape.
+- `references/path-encoding.md` — the 9 path-encoding variants, why each exists, which entries use which form.
+- `references/troubleshooting.md` — recoveries for stale-reference false positives, missed sidecars, ambiguous lookups, and the true-stale grep recipe.
+---
+
+## Skill Feedback
+
+If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
+
+**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
+
+```bash
+gh issue create \
+  --repo ElliotDrel/e-stack \
+  --title "estack-migrate-claude-session-history: <concise summary>" \
+  --body "<description from user feedback — expected vs. actual behavior and context>"
+```
+
+**If `gh` is not installed**, build a pre-filled URL:
+
+```bash
+python3 -c "
+import urllib.parse
+title = 'estack-migrate-claude-session-history: <concise summary>'
+body = '<description from user feedback — expected vs. actual behavior and context>'
+base = 'https://github.com/ElliotDrel/e-stack/issues/new'
+print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
+"
+```
+
+Share the printed URL with the user and offer to open it in their browser.
+
+They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.

package/skills/estack-migrate-claude-session-history/references/path-encoding.md

@@ -0,0 +1,55 @@
+# Path Encoding Reference
+
+Why session migration needs **nine** path replacements instead of one.
+
+A Claude Code project's working directory shows up inside session transcripts in several different encodings depending on which subsystem wrote it. Missing even one variant produces a transcript that *looks* migrated but breaks on `/resume` or shows the wrong project name. The migration script applies all nine; this file documents what each one is, and where it tends to appear.
+
+The script sorts the nine pairs longest-first before substitution, which prevents partial overlaps (e.g. matching the forward-slash form inside the JSON-escaped backslash form).
+
+## The nine variants
+
+For an old path `C:\Users\name\old\repo` migrating to `C:\Users\name\new\repo`, the script rewrites all of these:
+
+| Key | Encoding | Example old form | Where it appears |
+|---|---|---|---|
+| A | JSON-escaped backslash, uppercase drive | `C:\\Users\\name\\old\\repo` | `cwd` field on most entries; tool inputs serialized as JSON strings. This is usually the highest-count replacement by far. |
+| B | JSON-escaped backslash, lowercase drive | `c:\\Users\\name\\old\\repo` | Rare; only when something on the system normalized the drive to lowercase. |
+| C | Forward slash, uppercase drive | `C:/Users/name/old/repo` | Tool outputs from Unix-ish utilities running on Windows (e.g. `find`, `grep` via Git Bash). |
+| D | Hyphenated project-dir name, lowercase drive | `c--Users-name-old-repo` | References to the encoded project dir under `.claude/projects/` in lowercase. |
+| E | MSYS / Git Bash path | `/c/Users/name/old/repo` | Bash tool outputs from MSYS / Git Bash. |
+| F | Hyphenated project-dir name, uppercase drive | `C--Users-name-old-repo` | References to the encoded project dir, the form Claude Code itself uses on Windows. |
+| G | Forward slash, lowercase drive | `c:/Users/name/old/repo` | Rare lowercase-drive variant of C. |
+| H | Plain backslash, uppercase drive | `C:\Users\name\old\repo` | Conversation text — when Claude prints a path inline, it usually uses this form. |
+| I | Plain backslash, lowercase drive | `c:\Users\name\old\repo` | Rare lowercase-drive variant of H. |
+
+## How the encoded project-dir name is built
+
+Given a Windows path like `C:\Users\name\old\repo`:
+
+1. Take the drive letter and colon → `C:`
+2. Append each path segment separated by `\` → `C:\Users\name\old\repo`
+3. Replace every `:`, `\`, `/`, space, and `'` with `-` → `C--Users-name-old-repo`
+
+This is the folder name under `~/.claude/projects/`. Claude Code creates the uppercase-drive form on Windows; the lowercase form exists for case-insensitive filesystem quirks.
+
+## Why this matters for migrations
+
+Most replacements happen in the `cwd` field (variant A). But other variants show up in:
+
+- Subagent transcripts that captured shell output (variants C, E, G)
+- Tool result strings where Claude or a tool quoted a path (variant H)
+- References to other sessions or the project dir itself (variants D, F)
+
+The replacement count printed by the migration script's dry-run reveals which subsystems your session interacted with. A session that only ever talked to native Windows tools will show 100% pattern A; one that ran a lot of `git` or `bash` will show a mix.
+
+## What does NOT get rewritten
+
+- The new project's encoded folder name (`new-repo`'s `C--...` form). This is computed from `--new-repo` and used as the target directory name; it isn't substituted into entry bodies.
+- File contents outside the session transcripts. The script operates only on text files inside the project directory under `~/.claude/projects/`.
+- Anything that doesn't include the old path as a substring. The script does literal substring matching, not pattern matching.
+
+## What to do when the new path is a substring of the old path (or vice versa)
+
+This happens when you migrate a session into a subdirectory of its current project (e.g. `Other Claude Code` → `Other Claude Code\Sub-Project`). The script handles it correctly thanks to longest-first sorting, but its post-migration verifier will produce **false-positive** warnings because every occurrence of the new path also contains the old path as a substring.
+
+See `references/troubleshooting.md` → "Stale reference false positive" for the recipe that distinguishes real stale references from prefix-containment artifacts.

package/skills/estack-migrate-claude-session-history/references/troubleshooting.md

@@ -0,0 +1,96 @@
+# Troubleshooting
+
+Specific failure modes that have actually happened, with the diagnostic and the fix.
+
+## Stale reference false positive
+
+**Symptom.** The script prints, for the migrated file:
+
+```
+Stale reference in: <new-path>\<uuid>.jsonl (matches: C:\\Users\\...)
+WARNING: Found N file(s) in the new project dir that still contain old path references.
+```
+
+**When this is harmless.** When the **new** project path contains the **old** project path as a prefix (e.g. you migrated `C:\Users\me\Workspace` → `C:\Users\me\Workspace\Sub-Project`), every successfully rewritten occurrence of the new path also contains the old path as a substring. The verifier does naive substring matching, so it flags itself.
+
+**Diagnostic — count GENUINELY stale occurrences.** Run the bundled validator with `--old-repo` and `--new-repo`; the "Stale path references" check uses a negative-lookahead that filters out the prefix-containment false positives. It also scopes the check to entries that existed at migration time, ignoring any later activity that legitimately references the old path:
+
+```bash
+python <skill-dir>/scripts/validate-migration.py \
+  "<target-jsonl>" \
+  --old-repo "<source-real-path>" \
+  --new-repo "<target-real-path>"
+```
+
+If that check passes, the migration script's own warning was a false positive — move on. If it fails, the failure detail names the specific entries and counts; figure out which encoding variant the migration script missed (see `path-encoding.md`) and either re-run with a fix or hand-patch the file.
+
+## Sidecar / subagent files left behind
+
+**Symptom.** The migrated session's brief shows `subagents: 0`, but the original had several. Or `--mode subagent-list` against the migrated file returns nothing.
+
+**Cause.** In an older version of the script's single-session mode, only the top-level `<uuid>.jsonl` was copied — the `<uuid>/subagents/` sidecar directory was missed because the filter matched on basename only.
+
+**Fix.** The current script copies the sidecar tree automatically when `--session` is set. If you see this symptom, you're running an out-of-date copy of the script. Use the bundled one at `scripts/migrate-claude-history.js`.
+
+**Recovery if it already happened.** Just re-run the migration. The script's "skip if destination exists" check means the already-copied `.jsonl` won't be touched, and the sidecar files will be added on the second pass.
+
+## Ambiguous UUID lookup
+
+**Symptom.** After migration, `read-claude-session-history --mode lookup --uuid <prefix>` returns:
+
+```
+Ambiguous prefix '<uuid>' matches 2 sessions:
+  <source-project>/<uuid>.jsonl
+  <target-project>/<uuid>.jsonl
+```
+
+**Cause.** This is expected and correct — the migration is non-destructive. The source copy is still in place as a safety net until the user confirms `/resume` works under the new project.
+
+**Fix.** Once the user has confirmed the migrated session resumes correctly under the new project, delete the source copy:
+
+```powershell
+Remove-Item "<source-project-encoded-dir>\<uuid>.jsonl"
+Remove-Item -Recurse "<source-project-encoded-dir>\<uuid>"  # sidecar dir
+```
+
+Never delete before the user confirms. The backup folder is a fallback if the user discovers something broken later, but the in-place source copy is the fastest recovery path.
+
+## /resume doesn't show the session under the new project
+
+**Symptom.** User runs `claude` in the new project's working directory, types `/resume`, and the migrated session doesn't appear in the list.
+
+**Diagnosis — go through these in order.**
+
+1. **Confirm the migrated `.jsonl` is in the right encoded folder.** The folder under `~/.claude/projects/` must exactly match the encoded form of the **real** path the user is `cd`'d into. Case differences (`C--Foo` vs `c--Foo`) and missing/added hyphens both break the match. Compare: get the real cwd → encode it (drop drive colon, replace separators with `-`) → ensure that's the folder name.
+
+2. **Confirm the `cwd` field inside the entries matches.** A surprising amount of `/resume` logic keys off the entries' `cwd` field, not the folder name. Run the distinct-cwd check from SKILL.md step 7 — every entry should be the new path (or empty for marker entries).
+
+3. **Confirm the `.jsonl` is not zero-byte or malformed.** Open it: `python -c "import json; [json.loads(l) for l in open(r'<path>', encoding='utf-8') if l.strip()]"` — if this errors, the migration corrupted something.
+
+4. **Check whether Claude Code stripped or reordered entries.** Claude Code occasionally writes `permission-mode` and `ai-title` metadata entries when something opens a file. These are harmless. But if the count is far off from the original (say, more than +5), something else is wrong.
+
+## "Cannot find old project directory" error from the script
+
+**Symptom.** Script exits with: `Could not find old Claude project directory. Checked: ...`
+
+**Cause.** The `--old-repo` value's encoded form doesn't match any folder under `~/.claude/projects/`. Most often this is because the user gave a real path that doesn't actually have any sessions yet (the project folder gets created lazily).
+
+**Fix.** Run `ls ~/.claude/projects/` and find the folder name that corresponds to the user's intended source. Reverse-engineer the real path from the folder name and pass that as `--old-repo`. The encoding is: `C--<rest>` becomes `C:\<rest with hyphens turned back into backslashes>`.
+
+## The migration note was accidentally appended twice
+
+**Symptom.** Two `<session-migration-note>` blocks at the tail of the file.
+
+**Cause.** Pre-fix versions of the append routine didn't dedupe; or the file was edited between two script runs.
+
+**Fix.** The current script checks the last few entries for an existing `<session-migration-note>` and won't append a duplicate. To clean up an already-doubled note, hand-edit the file: remove the older note entry, keep the newer one. Always backup the file first.
+
+## Forgetting `--session` and migrating the whole project
+
+**Symptom.** Script copies hundreds of files, takes much longer than expected, prints replacement counts in the thousands. The target project dir suddenly has many `.jsonl` files.
+
+**Cause.** Without `--session`, the script's default mode migrates **every** session in the source project — that's how the script was originally written, for the rename-a-project use case.
+
+**Fix.** Stop the script (Ctrl-C if still running). Delete the unintended files from the target project dir (compare with the target backup to know what wasn't there before). Re-run with `--session <uuid>` this time.
+
+This is why backing up the **target** dir matters as much as backing up the source — without it, recovering from this mistake is much harder.