docs/ghost hunk messaging

README.md

@@ -15,6 +15,8 @@ Operator cheat sheet (3 steps)
 Notes
 - Peeks are read-only; patches are explicit. Prefer generous peeks to avoid re-peeks.
 - Hunks in diffs should be listed bottom-to-top per file (descending order).
+- Avoid anchorless hunks: every `@@` hunk must include real, unchanged context lines above and below.
+- Prefer small hunks: one clear change per hunk beats a huge “miles of context” hunk.
 
 Requirements
 - git, bash; macOS, Linux, or Windows terminal. Basic command-line literacy.

docs/00-overview.md

@@ -39,7 +39,7 @@ Assistant template (one paragraph)
 - “Please run sharefiles in this repo and paste the snapshot. Then run sharefiles in your project repo and paste that. I’ll request a generous peek (±30–200 lines or full sections) of the exact lines I’ll edit, then return a unified diff with hunks listed in descending line order per file. I’ll keep changes scoped to the peek, avoid surprises, and iterate until green.”
 
 Glossary (at a glance)
-- Peek: read-only, numbered slice of files (nl -ba | sed -n 'START,ENDp').
+- Peek: read-only, numbered slice of files (nl -ba -s'|' | sed -n 'START,ENDp').
 - Generous peek: full section/function or ±100–200 lines to avoid re-peeks.
 - Patch: unified diff; one fenced block; ends with a newline.
 - Descending diffs: list hunks bottom-to-top per file to reduce offset drift.

docs/01-quick-start.md

@@ -1,104 +1,87 @@
 # Quick Start -- Peek → Patch → Apply (clipboard-first)
-
 Why this
-- GPT can't clone/push to your repo, and forgets contents of a zip archive quickly. A plain-text repo dump can persist.
-- We keep a tight loop: Share repo, then Peek → Patch → Apply → Test → Repeat.
-- Chat UIs slow down as context grows. Starting a fresh instance and getting back to speed quickly is essential.
-
+- GPT can't clone/push to your repo, and it often forgets contents of a zip archive quickly. A plain-text repo dump can persist.
+- We keep a tight workflow: Share repo, then Peek → Patch → Apply → Test → Repeat.
+- Chat UIs can slow down as context grows, making it essential to start fresh when lag occurs.
 Privacy Warning
 - Don't share private or unshareable repos without permission. Repeat that out loud and pause.  This workflow works by pasting the contents of all text files in a repo into GPT or similar chat.  That may not be ok for your situation, especially in a professional setting. Think before using. Don't neglect to think about embedded credentials or other secrets.
-
 Tools (scripts/)
 - Put these in your $PATH, copy them to your $HOME/bin, or otherwise make them accessible.
   - sharefiles -- copies repo list and all (text) tracked files to clipboard as fenced code blocks. Paste once per session.
   - applyPatch -- reads a diff from clipboard (or file), auto-fixes hunk counts, ensures final newline, then git apply.
   - fix-diff-counts.sh -- recomputes @@ hunk lengths from the body of the changes made.
   - toClip / fromClip - Agnostic clipboard adapters to copy to or paste clipboard contents to stdout.
-
 Contract (safety + cadence)
 - One action per step; everything clipboard-driven.
-- One patch per step: at any given step the assistant should provide at most one combined diff for you to apply, even if it touches multiple files.
+- One patch per step: at any given step, the assistant should provide at most one combined diff for you to apply, even if it touches multiple files.
 - The assistant only requests obvious, low-risk commands; the human operator should refuse anything unclear at a glance.
 - Always paste code/patches/logs as fenced code blocks that end with a newline.
 - The assistant batches multiple peeks into one block so the human runs one command per step.
 
 - Project-specific aliases like 'test', 'build', and 'lint' (that send output through toClip) are a good alternative to hard-coded scripts.
-
-Share This repo (once per session)
+### Note: `nl` delimiter (TAB by default) vs file bytes
+- By default, `nl -ba` uses a TAB delimiter between the line number and the real file content.
+- Prefer `nl -ba -s'|'` in peek commands so the delimiter is a visible pipe character instead.
+- In patches: avoid introducing TABs by accidentally copying peek formatting (applyPatch rejects TABs by default).
+### Share This repo (once per session)
 - From this repo run "sharefiles" and paste the clipboard into a fresh GPT session to get it up to speed quickly.
-```bash
+~~~bash
 scripts/sharefiles
-```
+~~~
 Assistant's first reply (template)
 - From the repo you want to work on, run this and paste the clipboard output here to share all the files at once:
-```bash
+~~~bash
 sharefiles
-```
+~~~
 - After I see the snapshot, I'll propose one tiny, low-risk first change, request a generous peek of the exact lines I'll touch, and return a unified diff you can apply with applyPatch.
 
 Assistant first peek request (template)
 - One command, generous windows, batched into a single clipboard block.
-```bash
+~~~bash
 {
   echo "=== Sources/Feature/FileA.swift (1-200) ==="
-  nl -ba Sources/Feature/FileA.swift | sed -n '1,200p'
+  nl -ba -s'|' Sources/Feature/FileA.swift | sed -n '1,200p'
   echo
   echo "=== Sources/Feature/ModuleB.swift (120-280) ==="
-  nl -ba Sources/Feature/ModuleB.swift | sed -n '120,280p'
+  nl -ba -s'|' Sources/Feature/ModuleB.swift | sed -n '120,280p'
   echo
   echo "=== Tests/ModuleBTests.swift (1-180) ==="
-  nl -ba Tests/ModuleBTests.swift | sed -n '1,180p'
+  nl -ba -s'|' Tests/ModuleBTests.swift | sed -n '1,180p'
 } | toClip
-```
+~~~
 - Adjust ranges to cover full functions/sections or ±100–200 lines when unsure.
 - Batch all needed peeks into one block so the operator runs a single command.
-- Never guess bytes—peek first; then patch with hunks in descending order per file.
-
-Share Your Project repo (usually once per session)
-- Right before pasting your repo snapshot is a good time to confirm a test patch, or share handoff instructions, or a goal.
-- Once you've shared your files, you're ready to begin.
-- Collaborate as makes sense. Partnership or pair programming techniques work well.
-- Expect assistant to make errors and generate compile/test errors just like any other partner might.
-- Scripts are designed to copy errors/results to clipboard, ready to paste into assistant to repair/retry.
+- Never guess bytes—peek first; then patch with hunks in descending line order per file.
 
-The loop
+### Tabs: mostly a non-issue if you use `nl -ba -s'|'` (still avoid in patches)
+- Default `nl -ba` uses a TAB between the line number and file content; `-s'|'` replaces it with a visible `|`.
+- So: prefer `nl -ba -s'|'` in peeks, and avoid introducing TABs into patches by copying peek formatting.
+- `applyPatch` rejects TABs by default as a guardrail; override only if you explicitly intend tabs.
+### The loop
 1) Assistant requests peek of places it will be patching. Peeks are directly executable shell command blocks.
-- Unfortunately assistants sometimes skip this step and go right to creating the patch. That patch will probably fail.
-- It's better to reject patches without a peek first, and create a cadence which usually works with fewer stumbles.
-- It's fun and goes quickly when this works well.
+- It's better to reject patches without a peek first and create a cadence which usually works with fewer stumbles.
 2) Paste peek request into shell, review for sanity/safety, then hit Return to load the clipboard. Paste directly to assistant verbatim.
-- What peeks do:
-   - nl -ba adds visible line numbers (including blanks) without changing bytes.
-   - sed -n 'START,ENDp' prints only that range.
-   - Both are read-only and safe.
-   - toClip copies standard input to the clipboard.
-   - Window size guidance:
-     - Err on wider windows to avoid re-peeking later.
-     - Small edit: ±30–80 lines around the target.
-     - Medium/uncertain: ±100–200 lines or the whole function/section.
-     - Multiple ranges are OK; batch into one fenced block so the operator runs a single command.
-     - Never guess bytes—peek, then patch.
-   - Typical bundle requested by the assistant:
-```bash
+- Typical bundle requested by the assistant:
+~~~bash
 {
   echo "=== Sources/Widget.swift (1-140) ==="
-  nl -ba Sources/Widget.swift | sed -n '1,140p'
+  nl -ba -s'|' Sources/Widget.swift | sed -n '1,140p'
   echo
   echo "=== Sources/Utils/Tools.swift (60-120) ==="
-  nl -ba Sources/Utils/Tools.swift | sed -n '60,120p'
+  nl -ba -s'|' Sources/Utils/Tools.swift | sed -n '60,120p'
   echo
   echo "=== Tests/WidgetTests.swift (1-200) ==="
-  nl -ba Tests/WidgetTests.swift | sed -n '1,200p'
+  nl -ba -s'|' Tests/WidgetTests.swift | sed -n '1,200p'
 } | toClip
-```
+~~~
 3) Assistant prepares and returns a fenced code block with its patch.
-   - Multi-file patches are OK only if we just peeked all touched files in one request. Otherwise, send a single-file patch and iterate.
+- Multi-file patches are OK only if we just peeked all touched files in one request. Otherwise, send a single-file patch and iterate.
    - Hunks must be listed in descending line order per file (bottom-to-top) to minimize offset churn during apply.
    - New files use --- /dev/null and +++ b/path; include the full file body in one hunk.
 4) Copy the returned patch, and apply it directly from the clipboard (applyPatch reads from the clipboard by default):
-```bash
+~~~bash
 applyPatch
-```
+~~~
 5) Build/test and send short logs:
 - As early as step two, errors can occur. When they do, just paste the error to the assistant and the loop restarts.
 - Just getting to the point where there are no compile errors and testing can be done can be challenging.
@@ -136,24 +119,24 @@ Unified diff in brief (what Assistant will create and paste back)
   - Lines: space = context, - = deletion, + = addition (LF endings)
 
 Replace one line (example)
-```diff
+~~~diff
 --- a/Sources/Foo.swift
 +++ b/Sources/Foo.swift
 @@ -42,3 +42,3 @@
     let x = foo()
 -   let y = oldCall(x)
 +   let y = newCall(x)
     return y
-```
+~~~
 
 Insert one line (example, characteristically with a bad count)
-```diff
+~~~diff
 --- a/Sources/Foo.swift
 +++ b/Sources/Foo.swift
 @@ -99,2 +99,3 @@
     vm.refresh()
 +   vm.bootstrapIfNeeded()
-```
+~~~
 
 Patch expectations
 - Pure unified diff in one fenced block: