Edmund architecture contract

Edmund is a native macOS Markdown editor with live preview: AppKit + TextKit 2, SwiftPM, macOS 14+. Two targets (Package.swift):

Project ambition (maintainer, 2026-07-05): product-first — "the CotEditor of Markdown editors". Bias toward polish of the editing experience over feature count. The hardest live problem class to date is delete-drift (caret/selection integrity, 6 investigation rounds); the costliest failures were delete-drift and undo/redo viewport drift. Every rule below traces to one of those scars.

Ground truth this file distills: docs/ARCHITECTURE.md (repo root). Treat that doc as authoritative if the two ever disagree, and fix this skill.

Glossary (each term defined once)

• rawSource — the document's Markdown text, the single source of truth (EditorTextView.rawSource).
• storage — the NSTextStorage the text view displays (EditorTextStorage, Sources/EdmundCore/TextView/EditorTextStorage.swift).
• Block — one logical Markdown block (paragraph, heading, list run, code fence, table, quote/callout run). Model: Sources/EdmundCore/Model/Block.swift.
• Active block — the block under the caret; it renders its raw markdown (delimiters visible/editable) while all others render styled.
• Recompose — restyling storage from blocks (Sources/EdmundCore/TextView/EditorTextView+Composition.swift).
• Fragment — an NSTextLayoutFragment, TextKit 2's per-paragraph layout unit. Off-screen fragments have estimated heights until laid out.
• Overlay — an image or stroked path drawn at a character's laid-out position by the custom fragment class (see §4), replacing what NSTextAttachment would do in TextKit 1.
• Delete-drift — the bug class where rawSource/storage/selection desync and every later edit lands the caret in the wrong place. Chronicle: docs/investigations/delete-drift-investigation.md.
• IME composition — an input method's provisional "marked text" (hasMarkedText()), present in storage before the user commits it.

1. The two non-negotiable invariants

Break either and the editor misbehaves in subtle, delayed ways. Every design review starts here.

Invariant 1 — storage == rawSource (attribute-only rendering)

The displayed text storage is always character-identical to rawSource. Rendering only ever adds/changes attributes. Delimiters (**, `, [!note], …) are hidden, never stripped: hiddenFont (0.01pt system font, Sources/EdmundCore/Rendering/EditorTextView+Rendering.swift:55) plus a clear foregroundColor makes them invisible without touching the string.

Rationale. Identity mapping between display offsets and raw offsets means there is no offset-translation layer — caret math, selection, undo diffs, incremental reparse, and autosave all operate on one coordinate system.

Consequences you must respect:

The incident. The original delete-drift bug: an async restyle fired during IME composition, stranded the marked text, didChangeText kept bailing on its own guard, and the invariant stayed silently broken — caret drift on every subsequent edit. becomeFirstResponder now resyncs from storage as a catch-all. Full write-up: docs/investigations/delete-drift-investigation.md.

Invariant 2 — TextKit 2 only

Never touch NSTextView.layoutManager (the TextKit 1 NSLayoutManager accessor) and never store NSTextBlock/NSTextTable attributes. Either one silently and permanently reverts the view to TextKit 1 — no error, no log, just different (and wrong-for-us) layout from then on.

Rationale. All custom drawing rides NSTextLayoutFragment subclassing (§4), and viewport-based layout (only on-screen content laid out) is what makes large documents fast. Both are TextKit 2 facilities; a TK1 fallback kills them.

The tripwire. DEBUG builds observe NSTextView.willSwitchToNSLayoutManagerNotification and assertionFailure if the fallback ever triggers — textKit1FallbackTripwire(_:), Sources/EdmundCore/TextView/EditorTextView.swift:272-303. If you see that assertion, some code path you touched used a TK1 API or attribute. Find it; do not suppress the assert.

Corollary: Edit-mode tables cannot use NSTextTable. Alignment is done by distributing slack via .kern on hidden pipe glyphs — Sources/EdmundCore/Rendering/EditorTextView+TableRendering.swift.

2. Render pipeline

rawSource ──BlockParser──▶ [Block] ──styleBlock per block──▶ attributed runs in storage
                                        │
                                        └─ SyntaxHighlighter (swift-markdown walker
                                           + custom parsers: callouts, ==highlight==,
                                           wikilinks, comments, footnotes, math,
                                           backslash escapes, inline HTML tags)

Recompose entry points (pick the narrowest that works — a full recompose resets every fragment height to an estimate, see §6):

Lazy styling (Sources/EdmundCore/TextView/EditorTextView+LazyStyling.swift): a large dirty set styles only the viewport synchronously; the rest is finished by the idle drain (time-budgeted main-thread slices) and scroll promotion (style blocks as they enter the viewport).

Gotcha: attribute-only changes do not re-measure geometry in TextKit 2. If a restyle changed a block's height/indent, call invalidateLayout(for:) on its range or the fragment keeps a stale frame. recomposeDirty and the idle drain already do this; any new path must too.

3. Edit flow & undo

Normal edit: shouldChangeText (records a coalesced undo snapshot) → NSTextView mutates storage → didChangeText syncs rawSource and restyles the edited block(s) (Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift, +Composition.swift). Edits capture a pendingEdit on EditorTextStorage and reparse a window, not the whole document.

Undo/redo is custom (Sources/EdmundCore/TextView/EditorTextView+Undo.swift): stacks of rawSource snapshots, bypassing NSTextView's built-in undo. Restoring diffs the snapshot against current text (textDiff(old:new:), single contiguous span) and applies it with the range-bounded recomposeReplacing — never a full recompose, because a full recompose resets every fragment to a TextKit 2 height estimate and the follow-up scroll lands wrong (this was the undo/redo viewport-drift failure). The changed text drives the viewport: hold if any of it is on-screen, else center it.

AppKit does NOT pair every storage mutation with didChangeText. Proven incident (delete-drift round 4): a drag-move of selected text dropped on no valid target deletes the dragged range via shouldChangeText → replaceCharacters and never calls didChangeText — silently freezing rawSource/blocks; every later edit drifts the caret and autosave writes stale text. The heal: shouldChangeText schedules a next-run-loop bypass check (scheduleBypassedEditSyncCheck, +EditFlow.swift) — a pendingEdit still unconsumed by then means the closing didChangeText never came, and the editor runs the same sync itself. Breadcrumb in ~/.edmund/logs: healing storage edit that bypassed didChangeText. Never build a sync path on the assumption that didChangeText follows every edit.

Round 6 corollary: a bypassed edit also leaves TextKit 2's private selection fixup (_fixSelectionAfterChangeInCharacterRange:) queued; it fires at the next endEditing — even an attribute-only restyle — and leaps the caret blocks away, moving even a freshly set valid caret. The heal sets the caret before the sync and re-asserts it after (+EditFlow.swift). This class does not reproduce headless; see the routing in §8.

4. TextKit 2 drawing model

All custom visuals are drawn by DecoratedTextLayoutFragment (custom NSTextLayoutFragment, Sources/EdmundCore/TextView/EditorTextView+TextKit2.swift:160), vended via the layout-manager delegate. Two custom attribute keys (same file, lines 28/32):

The image-wedge constraint (open, not solved). Drawing an image overlay on a multi-line (wrapping) fragment re-triggers a layout pass that wedges the fragment to one line. Drawing a shape (stroked CGPath) does not. That is why the wrapping callout custom-title icon is a stroked path parsed from vendored Lucide geometry, never an image. Any new overlay that could share a line with wrapping text must be a shape, not an image. Full saga: docs/investigations/archives/callout-title-wrap-investigation.md.

5. Read mode contract

Read mode is a separate WKWebView, not an editor styling mode (Sources/EdmundCore/Export/). The contract: one parser, two back-ends — the same swift-markdown Document the editor parses is walked by SyntaxHighlighter.SpanCollector (→ editor attributes) and by HTMLRenderer (→ HTML), themed from the same EditorTheme via HTMLTheme, so the two renderings cannot drift. When adding a feature, implement it in both back-ends or document the divergence.

Hard properties of the web view (keep them):

• JavaScript disabled; every asset inlined (math as high-DPI PNG data URIs — SwiftMath has no SVG path; icons as inline Lucide SVG) so it needs no file/network reach. Remote images off by default (Sources/EdmundCore/Export/ReadRenderOptions.swift).
• Private URL schemes route navigation without JS: x-edmund-wiki: / x-edmund-link: (Sources/EdmundCore/Export/HTMLRenderer.swift:26,31).
• Inline HTML: only the whitelist SyntaxHighlighter.htmlFormatTags (u/kbd/mark/sub/sup, Sources/EdmundCore/Parsing/SyntaxHighlighter.swift:22) renders in either mode; everything else stays escaped/color-only. A real <br> break would need to mutate storage — forbidden by Invariant 1.
• Export/Print run the same HTML through WKWebView.printOperation (Sources/EdmundCore/Export/MarkdownPrinter.swift) for vector text.

6. Known weak points (open as of 2026-07-05)

State these plainly when designing near them; none is solved.

1. TextKit 2 height estimates are the root of most viewport glitches: an off-screen fragment's frame (and the total document height) is an estimate until layout reaches it — scroller jumps, scroll-to-target lands wrong (a documented TK2 limitation; TextEdit shows it too). Mitigations in place, not cures: documents ≤ fullLayoutMaxLength (100k UTF-16, Sources/EdmundCore/TextView/EditorTextView.swift:80) are kept fully laid out by scheduleFullLayoutSettle() wrapped in preservingViewportAnchor (+LazyStyling.swift:121, +TypewriterScroll.swift:22); repairContentAboveOrigin() (+LazyStyling.swift:151) fixes content stranded above y=0; centerViewportOnCaret re-measures after its first scroll. Never trust an off-screen fragment's y-coordinate without laying out the span first.
2. The image-wedge constraint (§4) applies to every new overlay.
3. Open bugs (misc/backlog.md): callout at end-of-file renders an extra un-prefixed line in the callout color (live incremental-restyle path, not static rendering); footnotes don't render in either mode; attached images create blank space below; math doesn't render in read mode (and has wrong padding in edit mode); delete caret drift and viewport-estimate glitches remain on the ongoing list.
4. Crash reporter endpoint is a placeholder: CrashReporter.reportingEndpoint is https://REPLACE-ME.invalid/crash (Sources/EdmundCore/Diagnostics/CrashReporter.swift:27) and the Settings ▸ Advanced toggle is commented out (Sources/edmd/Settings/AdvancedSettingsView.swift). Do not treat crash uploading as live.

7. Before you design something new — checklist

Run this before proposing any new mechanism, subsystem, or refactor:

• Invariant 1: does it insert/strip characters, use NSTextAttachment, or mutate storage outside the shouldChangeText→didChangeText path (or during IME composition)? If yes, redesign as attributes/overlays.
• Invariant 2: does it touch NSTextView.layoutManager or store NSTextBlock/NSTextTable? If yes, stop.
• Sync assumptions: does it assume didChangeText follows every mutation, or that a set caret stays put across the next endEditing? Both assumptions are proven false (§3).
• Geometry: does it read an off-screen fragment frame, or restyle without invalidateLayout(for:) when height changed? (§2, §6.)
• Both back-ends: does a rendering feature cover Edit and Read (§5)?
• Prior art: check ARCHITECTURE.md §14 — especially nodes-app/swift-markdown-engine, an independent AppKit+TextKit 2 live-preview engine solving the same problems — before inventing a new mechanism for an editing-experience problem.
• Weak points (§6): does the design lean on anything listed there? Label it as such; unproven mitigations are "open/candidate", never "fixed".
• Verification plan: unit test if headless can repro; otherwise plan a live repro (ReproScript) — do not ship a caret/IME/viewport fix on reasoning alone. Visual claims are measured from screencapture pixels, not eyeballed.

Process rules live in sibling skills, but never contradict them here: branch per fix off main; never auto-push/PR/merge; swift test green + visual verification before commit; never blanket pkill -x edmd (the maintainer's daily-driver app shares the binary name — pgrep and kill only your own PID); never request macOS Computer Access permissions.

When NOT to use this skill

Provenance and maintenance

Facts verified against the repo on 2026-07-05. If a grep below stops matching, the fact drifted — update this file and cite the new location.

# Invariant 2 tripwire still present
grep -n "textKit1FallbackTripwire" Sources/EdmundCore/TextView/EditorTextView.swift
# Recompose entry points
grep -n "func recompose" Sources/EdmundCore/TextView/EditorTextView+Composition.swift
# Bypass heal
grep -n "scheduleBypassedEditSyncCheck" Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift
# Custom draw attributes + fragment class
grep -n "blockDecoration\|fragmentOverlay\|class DecoratedTextLayoutFragment" Sources/EdmundCore/TextView/EditorTextView+TextKit2.swift
# hiddenFont hiding trick
grep -n "hiddenFont" Sources/EdmundCore/Rendering/EditorTextView+Rendering.swift
# Viewport mitigations
grep -n "fullLayoutMaxLength" Sources/EdmundCore/TextView/EditorTextView.swift
grep -n "scheduleFullLayoutSettle\|repairContentAboveOrigin" Sources/EdmundCore/TextView/EditorTextView+LazyStyling.swift
# Read-mode schemes + HTML whitelist
grep -n "wikiScheme\|linkScheme" Sources/EdmundCore/Export/HTMLRenderer.swift
grep -n "htmlFormatTags" Sources/EdmundCore/Parsing/SyntaxHighlighter.swift
# Crash-reporter placeholder (delete §6.4 once this is a real URL)
grep -n "REPLACE-ME.invalid" Sources/EdmundCore/Diagnostics/CrashReporter.swift
# Open-bug list
sed -n '/^Bugs/,/^UI\/UX/p' misc/backlog.md

Edmund — build & environment runbook

All paths relative to the repo root. Facts date-stamped 2026-07-05 are volatile — re-verify per the last section.

When NOT to use this skill

1. Environment from scratch

Requirements (verified 2026-07-05):

create-dmg trap: install via npm, NOT Homebrew. brew install create-dmg is a different tool with an incompatible CLI. Not needed for dev work — only for cutting releases (see edmund-release-and-operate).

Dependencies are fetched by SPM on first build — nothing to install by hand (verified against Package.swift / Package.resolved, 2026-07-05):

• swift-markdown ≥0.5.0 (CommonMark/GFM parsing; pulls swift-cmark transitively)
• SwiftMath ≥1.7.0 (LaTeX rendering — its resource bundle is a launch-crash landmine, §3)
• Sparkle ≥2.6.0 (auto-update — its framework is a dyld-abort landmine, §4)

Two SPM targets: EdmundCore (library + all tests; most work happens here) and edmd (the app shell executable). The binary is named edmd even though the app presents as "Edmund" — deliberate, see the comment in Package.swift.

2. Core commands

swift build                    # debug build of both targets
swift test                     # full suite: ~750+ tests, ~10s (2026-07-05)
swift test --filter Callout    # one suite
./scripts/build-app.sh         # release build → build/Edmund.app

swift test also runs automatically as a Stop hook after code-touching turns.

3. What build-app.sh actually does (and why the order matters)

scripts/build-app.sh → build/Edmund.app. Steps, in order:

1. swift build -c release
2. Assemble build/Edmund.app/Contents/{MacOS,Resources}; copy .build/release/edmd, Info.plist, Resources/AppIcon.icns.
3. Compile Resources/Assets.xcassets with actool (falls back to /Applications/Xcode.app/.../actool if xcode-select points at the CLT).
4. Embed Sparkle.framework into Contents/Frameworks/ (found under .build/; SwiftPM links Sparkle but never copies the framework — without it the updater crashes on first check) and install_name_tool -add_rpath "@executable_path/../Frameworks" so @rpath resolves post-install.
5. Codesign inside-out: Sparkle.framework first (nested XPC helpers must be signed before macOS will launch them), then the whole .app (ad-hoc, --deep, identifier com.i7t5.edmd). Sealing the bundle — not just the binary — is what Sparkle's update validator requires.
6. Only after sealing: copy .build/release/*.bundle (SwiftMath's math fonts) into the .app root.

Why step 6 is last and at the root — two constraints collide:

• codesign refuses to seal a bundle with any extra item at the .app root ("unsealed contents present in the bundle root"), so the seal must happen while the root holds only Contents/.
• SwiftMath's generated Bundle.module accessor hardcodes Bundle.main.bundleURL — the .app root — with only a hardcoded absolute .build path as fallback. So the bundle must sit at the root.

Resolution: seal first, copy after. The one unsealed root item makes codesign --verify and --strict complain, but Sparkle's actual check is non-strict and tolerates it (verified end-to-end; details in docs/ARCHITECTURE.md §8).

Missing SwiftMath bundle = instant crash the moment the app renders any LaTeX. App launches fine, opens documents fine, dies on the first math block. If you see that crash, check ls build/Edmund.app/*.bundle first.

4. Debug bundle fast path (EdmundDbg.app)

For live runs of a debug build, skip build-app.sh and hand-assemble (from docs/dev-guides/live-repro-guide.md §4):

swift build
mkdir -p build/EdmundDbg.app/Contents/MacOS
cp Info.plist build/EdmundDbg.app/Contents/
cp .build/arm64-apple-macosx/debug/edmd build/EdmundDbg.app/Contents/MacOS/
cp -R .build/arm64-apple-macosx/debug/Sparkle.framework build/EdmundDbg.app/Contents/MacOS/

• Sparkle.framework must sit next to the binary — dyld aborts without it.
• A bare .build/debug/edmd runs but never creates a window. It needs the bundle (Info.plist) around it.
• Launch by direct exec of the bundle binary, never open -a:

build/EdmundDbg.app/Contents/MacOS/edmd /path/to/test.md \
  -ApplePersistenceIgnoreState YES &

LaunchServices (open -a) can silently run a stale cached/translocated copy — you'd be executing last hour's code. Direct exec runs exactly the binary you just copied. -ApplePersistenceIgnoreState YES stops state restoration from reopening previous (possibly mutated) documents.

• Recreate the test document fresh before every run — autosave mutates it.

5. THE STALE BUILD DISEASE

The single most expensive trap in this repo: it has produced entire wrong debugging conclusions ("my fix doesn't work" when the fix was never in the binary).

Symptom: swift build prints Build complete! having compiled a changed file but not relinked edmd. The app then runs old code. Release builds (swift build -c release / build-app.sh) reuse stale objects too.

Detection — before trusting ANY binary you just built:

# 1. Grep for a LONG string literal unique to your new code:
strings .build/arm64-apple-macosx/debug/edmd | grep 'your long unique literal'
# 2. Hash before/after the build:
shasum .build/arm64-apple-macosx/debug/edmd

Literal length matters: string literals ≤15 bytes are stored inline in the Mach-O on arm64 and never appear in strings output. A short probe literal gives a false "stale" verdict. Use a long one (a distinctive log message works well).

Cure:

swift package clean          # first resort
rm -rf .build                # visual change "doesn't take" → nuke it all

Never hand-delete .build/…/edmd.build/ — that corrupts SwiftPM's output-file-map and wedges the target until a full clean anyway.

6. Running for visual checks — launch/kill hygiene

The user's daily-driver app has the same binary name (edmd). A blanket pkill -x edmd kills their live session. Always, in order:

# 1. Who is running, and since when?
pgrep -lx edmd
ps -o lstart=,command= -p <pid>
# 2. Kill ONLY your own PID — or, if you launched the debug bundle:
pkill -f EdmundDbg

Other run gotchas:

• open Edmund.app foregrounds a running instance instead of relaunching — you'll be looking at the old binary. Kill your instance first or direct-exec the binary.
• Always pass -ApplePersistenceIgnoreState YES (see §4).
• After many rapid launch/kill cycles the window server can glitch (tiny windows, broken state restoration): rm -rf ~/Library/"Saved Application State"/com.i7t5.edmund.savedState and relaunch.
• Verification method (window-id screencapture, offscreen render fallback): edmund-validation-and-qa and docs/ARCHITECTURE.md §8.

7. CI environment

.github/workflows/ci.yml (verified 2026-07-05): runs swift test on macos-14 with latest-stable Xcode (Swift 6.0 needs Xcode 16+), triggered on PRs and pushes to main.

• SPM cache: .build is cached keyed on spm-v2-${{ runner.os }}-${{ hashFiles('Package.resolved') }}. The v2 token exists because the repo rename md → Edmund changed the checkout path and invalidated absolute paths baked into the cached module cache — bump the token to discard a poisoned cache.
• Concurrency: cancel-in-progress: true per branch/PR — private-repo macOS minutes bill at 10x, so superseded commits' runs are cancelled.
• Release pipeline (release.yml, tag-triggered) is a separate beast: edmund-release-and-operate / docs/ARCHITECTURE.md §13.

8. Checklists

Fresh clone to green

• sw_vers — macOS 14+; swift --version — Swift 6.x (Xcode 16+)
• git clone + cd Edmund
• swift build — SPM fetches swift-markdown, SwiftMath, Sparkle
• swift test — ~750+ tests green in ~10s
• Read docs/ARCHITECTURE.md (mandated by AGENTS.md before non-trivial work)
• Visual work planned? ./scripts/build-app.sh, confirm build/Edmund.app exists and ls build/Edmund.app/*.bundle shows the SwiftMath bundle
• Releases planned? node --version ≥20, npm install --global create-dmg

Before trusting any run

• Binary is fresh: strings <binary> | grep '<long unique literal>' and/or shasum changed since the edit (§5)
• pgrep -lx edmd — user's live instance identified; you will kill only your own PID (§6)
• Launched by direct exec, not open -a (§4)
• -ApplePersistenceIgnoreState YES passed
• Test document recreated fresh (autosave mutated the last one)
• Debug bundle: Sparkle.framework sits next to the binary
• Release bundle: SwiftMath *.bundle at the .app root (or the first LaTeX render crashes)

Provenance and maintenance

Every claim above was read from the files below on 2026-07-05. Re-verify:

• Toolchain/deps: cat Package.swift (tools-version, platforms, dep versions); grep identity Package.resolved
• Build anatomy: cat scripts/build-app.sh (step order, sealing comments)
• Test count/time: swift test 2>&1 | tail -3
• Debug bundle recipe: docs/dev-guides/live-repro-guide.md §4
• Stale-build disease, launch gotchas: docs/ARCHITECTURE.md §8 ("Stale release builds", "open Edmund.app", savedState)
• CI facts: cat .github/workflows/ci.yml (cache key comment, concurrency)
• create-dmg quirks: docs/ARCHITECTURE.md §8 ("create-dmg — npm only")

If a command here disagrees with those files, the files win — update this skill.

Caret-integrity campaign (the delete-drift class)

Six rounds are settled; new rounds are expected. This class does not reproduce in headless tests — the harness runs AppKit's deferred machinery synchronously, so a green unit test proves nothing here. Success is measured by PASS/FAIL grep and byte counts, never by eye or by reasoning.

Verified 2026-07-05 against docs/investigations/delete-drift-investigation.md (456 lines) and the code. Read that doc fully before a deep dive.

QUICK CARD (the whole loop)

0. CLASSIFY   grep logs for the 4 signatures. Not this class? → debugging-playbook.
1. FENCE      check the 6 settled battles + guards still hold. Don't re-fight them.
2. EVIDENCE   run with verbose diags; find FIRST bad line; walk BACKWARDS;
              traceSelectionOrigin names who moved the caret; rebuild the doc.
3. REPRO      ReproScript: needles not offsets; real events; replicate internal
              call sequences verbatim. Freeze a script whose logsel/assertcaret
              DISCRIMINATES broken vs current build. No repro → hypothesis wrong.
4. SOLVE      rank candidates (missing guard < extend heal < reorder fixup <
              structural). Each states what it must PROVE.
5. PROMOTE    fix flips frozen repro to PASS same run → soak 4–5 cycles,
              byte-identical rawLen → swift test green → add test (locks headless
              contract even if non-discriminating) + keep .repro → update the
              investigation doc → branch/commit via change-control. Never ship on
              reasoning alone.

PHASE 0 — Classify: is it actually this class?

Grep ~/.edmund/logs/edmund-<date>.log (run the app with -settings.general.diagnosticLogging YES -settings.advanced.verboseEditorDiagnostics YES):

scripts/grep-trace.sh in edmund-live-repro-and-diagnostics surfaces all four at once.

If none match and the symptom is scroll/viewport-shaped (jump, wrong landing, can't-scroll-up) with the caret not leaping → this is the viewport class, not caret integrity → edmund-debugging-playbook + docs/investigations/viewport-glitch-investigation.md. Do not run this campaign on a viewport bug.

PHASE 1 — Fence off the six settled battles

Confirm each shipped guard still holds before hypothesizing a new mechanism. The most likely round-7 shape is a new code path that lacks an existing guard, not a new mechanism.

Confirm the guards exist:

grep -rn 'hasMarkedText' Sources/EdmundCore/TextView/
grep -n 'scheduleBypassedEditSyncCheck\|healing storage edit' Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift

FENCED WRONG PATHS (each proven dead — do not retry)

• Fixing by nudging the caret at symptom time. The symptom is armed seconds-to-minutes earlier (round 6: drift at 22:13 armed at 22:11:57). You'd patch the wrong instant.
• Trusting a headless regression test. The round-6 test passes with and without the fix. Headless runs the fixup synchronously.
• Shipping on reasoning alone. Rounds 1–5 all came back. Round 6's first fix candidate "worked by reasoning" and failed in the repro within a minute.
• Assuming didChangeText pairs with every mutation. AppKit violates this (round 4).
• Mutating storage mid-composition. That is the original bug (rounds 1–3).
• Expecting a scripted keystroke replay to arm round 7. Round 7 was replayed faithfully from a reconstructed t0 (every keystroke + capped pauses through the whole drift window) and it did not produce the block-end leap. Programmatic caret moves (clickoff) and imprecise synthetic clicks (realclickoff — lands off-by-a-few, diverges, crashes) do not fully arm it. The arming needs real mouse clicks at real positions and probably the real session's two-document window switching (becomeFirstResponder resync is the prime suspect). Round-8 lead: two open docs + real clicks, or instrument becomeFirstResponder/the caret-move restyle to catch the next live occurrence. Compressed replays also coalesce a bypass with the next keystroke into one pendingEdit hull (never happens live — the heal runs first), producing off-by-one breadcrumb noise; don't trust it as a repro.

PHASE 2 — Capture evidence

1. Launch with verbose diagnostics (debug bundle; file arg is argv[1]):

   build/EdmundDbg.app/Contents/MacOS/edmd DOC.md \
     -settings.general.diagnosticLogging YES \
     -settings.advanced.verboseEditorDiagnostics YES \
     -ApplePersistenceIgnoreState YES
   

2. Decode the trace fields: sel/active/marked/up/undo/blocks/storLen/rawLen. up=Y = event arrived mid-recompose (suspicious). Healthy ordering: shouldChangeText → selectionDidChange (up=N) → synced; a transient ⚠︎LEN-MISMATCH between those is normal, a persisting one is not.
3. Find the FIRST bad line, then walk BACKWARDS. The visible symptom is often the second half of a two-part mechanism.
4. traceSelectionOrigin logs the call stack of whoever moved the selection mid-recompose — this is what named _fixSelectionAfterChange in round 6. If the caret moves and you don't know who moved it, this answers it in one run.
5. Reconstruct the document. Wrapped-paragraph geometry and block kinds matter — repro against a lookalike, never "hello world".

Gate: you have a candidate trigger hypothesis + the first-bad-line timestamp. Otherwise instrument (add a Log.shouldTrace breadcrumb — one call stack or state dump beats ten speculative fixes) and wait for the next occurrence.

PHASE 3 — Build the deterministic repro

Use the in-process ReproScript driver (Sources/edmd/App/ReproScript.swift, DEBUG only; full guide in edmund-live-repro-and-diagnostics). Commands: sleep / caret / type / backspace / bypassdelete / assertcaret / logsel.

Worked example — the round-6 minimal repro (the first deterministic repro in six rounds):

sleep 2000
bypassdelete Sizemore,
sleep 800
logsel            # broken build: 321   fixed build: 290
backspace 2
logsel

The deciding output was logsel 321 → 290 with the fix, every run, window not even visible.

Rules that make repros survive editing:

• Needles, not offsets — offsets go stale the instant the script edits.
• Real events, not method shortcuts — insertText("") skips deleteBackward's selection machinery, exactly where round 6 lived.
• Replicate AppKit-internal call sequences verbatim — bypassdelete does shouldChangeText→replaceCharacters, no didChangeText, not an approximation. For a new internal path, pin its real sequence from a traceSelectionOrigin stack first, then replay it (extend ReproScript ~10 lines).

Gate: a frozen script (exact commands + document) whose logsel / assertcaret PASS/FAIL output discriminates the broken build from the current one.

No repro after honest attempts? The hypothesis is wrong, or fidelity is too low — a mouse-only path (real drag-select/drag-move) needs the CGEvent driver (edmund-live-repro-and-diagnostics §4). Loop back to Phase 2.

PHASE 4 — Solution menu (ranked; each with a proof obligation)

Pick by the observation pattern. Cheaper is higher.

1. Add a missing guard on an existing invariant (cheapest, most likely for a new round). Guard inventory: !hasMarkedText() on the offending styling path; bypass-check scheduling on a new mutation entry point; caret re-assertion after a restyle. Proof: the frozen repro flips to PASS and no other .repro regresses. Selects when: a specific new code path shows the round-1/4/6 signature that its siblings already guard.
2. Extend the heal to a new bypass source. Proof: first add a ReproScript command that replays the new source's exact call sequence, show it reproduces the freeze, then show the extended heal fixes it. Selects when: trace shows a shouldChangeText with no close-out from a path other than drag-move.
3. Intercept/reorder the queued fixup. Proof obligation: explain when TK2 queues and fires _fixSelectionAfterChange and show the reorder does not fight AppKit's machinery (no oscillation, no double-move). Selects when: traceSelectionOrigin names the fixup and the caret is valid before it fires. Higher risk — you are stepping into private AppKit ordering.
4. Structural: make rawSource sync independent of didChangeText pairing (e.g. a storage-version counter that reconciles regardless of which callbacks fired). Biggest change; candidate, unproven — route through edmund-research-frontier (frontier item "caret integrity by construction"). Proof: all historical .repro scripts + a randomized bypass-fuzzer soak stay green with the callback-pairing assumption removed.

PHASE 5 — Validate and promote

1. Fix candidate flips the frozen repro to PASS within the same run. (If it only "works by reasoning," it is not done — round history.)
2. Soak (edmund-live-repro-and-diagnostics §3): one script, one run, 4–5 trigger cycles at different document positions with ordinary editing between, assertcaret after every predictable step. Green across all cycles and byte-identical final rawLen across repeated runs = deterministic.
3. swift test green (also the Stop hook).
4. Add a regression test even if it can't discriminate the live mechanism — it locks the headless contract (assert rawSource == string; see the BypassedEditSyncTests / MarkedTextDesyncTests family). Keep the .repro script in the repo for the live half.
5. Update docs/investigations/delete-drift-investigation.md with the new round (symptom → root cause → repro recipe → fix → status), and docs/ARCHITECTURE.md §8 if an invariant changed — same PR.
6. Route through edmund-change-control: branch fix/… off main, small commits, never auto-push/PR/merge. (No screencapture unless the fix also draws.)

Never promote a fix that only "works by reasoning."

When NOT to use this skill

• Viewport/scroll drift where the caret itself does not leap → edmund-debugging-playbook + docs/investigations/viewport-glitch-investigation.md.
• Just need the repro driver mechanics / trace decoding → edmund-live-repro-and-diagnostics.
• The AppKit theory behind the mechanisms → textkit2-appkit-reference.
• The historical record of prior rounds → edmund-failure-archaeology.
• The structural (round-∞) redesign as a research project → edmund-research-frontier + edmund-research-methodology.

Provenance and maintenance

Verified 2026-07-05 against docs/investigations/delete-drift-investigation.md, Sources/edmd/App/ReproScript.swift, and Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift.

grep -nE '^## Round' docs/investigations/delete-drift-investigation.md          # round chronicle
grep -n 'scheduleBypassedEditSyncCheck\|healing storage edit' Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift
grep -rn 'hasMarkedText' Sources/EdmundCore/TextView/
grep -oiE '"(bypassdelete|assertcaret|logsel)"' Sources/edmd/App/ReproScript.swift | sort -u
# round-6 discriminating numbers (321 broken / 290 fixed):
grep -n '321\|290' docs/investigations/delete-drift-investigation.md

When round 7 lands, add its row to Phase 1 and its dead ends to the fenced list.

Edmund change control

Last verified: 2026-07-05, against main @ fe8a1f5 (release 0.1.3).

This is the gatekeeping doc: what class of change you are making, which gate it must pass, and the rules that are never traded away. The rules exist because each was paid for — the incident column is not decoration.

0. Before you start (task setup)

[ ] Read docs/ARCHITECTURE.md before any non-trivial change (its own rule)
[ ] git status — note any uncommitted work; never clobber it
[ ] Not on main? Fine. On main? Branch NOW, before the first edit
[ ] Classify the change (§1) so you know the gate before you write code
[ ] Edit-pipeline / selection work? Plan the live repro FIRST — if you can't
    reproduce the bug, you can't prove the fix (§3, last row)

1. Classify the change, apply the gate

Classify FIRST, before writing code. The class decides the verification bar.

Notes on the gates:

• swift test (~750+ tests, ~10s) also runs automatically as a Stop hook (.Codex/settings.json: swift test 2>&1 | tail -5) at the end of every turn. That is a safety net, not the gate — run it yourself before committing so the failure is yours to see, not the hook's.
• A change can be in multiple classes. Apply the union of gates. A caret fix that also moves a decoration needs test + screencapture + live repro.
• "Draws" is broad: padding, insets, colors, wrapping, fragment frames. If a human could see the diff, screenshot it.

Classification edge cases that have gone wrong before:

• "It's just an attribute change" is NOT automatically the code-logic class. If the attributes change measured geometry (font size, paragraph spacing, hidden-delimiter width), it draws AND it needs invalidateLayout(for:) — see §3.
• "It's just a restyle helper" that runs beginEditing/setAttributes on storage is edit-pipeline class if it can fire during IME composition or after a bypassed edit. When in doubt, grep for hasMarkedText guards on the sibling paths and match them.
• A test-only change is docs-class for gating purposes (nothing to screenshot), but the Stop hook still must pass — a broken test is a broken commit.
• Release-adjacent edits (Info.plist versions, CHANGELOG.md, appcast.xml, scripts/release.sh, .github/workflows/) are release class even when tiny. The v0.1.0→0.1.1 Sparkle failure came from the build script's signing step, not from app code.

2. Git discipline

From AGENTS.md + ARCHITECTURE §12 + the repo's own history (git branch -a).

• Branch off main for every fix. Never commit straight to main. One feature/fix per branch.
• Branch prefixes actually in use (verified): fix/, feat/, feature/, docs/, chore/, uiux/, ui/, ux/, markdown/, bug/, refactor/, ci/, release/. Prefer fix/, feat/, docs/, chore/ for new work; uiux/ for visual polish; markdown/ for syntax-feature work.
• Small, logical commits; commit frequently. A commit that mixes the fix with a drive-by refactor is two commits done wrong.
• NEVER auto-push, open a PR, or merge. Only when the maintainer explicitly asks. No exceptions for "it's just docs."
• Never discard uncommitted changes. No git checkout -- ., git reset --hard, git clean on a dirty tree without explicit permission.
• Commit messages follow the observed style: fix(editor): …, docs: …, ui: …, chore: … — short imperative subject.

3. The non-negotiables

Each rule was established by an incident. Verify against the cited doc before arguing an exception.

The two incidents that shaped this table

Worth knowing as stories, because the rules read as pedantry until you see the cost:

• Delete-drift (six rounds). The hardest live problem this repo has had. A caret that drifted after deletes. Round 1 blamed IME stranding — plausible fix, shipped, recurred. Round 2 disabled remaining marked-text sources — recurred. Round 3 stopped guessing and built diagnostics (selection tracing, event logs). Round 4's diagnostics caught a drag-move deleting storage with no didChangeText — the heal was born. Round 5: the heal itself leaped the caret via a stale selection. Round 6 found the actual drift mechanism — TextKit 2's queued _fixSelectionAfterChange firing at the next endEditing — and held only because the ReproScript driver could replay the exact keystroke sequence deterministically. Five shipped fixes failed; the one preceded by a frozen repro stuck. That asymmetry IS the change-control policy for this bug class.
• Undo/redo viewport drift. Undo restored a snapshot via full recompose, which reset every fragment to a TK2 height estimate; the follow-up scroll-to-caret then landed wrong and the viewport jumped. The fix (5bb2b40) diffs the snapshot against current text and applies only the changed span with recomposeReplacing. Moral: in TK2, layout state is part of the document state you must preserve — "re-render everything" is never the safe fallback here, it is the bug.

4. Review expectations

• ARCHITECTURE.md is updated in the same PR whenever you learn something non-obvious or change an invariant. The doc's own header demands this; the gotchas in §8 all arrived this way.
• Quirks are documented as comments at the code site — the edge case, the workaround, the why. Not in commit messages, not in AGENTS.md.
• New known issues go in ARCHITECTURE §9 with a one-line repro and a pointer to any deeper write-up in docs/.
• Big investigations (multi-round bugs) get a docs/*-investigation.md chronicle — see edmund-failure-archaeology for the pattern.

5. Pre-commit checklist (copy-paste)

The workflow that worked (ARCHITECTURE §12 + AGENTS.md). Run it verbatim:

[ ] swift test — all green (also enforced by the Stop hook; don't rely on it)
[ ] New behavior / bug fix → a test exists that fails without the change
[ ] Draws anything? → build app, screencapture window-by-id, look at the PNG
[ ] Edit-pipeline / selection change? → live repro or soak script passed
[ ] On a branch off main (fix/…, feat/…, docs/…, chore/…), NOT on main
[ ] Diff touches only what the task needs; style matches surroundings
[ ] Learned something non-obvious? → ARCHITECTURE.md updated in this change
[ ] Quirk introduced/found? → comment at the code site
[ ] Commit is small and logical; message matches repo style (fix(scope): …)
[ ] NOT pushing, NOT opening a PR, NOT merging (unless explicitly asked)

6. Ask the maintainer first — always

Never do these unprompted; ask and wait for an explicit yes:

When NOT to use this skill

Provenance and maintenance

• Sources: AGENTS.md (repo root), docs/ARCHITECTURE.md §1 §2 §8 §9 §12, .Codex/settings.json (Stop hook), misc/before-you-release.md, misc/how-to-release.md, docs/investigations/delete-drift-investigation.md (rounds 1–6), docs/investigations/archives/callout-title-wrap-investigation.md, git log / git branch -a as of fe8a1f5 (2026-07-05).
• Commits cited were verified in git log: 5bb2b40 (diff-based undo restore), 9f99795 (round-4 heal), ae61644 (stroked-path callout icon), 1b1420a (round-6 caret re-assert).
• Two rules rest on maintainer statements rather than repo docs: the measure-from-pixels rule and the test-files/ ownership rule. If either gets written into ARCHITECTURE.md, point at it here.
• Maintain: when a new incident produces a new rule, add a row to §3 with the incident pointer in the same PR that adds the rule to ARCHITECTURE.md. When the Stop hook in .Codex/settings.json changes, update §1's note.

Edmund configuration & flags

Ground-truth catalog of every knob. Code wins over docs — every value below was read from source on 2026-07-05; re-verify with the greps at the end before trusting a value in a decision.

Two source-of-truth files:

• Sources/edmd/Settings/AppSettings.swift — every UserDefaults key + typed accessor.
• Sources/edmd/Settings/*View.swift (Appearance / General / Advanced) + FontSettings — the SwiftUI panes (@AppStorage).

Definitions used below: UserDefaults = macOS per-app persisted key/value store; argument domain = passing -<key> <value> on the command line overrides that default for one launch; @AppStorage = SwiftUI wrapper binding a view to a UserDefaults key.

1. User settings (UserDefaults keys)

Every key is a static let in AppSettings.swift. The key string (not the Swift name) is what you pass as a launch arg.

Content width (the physical-column design): persisted as centimetres (maxContentWidthCm); contentWidthUnit is a display unit only. The column is an absolute physical cap converted to points via the display's real PPI (NSScreen.physicalPPI, from CGDisplayScreenSize), applied as a symmetric textContainerInset.width. Default is locale-aware — 5 in (US) / 12 cm (elsewhere) — and doubles as the slider's magnetic snap point. Recomputed on resize and on NSWindow.didChangeScreenNotification. Consumer path lives in EditorTextView+ContentWidth.swift.

Window sizing trap: persistence must round-trip the frame size, not the contentView.bounds size — reapplying content size grows the window by the title-bar + toolbar height on every reopen, and heights below minSize get silently rejected. Save window.frame.size, reapply with window.setFrame(_:) after the toolbar is installed. (Note: the key on disk is settings.window.lastHeight — code, not the lastWindowSize some docs say.)

Crash uploading is inert: sendCrashLogs defaults off AND the Settings ▸ Advanced toggle is commented out in AdvancedSettingsView.swift, and CrashReporter.reportingEndpoint is a REPLACE-ME.invalid placeholder (CrashReporter.swift:27, // TODO: real server). Nothing uploads today. Un-inert it only when a receiving server exists (see edmund-release-and-operate).

2. Launch arguments

macOS reads -<UserDefaults-key> <value> into the argument domain. Pass the key string from §1, not the Swift name. The file to open must be argv[1] (before the flags).

build/EdmundDbg.app/Contents/MacOS/edmd FILE.md \
  -settings.general.diagnosticLogging YES \
  -settings.advanced.verboseEditorDiagnostics YES \
  -debug.reproScript SCRIPT.repro \
  -ApplePersistenceIgnoreState YES

-debug.reproScript is the only Edmund-specific debug key; it does not have an AppSettings accessor — it is read directly in ReproScript.swift. It is compiled out of release builds.

3. Compile-time axes

#if DEBUG gates live in: EditorTextView.swift, EditorTextView+EditFlow.swift, Diagnostics/Log.swift, edmd/App/main.swift, edmd/App/ReproScript.swift. What they gate:

• The TextKit-1 tripwire (EditorTextView.swift:273+): a DEBUG observer on NSTextView.willSwitchToNSLayoutManagerNotification that asserts if the view ever falls back to TextKit 1. Ships only in DEBUG; the fallback itself is silent and permanent (see edmund-architecture-contract).
• ReproScript — the whole in-process keystroke driver.
• Log level threshold — Log.swift compiles a lower floor in DEBUG (debug+) than release (info+); see §4.

Named tuning constants (not user-facing, but they behave like knobs):

4. Logging config

Read Sources/EdmundCore/Diagnostics/Log.swift and EditorTextView+Diagnostics.swift.

• API: Log.{debug,info,error}(_:category:), Log.measure(_:) { … }.
• File: ~/.edmund/logs/edmund-YYYY-MM-DD.log, written on a private serial queue.
• Config flow: AppSettings.applyLogging() pushes the toggle + retention into Log.configure at launch and on change; retention pruning happens there.
• Two independent switches: diagnosticLogging (writes anything at all) and verboseEditorDiagnostics (adds the per-event editor trace). For a live repro you almost always want both on. Verbose lines are gated behind Log.shouldTrace.
• The log is opt-out (on by default), retention-pruned; the user only toggles it and picks a retention window in Settings ▸ General ▸ Diagnostics.

Trace-field decoding (sel/active/marked/up/undo/blocks/storLen/rawLen, ⚠︎LEN-MISMATCH, traceSelectionOrigin) is covered in edmund-live-repro-and-diagnostics and edmund-debugging-playbook — one home per fact; this skill only says which flags turn the trace on.

5. ReproScript command surface

Sources/edmd/App/ReproScript.swift, DEBUG only. One command per line, # comments allowed.

Adding a command is ~10 lines in ReproScript.swift. Usage, soak patterns, and launch recipe: edmund-live-repro-and-diagnostics.

6. How to ADD a setting (checklist)

Worked from an existing real path (sourceMode / content width). To add a user-facing setting:

1. Add a static let key + typed accessor in AppSettings.swift (namespace the key string: settings.<area>.<name>).
2. Bind it in the relevant SwiftUI pane with @AppStorage(AppSettings.<key>).
3. If it must affect open documents live, add/extend an applyTo… broadcast (see the font/line-height/content-width applyTo… helpers) so every open Document.editor picks it up — a setting that only takes effect on next open is usually a bug.
4. Pick a sane default (register it, or make the accessor default when absent).
5. New behavior needs a test + (if it draws) a screencapture check — route through edmund-change-control and edmund-validation-and-qa.

When NOT to use this skill

• Understanding why an invariant exists → edmund-architecture-contract.
• Release/signing/appcast flags, RELEASE_TOKEN, Sparkle keys → edmund-release-and-operate.
• Interpreting log output / running a repro → edmund-live-repro-and-diagnostics.
• Which change needs which gate → edmund-change-control.
• Build-time flags in the toolchain sense (stale builds, swift package clean) → edmund-build-and-env.

Provenance and maintenance

Verified 2026-07-05 against source. This skill drifts fastest — re-verify each table before relying on it:

# §1 all keys + strings:
grep -nE 'static let [a-zA-Z]+ = "[a-zA-Z0-9._]+"' Sources/edmd/Settings/AppSettings.swift
# §1 crash toggle still commented out / endpoint still placeholder:
grep -n 'Crash reports:' Sources/edmd/Settings/AdvancedSettingsView.swift
grep -n 'reportingEndpoint' Sources/EdmundCore/Diagnostics/CrashReporter.swift
# §2 repro flag key:
grep -n 'debug.reproScript' Sources/edmd/App/ReproScript.swift
# §3 tripwire + constant:
grep -n 'willSwitchToNSLayoutManager' Sources/EdmundCore/TextView/EditorTextView.swift
grep -n 'fullLayoutMaxLength' Sources/EdmundCore/TextView/EditorTextView.swift
# §5 repro commands:
grep -oiE '"(sleep|caret|type|backspace|bypassdelete|assertcaret|logsel)"' Sources/edmd/App/ReproScript.swift | sort -u

Known doc-vs-code discrepancies (code wins): ARCHITECTURE §7 calls the window-size key lastWindowSize; the code key is settings.window.lastHeight (lastWindowHeight). If you touch window persistence, trust the code.

Edmund debugging playbook

Date-stamped 2026-07-05. Runbook for triaging any Edmund bug. Start at the triage table, run the discriminating first check before forming a theory, and check the open-bug inventory before declaring a discovery.

When NOT to use

• Making a change, not chasing a bug → edmund-change-control.
• You already know the bug is live-only and need to build a deterministic repro → edmund-live-repro-and-diagnostics (full ladder detail; summary in §5 here).
• Caret-drift class specifically, with its six-round history → edmund-caret-integrity-campaign.
• Build/toolchain/stale-binary mechanics beyond the quick checks here → edmund-build-and-env.
• Release, signing, appcast, Sparkle pipeline → edmund-release-and-operate.
• TextKit 2 / AppKit API semantics reference → textkit2-appkit-reference.
• Launch flags and settings keys reference → edmund-config-and-flags.
• How past investigations were run and why → edmund-failure-archaeology, edmund-research-methodology.
• Pre-merge verification of a fix → edmund-validation-and-qa.

1. First 15 minutes — any new bug

Run this checklist before hypothesizing. Every step is cheap; skipping them is how rounds 1–5 of delete-drift shipped fixes that came back.

1. Check the open-bug inventory (§6). If the symptom matches a known open bug, you are done triaging — link the backlog entry and its repro asset.
2. Get the logs. ls -t ~/.edmund/logs/ and read the day's file (edmund-YYYY-MM-DD.log). Grep for the three permanent breadcrumbs:

   grep -n "healing storage edit that bypassed didChangeText\|repairing content above origin\|recovered stranded desync on focus regain" ~/.edmund/logs/edmund-*.log
   

   Also grep for invariant: (the always-on storage==rawSource tripwire) and ⚠︎LEN-MISMATCH.
3. Find the first bad line and walk BACKWARDS. The user-visible symptom is often the second half of a two-part mechanism — the round-6 caret drift was armed by a silent bypass 80 seconds and dozens of healthy edits before the leap. Never start reading at the symptom timestamp.
4. Rule out a stale build if this follows a rebuild: grep strings .build/arm64-apple-macosx/debug/edmd for a long string literal unique to the new code (≤15-byte literals are inlined on arm64 and never appear); shasum the binary. See §3c.
5. Check git history for prior art. git log --oneline -- <suspect file> plus the investigation docs in docs/. The viewport-glitch investigation found four earlier fixes all working around the same unnamed root cause.
6. Reconstruct the document. Get the user's file or rebuild it from the trace's block counts/lengths. Wrapped-paragraph geometry and block kinds matter; do not repro against "hello world".
7. Before touching any running app: pgrep -lx edmd then ps -o lstart=,command= -p <pid>. The user's daily-driver app shares the binary name. Never blanket pkill -x edmd — kill only the PID you launched.
8. Row found in §2 → run its discriminating check. No row → escalate per §5, and add the new row here when it's understood.

2. The triage table

3. The traps that cost real time

Each of these burned hours to days. Read before shipping any fix.

(a) Shipping caret fixes on reasoning alone. Delete-drift rounds 1–5 each shipped a plausible, well-argued fix — and each came back. Only round 6, the first with a frozen deterministic live repro (bypassdelete script), named the actual mechanism (_fixSelectionAfterChangeInCharacterRange queued by a bypassed edit, firing at the next endEditing) — and its first fix attempt failed in the repro within a minute, which reasoning would never have caught. Lesson: time spent making the failure cheap to observe beats time spent reasoning about the fix. Freeze the repro before writing the fix.

(b) Undo/redo viewport drift. Two defects hid behind one symptom: restoreSnapshot ran a full recompose (discarding all TK2 layout, so the follow-up scroll measured freshly manufactured estimates) and performUndo recorded the redo snapshot with the caret at undo-invocation time, not at the edit. Lesson: a wrong-scroll symptom can be a geometry bug and a plain stale-state bug stacked; fix and verify them separately. The contract since 5bb2b40: diff the snapshot, apply via recomposeReplacing, select the changed text, let the changed range drive the viewport.

(c) Stale binaries produce false conclusions. In round 6, swift build twice printed Build complete! while linking a stale edmd — the compile ran, the relink silently didn't — and two "failed" fix iterations were phantoms. Detect: grep strings on the binary for a long literal unique to the new code. Cure: swift package clean (or rm -rf .build for release weirdness). Never hand-delete .build/…/edmd.build/ — that corrupts the output-file-map and wedges the target until a full clean.

(d) Headless-green ≠ fixed for input-layer bugs. The round-6 unit test reconstructs the exact document and gesture and passes with and without the fix: the test harness runs AppKit's deferred selection fixup synchronously, so the broken state never forms. A green test proves nothing about the live NSTextView / TextKit 2 / input-context class. The scripted live repro is the regression harness; the unit test is only a contract spec.

(e) open -a runs stale cached copies. LaunchServices can foreground an already-running instance instead of relaunching, and can execute a stale cached/translocated copy of the bundle — you debug last hour's code. Always launch by direct exec: build/Edmund.app/Contents/MacOS/edmd file.md & (after the §1 step-7 pgrep check).

(f) Trusting off-screen fragment y-coordinates. A TK2 fragment's frame is real only once laid out; everything off-screen, plus total document height, is an estimate. Any code that measures before ensuring layout of the viewport↔target span lands wrong (this is Bug 1a, the typewriter-scroll gotcha, and most historical viewport glitches). Ensure layout for the target range first, then align to real geometry — and never verify a visual fix from headless layout: measure from screencapture pixels.

4. Discriminating experiments — cheap checks that split hypothesis spaces

Verbose diagnostics launch (defaults keys are namespaced; the file must be argv[1]):

build/Edmund.app/Contents/MacOS/edmd FILE.md \
  -settings.general.diagnosticLogging YES \
  -settings.advanced.verboseEditorDiagnostics YES

Or toggle in Settings ▸ Advanced ("Save diagnostic logs" + "Verbose editor tracing"). Logs land in ~/.edmund/logs/edmund-YYYY-MM-DD.log.

Trace field vocabulary (source of truth: Sources/EdmundCore/TextView/EditorTextView+Diagnostics.swift, diagnosticState). Every trace line ends with:

Healthy vs suspect edit orderings:

• Healthy: shouldChangeText → selectionDidChange (up=N) → synced. A transient ⚠︎LEN-MISMATCH between those lines is normal (storage moves before rawSource syncs).
• Suspect: a selectionDidChange with up=Y at a surprising position; a persisting LEN-MISMATCH; a shouldChangeText with no synced/SKIPPED/DEFERRED line after it (bypassed didChangeText); the healing storage edit that bypassed didChangeText breadcrumb.

traceSelectionOrigin: under verbose tracing, any selection change arriving mid-recompose (up=Y) or with an unconsumed pendingEdit logs a condensed call stack naming the AppKit path that moved the caret. This is what named _fixSelectionAfterChangeInCharacterRange in round 6. If your bug moves the caret and you don't know who moved it, this answers it in one run.

Walk backwards from the first bad line, not forwards from the symptom. The round-6 drift was armed 80 seconds before the visible leap. Find the first line whose state is wrong, then read earlier.

verifyEditorInvariants (same file): the O(1) length check (storage.length != rawSource.length) logs an error whenever logging is on — no verbose toggle needed — so a hard-invariant break always leaves an invariant: line. The full structural checks (string equality, blocks reconstruct rawSource, block ranges in bounds) run under verbose tracing and assert in DEBUG. An invariant: error in a user's log is a model desync, full stop; triage as the delete-drift class.

If the existing logging didn't capture the deciding fact, add the log line first and reproduce again — one breadcrumb beats ten speculative fixes. Keep good ones behind Log.shouldTrace and ship them.

5. The escalation ladder (summary)

Full detail, ReproScript command reference, CGEvent driver, and soak-script method: edmund-live-repro-and-diagnostics and docs/dev-guides/live-repro-guide.md. Work down; stop at the first level that reproduces.

1. Plain unit test (makeEditor()) — model/parsing/styling logic.
2. Windowed unit test (NSWindow + NSScrollView, real deleteBackward) — adds layout, viewport, first-responder. Failure to repro here is evidence, not defeat: it points at deferred/queued AppKit state and at levels 3–4.
3. In-process ReproScript — DEBUG builds accept -debug.reproScript <path> (Sources/edmd/App/ReproScript.swift); replays a keystroke script through the real window.sendEvent path. No Accessibility/TCC needed, works with the window on an invisible Space. Commands: sleep, caret, type, backspace, bypassdelete, assertcaret, logsel. Launch with -ApplePersistenceIgnoreState YES and recreate the test document fresh each run. The default for live bugs.
4. CGEvent driver — only for paths that must originate as HID events (drag-select, drag-move, autoscroll). TCC decides per session; if input doesn't land after one test click, fall back to level 3 immediately.
5. Instrumented field occurrence — can't trigger it yourself: add the decisive breadcrumb, ask the user to enable verbose tracing, and wait. Days of latency; make sure the next occurrence is decisive.

After a fix: freeze the repro script, run a soak (several trigger cycles in one app run with assertcaret checks), then full swift test.

6. Open-bug inventory

Known open bugs — check here before "discovering" one. Sources: misc/backlog.md (authoritative list) and docs/ROADMAP.md (larger themes, e.g. "TextKit 2 viewport stabilization" is a v1.0.0 item — viewport estimate glitches are a known, partially-mitigated class). All entries below are OPEN as of 2026-07-05.

Do not relabel any of these as fixed without a verified repro flip; no oversell. When you fix one, update misc/backlog.md and this table in the same branch.

7. House rules while debugging

• Never blanket pkill -x edmd. The user's daily-driver app shares the binary name. pgrep -lx edmd + ps -o lstart=,command= -p <pid>, then kill only your own PID (pkill -f EdmundDbg if you launched the debug bundle).
• Do not request Computer Access — Screen Recording and Accessibility are already granted.
• Measure visuals from screencapture pixels (capture by window id, see ARCHITECTURE §8), never from headless layout alone.
• Never mutate storage while hasMarkedText() — including in any diagnostic or repro code you add.
• Never auto-push, PR, or merge. Branch off main per fix; commit small and often.
• Logs in ~/.edmund/logs are app-owned and fair game to read and quote.

Provenance and maintenance

Built 2026-07-05 from: docs/ARCHITECTURE.md (§2, §8, §9), docs/investigations/delete-drift-investigation.md (rounds 1–6), docs/investigations/viewport-glitch-investigation.md, docs/investigations/archives/callout-title-wrap-investigation.md, docs/dev-guides/live-repro-guide.md, misc/backlog.md, docs/ROADMAP.md, and Sources/EdmundCore/TextView/EditorTextView+Diagnostics.swift. Log strings (healing storage edit that bypassed didChangeText, repairing content above origin, recovered stranded desync on focus regain), launch-flag keys, fullLayoutMaxLength, ReproScript commands, the TK1 tripwire, and commit 5bb2b40 were verified against the source tree on that date.

Maintain it like the codebase docs: when a new bug class is understood, add its triage row; when a trap costs real time, add its story to §3; when a backlog bug opens or closes, sync §6 with misc/backlog.md in the same branch. If a row's discriminating check stops matching the code (renamed log string, moved file), fix the row — a stale runbook is worse than none. Deeper mechanism detail belongs in the sibling skills and docs/ investigation files, not here; this file stays a triage surface.

Edmund docs and writing

Date-stamped 2026-07-09. Every claim below was verified against the files on main at that date; re-verify paths before trusting this after major reorganizations.

When NOT to use this skill

This skill is for prose: what to write, where it lives, how it should read.

1. The docs-of-record map — one home per fact

Every fact has exactly one home; everywhere else gets a pointer. All paths exist and are current as of 2026-07-09.

Note: misc/backlog.md and docs/ROADMAP.md currently duplicate the v1.0.0/v1.x/v2.0.0 sections (backlog carries an extended copy). ROADMAP is the public plan; backlog is the working list. When they disagree, treat ROADMAP as the versioned commitment and backlog as scratch — and mention the drift to the maintainer rather than silently reconciling.

2. Where does a new fact go — decision table

Route the fact FIRST, then write. One home; cross-reference from elsewhere.

The same-PR rule is the load-bearing one. Doc updates that ride the code PR actually happen (see cf10741, b600e12, c4a602b in history); doc updates deferred to "later" don't.

3. House style

Derived from reading ARCHITECTURE.md and the investigation docs. Match it.

• Dense, specific, evidence-first. State the mechanism and the proof, not vibes. "Verified against that exact API" (§8 Sparkle bullet), timestamps and selection ranges quoted verbatim in investigation docs.
• Bold lead-ins for gotcha bullets, then the explanation: - **Stale release builds**: .... Scannable list, detail inline.
• Backticks for every file, symbol, flag, and command: `recomposeDirty`, `+EditFlow` (the extension-file shorthand), `-debug.reproScript`.
• One-line repro pointers, not embedded essays: "See misc/bug-repros/image-blank-after.mov", "grep ~/.edmund/logs for repairing content above origin".
• Honest status labels. The docs say "unconfirmed live", "theory + targeted repair, not a confirmed kill", "Verification limits (honest gaps)", "the test documents intent; the leap only reproduces under live layout". Never claim verification you didn't do. No oversell.
• Section anchors as cross-refs: "see §8", "ARCHITECTURE §13" — used across ARCHITECTURE, AGENTS.md, before-you-release.md. If you renumber sections, grep the repo for § and fix every reference.
• Address "you", the next agent/engineer: "will bite you", "Context for anyone who sees the bug again", "Next time it happens: ...".
• Record what failed, not just what worked — investigation docs keep the overturned theories and the phantom fixes (stale-binary trap) because the dead ends are the reusable knowledge.

Commit messages (from git log --oneline -50)

Mixed but patterned: conventional prefixes dominate for fixes and docs — fix(scope): ... (scopes seen: editor, layout, scroll, undo, release-workflow, changelog-to-html), docs: ..., occasional refactor:, appcast: add Edmund X.Y.Z, release X.Y.Z. Chores and README work often use plain imperative subjects ("Update README", "Add assets for README"). Branches: fix/<slug>, docs/<slug>, chore/<slug>. When in doubt: fix(scope): for behavior changes, docs: for doc-only commits, plain imperative for chores. Never auto-push, PR, or merge — only when asked.

4. CHANGELOG format — machine-read, get it exact

.github/workflows/release.yml extracts release notes with:

awk "BEGIN{p=0} /^## \[${VERSION}\]/{p=1;next} p && /^## \[/{exit} p{print}"

So the section header MUST be ## [x.y.z] at line start, version matching CFBundleShortVersionString exactly; the section ends at the next ## [. scripts/changelog-to-html.py converts the same section to HTML for Sparkle's update dialog (it folds wrapped bullet lines into their <li> — wrapping bullets is safe). Full pipeline: edmund-release-and-operate.

House format (verify against the file; current entries follow this):

## [0.1.4] — 2026-07-XX

### Fixed
- <User-facing symptom, past tense optional> ([docs](docs/<topic>-investigation.md)) [#NNN](https://github.com/I7T5/Edmund/issues/NNN)

---

• Em dash between version and ISO date; --- separator between versions.
• Subsections used so far: ### Added, ### Changed, ### Fixed (Keep a Changelog 1.1.0 vocabulary).
• Entries describe the user-visible effect, not the mechanism; mechanism lives in the linked investigation doc / ARCHITECTURE.
• An optional free-text line under the header is fine (0.1.2 has one) — the awk extraction includes it.

5. The investigation-doc template

Derived from docs/investigations/delete-drift-investigation.md (6 rounds) and docs/investigations/viewport-glitch-investigation.md. Both open with why the doc exists ("Context for anyone who sees the bug again... records the trail end to end") and name the fixing commits/branch up front. Chronicle structure: each recurrence is a new ## Round N appended to the same doc — symptom → diagnosis → root cause → fix → verification, with limits stated.

Skeleton (copy-paste):

# <Area> "<bug nickname>" — investigation notes

Context for anyone who sees this again. <One line on why it was hard:
intermittent / state-dependent / looked nothing like its cause.>

Fixed on branch `fix/<slug>`, commits: `<sha>` — <subject>, ...

## Symptom

<Exact user-visible behavior. Bulleted key properties, each a discriminating
fact ("caret-only, text fine"; "never right after launch"). Evidence
pointers: `misc/bug-repros/<file>`, `~/.edmund/logs/...`.>

## How it was diagnosed

1. <Numbered steps in the order they happened, including overturned
   theories and WHY each clue narrowed the space.>

## Root cause

<The mechanism, in bold where it matters. Explain why every symptom
property follows from it.>

## The fix

<What changed, in which file, and why that shape (defenses tried and
rejected count too).>

## Verification

<Tests added, live repro results, suite count. Then an honest limits
subsection: what was NOT reproduced/confirmed, and the breadcrumb to grep
for if it recurs.>

## If it ever recurs

<Ordered checks for the next investigator: which invariant/log/flag to
inspect first.>

## Round 2: <one-line summary>   ← append on recurrence, same structure

After writing one: add the one-bullet gotcha to ARCHITECTURE §8 with a pointer, add the CHANGELOG entry with a ([docs](docs/...)) link, and check the corresponding misc/backlog.md box (or move it under On-going bugs).

6. Maintenance duties

Do these whenever you touch the relevant doc; they rot otherwise.

• ARCHITECTURE placeholders: §9 and §10 end with italic "Add new ones here" / "track code-debt here" lines — keep them last in their lists so the invitation stays visible.
• ROADMAP Last updated: — bump the date on any edit.
• Backlog hygiene: check - [x] boxes when a fix ships (move to ## Done only if following the existing pattern — completed items live there); keep repro pointers valid; don't reorder the maintainer's priority sorting.
• README's inline HTML comments are the maintainer's own edit notes (e.g. <!-- Replace "minimal" with ... -->) — leave them unless acting on them.
• At release: CHANGELOG section header ↔ Info.plist version ↔ appcast <item> must agree; the checklist is misc/before-you-release.md, the mechanics edmund-release-and-operate.
• Section renumbering in ARCHITECTURE: grep the whole repo (docs, misc, AGENTS.md, skills) for § references before and after.
• Never edit test-files/todo.md — the maintainer owns it.

Provenance and maintenance

Written 2026-07-05 against main at fe8a1f5 (release 0.1.3). Sources, all read directly: docs/ARCHITECTURE.md (header, §8–§13), README.md, CHANGELOG.md, docs/ROADMAP.md, misc/backlog.md, docs/investigations/delete-drift-investigation.md, docs/investigations/viewport-glitch-investigation.md, docs/dev-guides/live-repro-guide.md (§1), misc/before-you-release.md, misc/how-to-release.md, root AGENTS.md, .github/workflows/release.yml (awk extraction quoted verbatim), git log --oneline -50 (commit-style tally), directory listings of docs/ (architecture/, investigations/ incl. archives/, dev-guides/), misc/, misc/bug-repros/, LICENSES/.

§1 map re-verified 2026-07-09 against the docs/ reorg (investigation docs split into docs/investigations/ + docs/investigations/archives/; docs/live-repro-guide.md moved to docs/dev-guides/).

Maintain this skill when: a doc of record moves or splits (update the §1 map), ARCHITECTURE sections are renumbered (fix every § reference here), the CHANGELOG extraction in release.yml changes (§4 quotes it), or a new investigation doc establishes a better template. Keep the one-home-per-fact rule itself stable — it is the point of the skill.

Edmund external positioning — what we claim, what we can prove

Governing rule: nothing may be claimed publicly that an outsider cannot reproduce from the repo + a release. Unproven = "candidate", never "novel" or "first". This skill exists to prevent overselling a beta.

When NOT to use this skill

1. The positioning (quote it exactly)

Source of truth: README.md. As of 2026-07-05:

• One-liner: "Edmund is a minimal, file-based, native Markdown editor for macOS with inline live preview."
  • README carries its own TODO comment on this line: "Replace 'minimal' with 'customizable' or 'lightweight' once more features are implemented" — do not do that replacement early; "minimal" is the honest word today.
• Goal statement: "Our goal is to be the CotEditor of Markdown editors, i.e. elegant, powerful, configurable, and native inside out."
• Beta warning: "⚠️ Edmund is currently in beta." — this must stay visible in the README and any landing page until v1.0.0 ships.
• Maintainer's blog post: https://i7t5.com/posts/2026-06-26-edmund/ ("more of the motivation and design philosophy"). Cite it; do not paraphrase or invent its content without fetching it.
• Ambition framing: product-first. "Beyond state of the art" means product excellence — the TextKit 2 techniques are means, not ends. Never lead public copy with internal mechanism names; lead with what the user gets.

The six claimed differentiators (README, verbatim, 2026-07-05)

README also has a TODO comment after the list: "Move 'Fast' and 'Extensible'? Add 'integrations' section to Native after implementation" — the list is known-provisional; keep quotes synced to the file when you edit copy.

2. Claims discipline

Before strengthening any claim publicly, the evidence in the middle column must be upgraded to the right column. Status as of 2026-07-05.

3. Novel vs. known — the honest inventory

When writing a craft blog post or comparison, keep this ledger straight. "Candidate" means blog-worthy pending proof; it is not "proven novel".

Known / prior art (never claim novelty here)

• Live-preview Markdown editing: Typora, Obsidian, MarkText, Nodes. MarkEdit is the stated reference for source mode (ROADMAP v2.0.0 "the MarkEdit experience").
• TextKit 2 viewport virtualization for Markdown: nodes-app/swift-markdown-engine (Apache 2.0, macOS 14+) solves the same problems — viewport virtualization, live styling, wiki links, reading column, LaTeX. Per ARCHITECTURE §14: consult it before inventing a new mechanism and as a technique source (drag-select autoscroll, overscroll). Its existence caps any "first TK2 live-preview engine" claim at zero.
• The README's own Alternatives section credits ~15 editors. Public copy that ignores them reads as either ignorant or dishonest.

Distinctive candidates (label as such; each needs proof before publishing)

Reproducibility standard for any technical post: a reader with the repo and the post must be able to reproduce every claim — frozen repro scripts, pinned document fixtures, named macOS versions, measured numbers with the command that produced them. If a claim can't meet that, cut it or mark it anecdotal.

4. Ecosystem and license hygiene

Verified against the repo, 2026-07-05:

• License: Apache 2.0 (LICENSE, README "License" section, and the 0.1.0 changelog entry all agree). Say "Apache 2.0", never "MIT".
• Lucide icons: vendored, ISC (LICENSES/lucide.txt, © 2026 Lucide Icons and Contributors; parts derived from Feather). Attribution duty: keep LICENSES/lucide.txt shipping and credit Lucide where icons are discussed.
• Why Lucide in both modes (SF Symbols constraint): ARCHITECTURE §6 — SF Symbols cannot ship in exported PDFs (license), so callout headers use Lucide in both Read (inline SVG, currentColor-tinted) and Edit (rasterized tinted NSImage overlay). App-chrome SF Symbols (toolbar/settings) are fine; Edit-mode task checkboxes still use SF Symbols on-screen only. Don't "simplify" copy or code in a way that breaks this split.
• Dependencies to credit: swift-markdown, SwiftMath, Sparkle (README "Dependencies"). Acknowledgements section additionally credits swift-markdown-engine/Nodes, Typora, theme sources, create-dmg, MarkEdit, and others — preserve it when restructuring the README.
• Not notarized (2026-07-05): ad-hoc signed; users hit Gatekeeper ("damaged app"). README's WARNING block gives the two workarounds (System Settings → Privacy & Security → Open Anyway; or xattr -dr com.apple.quarantine /Applications/Edmund.app, maybe sudo). Keep those instructions accurate in every venue that mentions installing. misc/marketing/MARKETING.md gates Show HN on fixing this (notarize, or make the workaround idiot-proof).
• GitHub issue templates exist: .github/ISSUE_TEMPLATE/bug_report.md, feature_request.md. Point users there, not at email.
• appcast.xml is a public artifact served raw from the repo (SUFeedURL points at the raw GitHub URL). Anything committed to it is user-visible in Sparkle's update dialog. Pipeline details: edmund-release-and-operate.

5. Release-notes and public-writing style

• Pipeline: CHANGELOG.md sections become both the GitHub release notes (awk-extracted) and Sparkle's update-dialog HTML (scripts/changelog-to-html.py → appcast <description>). A CHANGELOG entry IS public copy — write it that way. Mechanics: edmund-release-and-operate.
• Actual house style (read CHANGELOG.md 0.1.0–0.1.3 before writing): Keep-a-Changelog headers (### Added / Changed / Fixed); one line per item, sentence case, no trailing period enforced; links to issues ([#156]) and investigation docs (([docs](docs/investigations/delete-drift-investigation.md))); user-visible phrasing ("Redo now jumps to where changed text was instead of caret") not internal jargon; occasional first-person maintainer notes with personality ("trying to have Fable 5 fix all the big bugs while I still have it with me"); 0.1.0 used bold Feature — one-line descriptions. Match this voice: plain, specific, lightly informal, zero hype.
• Screenshots/videos: README embeds live in docs/assets/ (v0.1.0_*.png, installation.png, v0.1.0_video.mp4, AppIcon/). Raw/source marketing assets live in misc/marketing/: MARKETING.md (the plan), reddit-post.md, demo-slide-v0.1.key, demo-src-files/, demo videos (demo.mov, demo-video-v0.1-brown.mp4), _raw screenshot masters, social-preview_figma.png. New public screenshots: polished copy → docs/assets/, raw master → misc/marketing/, versioned filenames.

6. Marketing priority context (2026-07-05)

From misc/backlog.md "Now": "Priority: Marketing = Bugs >= UI/UX > Features" — marketing work is tied for top priority with bug fixes. Open marketing items: screenshots/files and a webpage (reference: kruszoneq.github.io/macUSB). Backlog embeds a star-history.com chart; misc/marketing/MARKETING.md names GitHub stars (~69 at writing) as the goal and metric, audience "developers who value craft", and holds Show HN in reserve until first-run friction and a landing page are fixed. Its "craft months" deep-dives are exactly the Section 3 candidates — which is why the proof bar there matters.

Provenance and maintenance

• Sources verified 2026-07-05 against: README.md, docs/ROADMAP.md (last updated 2026-07-03), misc/backlog.md, docs/ARCHITECTURE.md (§2, §6, §8, §13, §14), CHANGELOG.md (0.1.0–0.1.3), LICENSE, LICENSES/lucide.txt, .github/ISSUE_TEMPLATE/, misc/marketing/, Tests/EdmundTests/PerfHarnessTests.swift, Sources/EdmundCore/Export/{ReadRenderOptions,HTMLRenderer,DocumentHTML}.swift, Sources/EdmundCore/TextView/EditorTextView.swift.
• Volatile facts are date-stamped inline: version (0.1.3), beta status, notarization status, shipped-vs-roadmap feature split, star count, README wording. Re-verify each against the file before repeating it publicly.
• When README differentiators or the one-liner change, update the verbatim quotes in §1 and re-run the §2 evidence check.
• If a §3 candidate ships as a published post, move it out of "candidate" and link the post + its frozen repro.
• Cross-references: edmund-release-and-operate (release/appcast mechanics), edmund-docs-and-writing (internal doc style), edmund-research-frontier (novelty judgment for research direction), edmund-architecture-contract (the invariants quoted here).

Edmund failure archaeology

Chronicle of settled battles. Purpose: nobody re-fights one. Each entry gives symptom → root cause → evidence → status. Hashes are on main unless noted. Dates are commit dates. Status vocabulary: settled (root-caused, fix verified), mitigated-unconfirmed (fix shipped, never seen killing a live occurrence), open (in misc/backlog.md), reverted-pending-redo.

When NOT to use this skill

• Designing a change / asking "why is it built this way" → edmund-architecture-contract.
• Actively debugging a NEW symptom (method, not history) → edmund-debugging-playbook.
• Driving the live app to reproduce something → edmund-live-repro-and-diagnostics (and docs/dev-guides/live-repro-guide.md).
• TextKit 2 / AppKit API semantics → textkit2-appkit-reference.
• Cutting or fixing a release → edmund-release-and-operate (this file only records how 0.1.0 broke).
• Build environment, stale-link traps in depth → edmund-build-and-env.
• Deciding whether a change is safe to make at all → edmund-change-control.
• Test strategy / what the suite can and cannot catch → edmund-validation-and-qa.
• The ongoing caret-integrity program (forward-looking) → edmund-caret-integrity-campaign.
• Debug flags (-debug.reproScript, verbose tracing toggles) → edmund-config-and-flags.

1. The delete-drift saga (rounds 1–6) — issue #156

The hardest bug in the project's history: pressing Delete moved the caret to a different line instead of deleting. Six rounds, 2026-06-25 → 2026-07-04. Full trail: docs/investigations/delete-drift-investigation.md (read it before touching +EditFlow / +SelectionTracking / the heal). One symptom, FOUR distinct root causes stacked on top of each other — each fix was real, and each round's recurrence was a different mechanism underneath.

STATUS: settled through round 6 (shipped in 0.1.3, 2026-07-04). The class — live-only caret/selection desync — remains the project's hardest problem; new rounds are possible. Backlog still lists "Delete caret drift" under On-going bugs as a class to watch, not a known unfixed defect.

Round 1 — stranded IME marked text (2026-06-26, 386604b + docs ef3d87e)

• Symptom: once it started, EVERY delete drifted; never at launch; cleared by switching apps and back. Text stayed correct — caret-only desync.
• Root cause: every styling path bails on hasMarkedText() (correct during live IME composition). A stranded composition (hasMarkedText() stuck true, no live composition) made didChangeText bail forever → rawSource/blocks froze while storage kept mutating → all caret math ran against a stale model. Strander: the async active-block restyle in +SelectionTracking re-checked isUpdating but not hasMarkedText(), so it could run recomposeDirty over a live composition scheduled one turn earlier.
• Fix: (a) add the missing !hasMarkedText() guard to the async restyle; (b) becomeFirstResponder recovery hook — unmarkText() + resync when the invariant is broken on focus regain (made the user's accidental focus-switch cure deterministic).
• Why it came back: the guard closed one strander; other marked-text sources existed (round 2), and other desync mechanisms entirely (rounds 4–6).

Round 2 — marked text without "IME" (2026-06-27, a1f3219)

• Symptom: recurred with no CJK/accent/emoji input. Focus-switch still cured it.
• Root cause (by elimination, documented in the doc): still stranded marked text — from automatic text completion / inline predictions, which inject provisional marked text on plain typing.
• Fix: isAutomaticTextCompletionEnabled = false, inlinePredictionType = .no in commonInit, plus a permanent Log.info breadcrumb in the recovery hook.
• Why it came back: the next recurrence wasn't marked text at all.

Round 3 — no fix; built diagnostics instead (2026-06-28, 5dae387, 3aaeb04, PR #139)

• Symptom: recurred on a build with rounds 1–2. NO recovered stranded desync log line; a headless probe of the exact gesture showed the model was CORRECT. Only appeared after minutes of editing in one window.
• Conclusion: the model/parse layer is sound; the drift is a live NSTextView / TextKit 2 / input-context phenomenon invisible headless. Chasing it blind was declared the wrong move.
• Shipped: verbose editor tracing (Settings ▸ Advanced, Log.trace, category .edit, per-event live-state prefix) + an always-on O(1) invariant tripwire (verifyEditorInvariants, logs error on length mismatch). This instrumentation is what cracked rounds 4–6. Lesson: when a live-only bug resists reproduction, ship diagnostics, not guesses.

Round 4 — drag-move deletes with NO didChangeText (2026-07-02, 9f99795, PR #163)

• Symptom (from the round-3 trace): drifting deletes showed shouldChangeText → nothing → selectionDidChange mid-recompose with a stale caret. Origin event: a drag-select, then shouldChangeText OK repl="", then LEN-MISMATCH forever — didChangeText never fired.
• Root cause: AppKit's drag-move gesture, when the drop lands past the end of the document (or fumbles), performs the source deletion via shouldChangeText → replaceCharacters and never calls didChangeText. rawSource silently froze — and autosave wrote the stale bytes: this was a data-corruption bug, not just a caret bug.
• Fix: shouldChangeText schedules a next-run-loop bypass check (RunLoop.main.perform): a pendingEdit still unconsumed one pass later == didChangeText was bypassed → run the same sync it would have, log healing storage edit that bypassed didChangeText (release too). Exempt while isUpdating/isUndoRedoing/hasMarkedText() (IME legitimately defers).
• Why it came back: the heal restored the model but rounds 5–6 found the heal itself could move the caret.

Round 5 — the heal leaped the caret (stale selection) (2026-07-03, 422498f, docs c4a602b, merged 222dd86, PR #166)

• Symptom: heal fired, invariant restored, bytes correct — but the caret leaped to the END of the document at the heal moment.
• Root cause: when the bypassed deletion removes the selected text, AppKit also skips its usual selection fix, so at heal time the selection still spans deleted text (e.g. {951,37} in a 973-char doc). The heal's restyle makes AppKit re-resolve the invalid selection → clamps to document end.
• Fix: before syncing, the heal collapses an out-of-bounds selection to the edit point. (Headless NSTextView clamps this itself — the test documents intent; only live layout reproduces the leap.)
• Why it came back: this out-of-bounds clamp was a special case of the real mechanism, found in round 6.

Round 6 — TextKit 2's queued selection fixup: the drift mechanism itself (2026-07-04, 1b1420a, branch fix/wrapped-paragraph-caret-drift, merged 218d922, PR #169)

• Symptom: typing mid wrapped paragraph, one backspace leaped the caret +43 ("two viewport-lines down"); drift no longer continuous — one delete drifts, the next ones don't. Model fine; a heal had fired 80 seconds EARLIER.
• Root cause (named via a traceSelectionOrigin stack capture): a normal edit runs TextKit 2's _fixSelectionAfterChangeInCharacterRange synchronously inside its own transaction. A didChangeText-bypassing mutation skips that too, so the fixup stays queued and fires at the NEXT endEditing — the heal's attribute-only restyle — where it maps the stale selection against post-edit coordinates and drops the caret blocks away. Fires exactly once (state is then synchronized), explaining "drifts once, then fine". Round 5's clamp was the sub-case where the stale selection ran past the shrunk document end.
• Fix: the heal derives the correct caret from the pendingEdit hull and sets it both before AND after syncRawSourceFromDisplay(). The before-only version still leaped — the queued fixer moves even a freshly set, fully valid caret during the sync's endEditing. The post-sync re-assert is the load-bearing half; the pre-set keeps cursorRaw/active-block styling correct.
• The breakthrough repro (first deterministic one in six rounds): ReproScript.swift (DEBUG-only, -debug.reproScript <path>) replays keystrokes in-process through window.sendEvent(_:) — no TCC, works on an invisible Space. bypassdelete <needle> simulates the drag-move deletion exactly; one bypass beforehand → the next delete always drifts. Typing alone never drifts. See edmund-live-repro-and-diagnostics.

Do not retry (proven dead across the saga)

• Headless/unit tests for this class. The test harness runs TextKit 2's selection fixups synchronously, so the deferred-fixup state never forms. The round-6 unit test passes with and without the fix — it is a contract spec, not a regression guard. Only the ReproScript live repro discriminates. Do not "add a test to catch it" and call the class covered.
• CGEvent injection as the default live driver. Round 6's session dropped the events (per-session TCC), and the app's windows launch on an inactive Space. Use ReproScript first.
• DEBUG assertion in didChangeText's marked-text guard — rejected in round 1: the invariant is legitimately broken during composition; it false-fires on every IME keystroke.
• "No explicit selection repair needed" (round 4's claim) — wrong twice. Any new heal-like path must handle selection explicitly, before and after.
• swift build trusted after "Build complete!" — round 6 hit a stale-link relink failure TWICE; two "failed" fix iterations were phantoms running old code. Verify with strings on a LONG literal (≤15-byte literals inline on arm64 and never show), cure with swift package clean, never hand-delete edmd.build/. Details: edmund-build-and-env.

2. Undo/redo viewport drift — the costliest failure

STATUS: settled (2026-07-02, 5bb2b40, part of PR #164) — with one caveat: misc/backlog.md "Lurking (Unreproduceable)" carries a later note "Undo/Redo and Copy/Paste scrolling is failing again". No repro exists. Treat the mechanism below as settled and any new report as a NEW investigation that starts from this entry.

• Symptom: undo scrolled too far down; redo centered on wherever the caret sat before the undo; changed text never selected.
• Root cause (two defects, found by code read before any experiment):
  1. restoreSnapshot ran a full recompose — replacing the entire storage discards every TextKit 2 layout fragment, resetting ALL geometry to height estimates; the subsequent centering math measured estimates.
  2. performUndo recorded the redo snapshot with the caret at undo invocation time (stale), and redo centered on it.
• Fix: textDiff(old:new:) single contiguous changed span → range-bounded recomposeReplacing (layout outside the span stays real); the changed range — never a stored caret — is selected and drives the viewport (hold if visible, else center).
• Load-bearing contract: never full-recompose on undo/redo. Anyone "simplifying" restoreSnapshot back to recompose reintroduces the bug. Guarded by TextDiffTests, UndoRedoSelectionTests, UndoRedoViewportTests.
• Prior art that treated symptoms without naming the estimate problem: 9aaa11b (undo hold-or-center), 2778d6e/21cc284 (cursor-move lurch), 84123e4 (pin scroll above viewport), c49cd5c (lazy viewport-first styling). All sound, all workarounds; 5bb2b40 removed the manufactured estimates at the source.

3. Viewport glitches — TextKit 2 height estimates (PR #164, 2026-07-02)

Full trail: docs/investigations/viewport-glitch-investigation.md. Three reported symptoms, one root cause: every off-screen TextKit 2 frame is an estimate; code that discards layout, trusts off-screen y, or runs two scroll policies at once turns estimate churn into visible jumps. Community-documented (Krzyżanowski / STTextView, Apple forums) — even TextEdit exhibits it.

• Bug 1 (undo/redo): entry 2 above. STATUS: settled (same caveat).
• Bug 2 (editing at top pushes line 1 above the viewport, can't scroll up). Theory: TK2 assigns fragments negative y when estimates above the viewport correct downward; scroller clamps at 0. Mitigations 217da5f (documents ≤100k UTF-16 kept fully laid out via a deferred scheduleFullLayoutSettle — estimates never exist) and 8b4ecfe (repairContentAboveOrigin: first fragment minY < -0.5 → re-lay start→viewport-end inside preservingViewportAnchor; breadcrumb repairing content above origin). STATUS: mitigated-unconfirmed. The doc is explicit: Bug 2 was never reproduced live; the repair had not been confirmed against a live occurrence as of this writing (2026-07-05). If it recurs: grep ~/.edmund/logs for the breadcrumb — present means diagnosis confirmed but repair raced/undersized; absent means different cause (scroller-only estimate jumps, or textContainerOrigin).
• Bug 3 (viewport oscillates during a steady drag-select). Two scrollers fighting: drag autoscroll pulling down vs the scrollRangeToVisible override always revealing the selection top once the selection outgrew the viewport. Fix 340fcbc: reveal the nearest end. STATUS: settled by geometry/reasoning — a live drag was never synthesized (that session couldn't arm AppKit selection). Phase 1 of the same report ("can't select") was NOT a bug: a whole-doc selection was active, so the drag was AppKit's drag-move gesture — same family as delete-drift round 4.
• Do not retry: raising fullLayoutMaxLength without measuring ensureLayout cost (full layout on large docs is the process-killing path that motivated the lazy pipeline); running a full layout inside a caller's preservingViewportAnchor (poisons its before/after measurement — the tab-indent stability test caught a 366pt compensation; that's why the settle is deferred).
• Backlog keeps "Inaccurate viewport estimates and things related" under On-going bugs, plus a lurking "glitch when scrolling" — the estimate class is managed, not extinct. Roadmap v1.0.0 carries "TextKit 2 viewport stabilization".

4. Callout-title wrap / the image wedge (settled 2026-07-03, aa45563 + ae61644, PR #165)

Full trail: docs/investigations/archives/callout-title-wrap-investigation.md — including a 10-row matrix of dead ends.

• Symptom/goal: custom callout titles (> [!type] Title) should render as real wrapping text with the type icon; any attempt to draw the icon clipped the wrapped title to one line.
• Root cause: drawing any IMAGE on a multi-line layout fragment wedges that fragment to a single line — an unexplained TextKit 2 reentrancy quirk. Isolated exhaustively: fragment overlay, frame-relative draw, before/after super.draw, raw CGContext.draw, editor-level draw(_:), pre-rasterized bitmap, transparent subview, layer-backed subview, CALayer contents — ALL clip. Controls: no icon → wraps; positions computed but plain rect filled instead of the image → wraps. Reading layout is fine; drawing a shape is fine; drawing an image is not.
• Fix: the icon is a stroked CGPath — SVGPath parses the vendored Lucide geometry, FragmentOverlay gained a path form, DecoratedTextLayoutFragment strokes it in CG. Verified live: icon renders, long titles wrap and re-wrap on resize.
• Standing constraint: any future overlay that can share a line with wrapping text MUST use the path form, never the image form. Existing image overlays (math, bullets, default callout header) survive only because they sit on single-line fragments.
• Do not retry: any image-drawing mechanism from the matrix; bumping the deployment target to macOS 15 on the hope newer TextKit 2 fixed it (no evidence, drops Sonoma incl. the dev machine). The whole-header-as-image alternative is preserved on branch fix/callout-title-image (tip c7f5170, unmerged): it sidesteps the wedge but has two unsolved problems (~2× line height band above the title; a width-timing race).
• Still open nearby (backlog): callout icon baseline / crispness; the callout-at-end-of-file extra colored line (live-path rendering bug).

5. The 0.1.0 release failures (2026-06-26 → 2026-07-02)

Reference: ARCHITECTURE §13. Five separate failures shipping and updating the first releases. STATUS: all settled, with one time bomb (PAT expiry).

1. sign_update -s exits 1 for new keys (59565f5, 2026-06-27, PR #135). Sparkle deprecated -s <key>; for keys generated after that change it prints a warning and exits 1. Killed the first 0.1.0 release. Fix: key on stdin — echo "$SPARKLE_ED_PRIVATE_KEY" | sign_update --ed-key-file - <dmg>. Do not retry -s.
2. Bundle not sealed → EVERY update failed "improperly signed" (5e54b40, 2026-06-29, issue #158). Sparkle re-validates the Apple code signature at install (SUUpdateValidator → SecStaticCodeCheckValidity); the build signed only the main binary, never sealed the bundle, so a valid EdDSA signature didn't save it. Fix: codesign --deep the whole .app — and because SwiftMath's resource bundle must sit at the .app root (Bundle.module hardcodes Bundle.main.bundleURL) and codesign won't seal a bundle with root items, seal first, copy the SwiftMath bundle in AFTER sealing. The lone unsealed root item trips strict codesign --verify but not Sparkle's non-strict check (verified against that exact API). Do not "fix" the ordering or the failing strict verify.
3. Appcast push to protected main rejected, GH006 (e56a4dd, 2026-06-28, PR #140). GITHUB_TOKEN isn't admin; enforce_admins: false means an admin PAT bypasses the required check. Fix: fine-grained admin PAT in secret RELEASE_TOKEN, set on the checkout step (not the push URL — actions/checkout persists an extraheader credential that overrides inline-URL creds). RELEASE_TOKEN expires 2027-06-27; rotate before then or releases fail at the appcast push.
4. create-dmg quirks (098d8c0, 2026-06-26, documented in §8): it's the npm create-dmg (sindresorhus), not the Homebrew tool; Node ≥20; exit code 2 for unsigned images is success; space-in-filename normalization.
5. Release workflow YAML invalid (854f85d, 2026-07-02, merged 232e6c8, PR #162). Literal multi-line bash strings inside a run: | block had unindented lines — invalid in a YAML block scalar; the whole workflow file failed to parse. Fix: build the strings with printf \n escapes; also $(...) strips trailing newlines, so the separator newline lives in NEW_ITEM's format string, not DESC_BLOCK.

6. Reverts and abandoned directions

• Selection tint — ee173f7 (2026-06-26): reverted an experimental selection color back to accent-derived (accent @ 30% alpha). STATUS: settled. Don't re-hardcode a bespoke selection color.
• img.md-image { display:block } in the export/Read HTML theme — 75d2824 (2026-06-25): reverted; it did NOT fix the image blank-space and broke layout. The commit title itself records the verdict: image blank-space is a separate, STILL-OPEN bug (backlog: "Attached image padding… creates a large empty space below", misc/bug-repros/image-blank-after.mov). Do not retry display:block for it.
• Checkbox click-to-toggle + table borders — 9991413 (2026-06-03): pulled from a branch for separate passes. STATUS: partially redone. Table work landed later (edit-mode table alignment shipped, per backlog Done); Read-mode click-to-toggle checkbox is still in the v1.x backlog — reverted-pending-redo. The original attempt lives on stale branch feature/checkbox-toggle (merged history, d6227e3).
• TextKit 2 migration regressions — b3a4b29 (2026-06-12): the TK1→TK2 migration silently broke inline-math height, HR spacing, and scroll; fixed with RenderingRegressionTests as the guard. Lesson: TK2 migrations regress silently in geometry — extend that suite when touching layout.
• Stale branches that look abandoned but are MERGED (don't "rescue" them): feature/incremental-recompose (tip 1222f79, in main) and refactor/word-level-rendering (merged via PR #8, 7eb6a21 — word-level delimiter hiding became the shipped approach). The genuinely unmerged WIP branches are fix/callout-title-image (entry 4) and dozens of old merged topic branches never deleted.

7. Wrapped-paragraph caret drift (PR #169) — same battle as round 6

fix/wrapped-paragraph-caret-drift / merge 218d922 IS delete-drift round 6 (entry 1): the branch name comes from the reporting symptom (backspace mid wrapped paragraph), but the root cause was the queued TextKit 2 selection fixup armed by an earlier bypassed drag-move edit — the wrapped paragraph was incidental. STATUS: settled with 1b1420a. If a caret drift is reported "in a wrapped paragraph", do not assume wrapping is the mechanism; check for a preceding heal breadcrumb in ~/.edmund/logs first.

8. Smaller settled battles (one paragraph each; verified in git)

• Flaky math fit-width test — took TWO rounds (5421297 2026-06-06 branch fix/flaky-math-test, then 352bdc9 PR #65). First fix pinned the text container width (tracking off) — the flake persisted ~1 in 3 runs. Real cause: shared theme-defaults state pollution between tests; fixed with isolated defaults. Lesson: a flake "fix" that doesn't name the shared state isn't done.
• Emoji rendered as missing-glyph boxes (0f5ffba, 2026-06-06). EditorTextStorage.fixAttributes is a deliberate no-op (so .attachment on real characters survives) — which also disabled font substitution. Fix: perform substitution manually (Apple Color Emoji per composed-character sequence, ZWJ/skin-tone graphemes whole). Don't re-enable the framework fixAttributes; it strips the marker attachments.
• Nested list hanging indent (8d2088f, 2026-06-06, PR #64). swift-markdown's list-item delimiter excludes leading indentation; the visible spaces broke the hang. Fix: hide the leading whitespace in the inactive branch; indentation comes entirely from the paragraph style.
• Ordered-list deep nesting lost styling (b255903, 2026-06-06). swift-markdown parses ≥4-space indent as indented code; the rescue regex only matched [-*+]. Extended to \d{1,9}[.)]. Any new list-ish syntax must be added to the rescue parser too.
• Window size persistence — three commits to get right (538ff6e → d967bcf → 678c5d6, 2026-06-28, PR #144). Saving content-view size made windows grow taller on reopen (titlebar double-counted); final form stores the full window frame and restores via setFrame.
• Toolbar right-click interception — three failed view-level attempts (4eb604a, 6723280, then f8472ca, 2026-06-26). View .menu, rightMouseDown, and a gesture recognizer all lost to the toolbar's "Customize Toolbar…" menu. Working fix: DocumentWindow overrides NSWindow.sendEvent — the documented funnel ahead of the toolbar — and swallows secondary clicks on the view-mode button. Do not retry view-level interception for anything the titlebar/toolbar claims.
• Invisible CJK input (a3df387): IME-composed text was invisible until committed; fixed by keeping marked text visible. Related to (and predating) the round-1 marked-text rules.

9. Still OPEN — do not let this chronicle imply otherwise

Per misc/backlog.md (cross-checked 2026-07-05): footnotes don't render (edit or Read); math doesn't render in Read mode; math padding in edit mode; image blank-space below attached images (see the 75d2824 revert); callout-at-end-of-file extra colored line; max content width not applied to Read mode; tables don't wrap/shrink at small content sizes; table-cell content wraps out of the cell; "sometimes click to select / select+delete doesn't work" (unreproduced); lurking scroll glitch from off-viewport height changes; lurking indented-cursor-stuck report; lurking "undo/redo and copy/paste scrolling failing again" (see entry 2 caveat). Delete-caret-drift and viewport-estimate classes stay on the watch list even though every known mechanism is fixed.

Provenance and maintenance

• Written 2026-07-05 by mining: docs/investigations/delete-drift-investigation.md, docs/investigations/viewport-glitch-investigation.md, docs/investigations/archives/callout-title-wrap-investigation.md, docs/ARCHITECTURE.md §13, CHANGELOG.md, misc/backlog.md, docs/ROADMAP.md, and git log --all (every hash above verified with git show on that date).
• Code and git win over prose. If this file disagrees with a commit or the current source, trust the commit, then fix this file.
• Update triggers: a new delete-drift round (append to entry 1 — never a new doc); any live confirmation or refutation of repairContentAboveOrigin (flip entry 3 Bug 2 off mitigated-unconfirmed); RELEASE_TOKEN rotation (entry 5); any revert (entry 6); closing a backlog bug named in entry 9.
• Keep the status vocabulary exact; "mitigated-unconfirmed" is not "fixed". No oversell — this file's value is that its claims can be trusted blind.
• Sibling map lives in "When NOT to use" above; keep it in sync as the skill library grows.

Edmund live repro & diagnostics

A class of Edmund bugs lives in the live NSTextView / TextKit 2 / input-context layer (deferred selection fixups, IME composition, drag sessions, event-loop timing). Headless tests cannot form the broken state — the test harness runs AppKit's deferred machinery synchronously, so a green unit test proves nothing about this class. This skill is how you make such a bug cheap to observe, then deterministic. Primary source doc: docs/dev-guides/live-repro-guide.md.

Verified 2026-07-05.

0. Safety preamble (do this every time)

• Check for the user's live instance first. The user's daily-driver app has the same binary name (edmd). Run scripts/check-live-instance.sh. Never blanket pkill -x edmd — kill only your own PID, or use pkill -f EdmundDbg (only your debug bundle matches).
• Recreate the test document fresh before every run — autosave mutates it; run 2 against run 1's leftovers produces garbage offsets.
• Verify the binary is fresh before trusting a run (SwiftPM sometimes prints Build complete! without relinking edmd) — strings/shasum method in edmund-build-and-env.
• Do not request macOS Computer Access. Screen Recording + Accessibility are already granted for this project; ReproScript (§3) needs neither.

1. The escalation ladder

Work down; stop at the first level that reproduces. Each is more faithful and more expensive than the one above.

Two levels deserve emphasis:

• Level 2 failing to repro is evidence, not defeat — it tells you the bug needs deferred/queued AppKit state, pointing you at level 3–4.
• Level 3 exists because level 4 is unreliable — background/agent sessions often have no TCC grant and synthetic keyboard events get dropped silently. In-process injection needs no permission.

2. Step 0 — make the trace tell you the trigger

Never script blind. The recipe is usually already in ~/.edmund/logs, if verbose diagnostics were on. Launch flags (file arg must be argv[1]):

<app>/Contents/MacOS/edmd FILE.md \
  -settings.general.diagnosticLogging YES \
  -settings.advanced.verboseEditorDiagnostics YES

Trace-field decoder (each verbose line carries these; from EditorTextView+Diagnostics.swift):

• Healthy edit ordering: shouldChangeText → selectionDidChange (up=N) → synced. A transient ⚠︎LEN-MISMATCH between those lines is normal (storage moves before rawSource syncs).
• Suspect: a selectionDidChange with up=Y at a surprising position; a persisting LEN-MISMATCH; a shouldChangeText with no synced/SKIPPED/DEFERRED after it (a bypassed didChangeText); the healing storage edit that bypassed didChangeText breadcrumb.
• traceSelectionOrigin logs a call stack for any selection change that lands mid-recompose — this is what named _fixSelectionAfterChange in round 6.
• Walk BACKWARDS from the first bad line, not forwards from the symptom. The round-6 drift was armed ~80 seconds and dozens of healthy edits before the visible failure. The user-visible symptom is often the second half.

If the log didn't capture the deciding fact, add the log line first (keep good ones behind Log.shouldTrace and ship them) and reproduce again. Also reconstruct the document — wrapped-paragraph geometry, block boundaries, and block kinds all matter; repro against a lookalike, never "hello world".

scripts/grep-trace.sh [YYYY-MM-DD] surfaces the suspect patterns in one shot.

3. The in-process ReproScript driver (default for live bugs)

Sources/edmd/App/ReproScript.swift, DEBUG builds only. Replays a keystroke script against the front document by synthesizing NSEvents and pushing them through window.sendEvent(_:) — the full authentic key route (keyDown → interpretKeyEvents → insertText: / deleteBackward:). No Accessibility, no visible window required (works on an inactive Space), real run-loop pacing.

Launch: scripts/launch-debug.sh FILE.md SCRIPT.repro (assembles EdmundDbg.app, guards the user's instance, direct-execs with all flags). Or by hand:

build/EdmundDbg.app/Contents/MacOS/edmd "$DOC.md" \
  -settings.general.diagnosticLogging YES \
  -settings.advanced.verboseEditorDiagnostics YES \
  -debug.reproScript "$SCRIPT.repro" \
  -ApplePersistenceIgnoreState YES &

Command surface (one per line, # comments allowed):

Round-6 minimal repro (the worked example): the deciding output was logsel 321 (broken) → 290 (fixed), every run, window not even visible.

sleep 2000
bypassdelete Sizemore,
sleep 800
logsel            # broken: {321,…}; fixed: {290,…}
backspace 2
logsel

Design rules — keep them when extending:

• Address text by needle, never offset — offsets go stale the moment a script edits; needles survive (this is what makes soak scripts possible).
• Real events over direct method calls — insertText("") shortcuts skip deleteBackward's selection machinery, the exact place round 6 lived.
• Simulate AppKit-internal paths by exact call sequence — bypassdelete replicates shouldChangeText → replaceCharacters, no didChangeText verbatim, not an approximation. Pin any new internal path's real sequence from a traceSelectionOrigin stack first, then replay it.
• Asserts inside the app, results in the log — the harness (you, or a shell loop) only greps PASS/FAIL; the app is the oracle.
• New commands are ~10 lines each — extend ReproScript.swift, don't work around it.

Soak scripts (§6): chain several trigger cycles at different positions with ordinary editing between them, assertcaret after each predictable step, and compare final rawLen across runs (byte-identical = deterministic). A soak green across 4–5 cycles is far stronger than one clean repro — it catches bugs needing armed state (round 6's queued fixup).

bypassdelete Sizemore,
assertcaret Strang
backspace 2
type xy
bypassdelete widely
assertcaret used in various
logsel

4. CGEvent driver (mouse-only paths, TCC willing)

For paths that must originate as HID events — real drag-select, drag-move, autoscroll — keyboard replay can't cover them. A ~70-line ui.swift (compile with swiftc) posting CGEvents does: bounds <substr> (window lookup via CGWindowListCopyWindowInfo), click x y, dragselect, dragmove (mousedown + ~400 ms hold before moving, or AppKit never arms the text drag), key, type.

Caveats (all hit in practice):

• TCC decides per session. Background/agent sessions often can't post keyboard events (dropped silently) or use System Events. Test with **one click
  • log check**; if input doesn't land, fall back to §3 immediately — don't iterate on driver variations.
• App windows are on an inactive Space until activated (kCGWindowIsOnscreen == false); osascript -e 'tell application "<path>.app" to activate' (Apple Events, a separate TCC bucket) may work where System Events is denied.
• Re-activate before every interaction batch; focus is lost between shell calls.

5. Screencapture measurement

Visual judgments are measured, not eyeballed — when the task says "balance padding" or "align the icon", capture the window and measure pixels.

scripts/capture-window.sh <window-title-substring> out.png finds the window id (JXA → CGWindowListCopyWindowInfo) and runs screencapture -x -o -l<id>. Notes:

• Capture by window id, reliable even when not frontmost.
• Crop by the detected window bounds — the desktop wallpaper defeats screencapture's brightness-based auto-crop.
• Measure padding/alignment from the PNG (e.g. a short Python/PIL pixel scan for the first/last colored row of a callout box). Report the pixel numbers, not an impression.
• Window-server state can glitch (tiny windows, restoration) after many rapid launch/kill cycles: rm -rf ~/Library/"Saved Application State"/com.i7t5.edmund.savedState and relaunch.

6. The loop, end to end

1. Verbose trace from the occurrence → find the first bad line, walk backwards, form a trigger hypothesis (§2).
2. Reconstruct the document; script the hypothesized trigger (§3).
3. No repro? Hypothesis wrong or fidelity too low — move down the ladder (§1), or instrument and wait for the next hit.
4. Repro in hand? Freeze it (exact script + document), then let it falsify fix candidates — round 6's first "fix by reasoning" failed in the repro within a minute.
5. Fix verified → soak (§3) → full swift test → keep the script + new diagnostics → update the relevant docs/*-investigation.md.

Meta-lesson from six rounds: time spent making the failure cheap to observe beats time spent reasoning about the fix. Every round that shipped on reasoning alone came back; the round that shipped on a deterministic repro named the actual mechanism.

scripts/ (in this skill dir)

All four pass bash -n. The two "verify on first use" scripts depend on live system state (window server, build layout) that couldn't be exercised while authoring; read the header comment before first run.

When NOT to use this skill

• Deciding which mechanism a symptom implies → edmund-debugging-playbook.
• Running the full caret-integrity investigation → edmund-caret-integrity-campaign.
• Stale-binary detection / bundle internals → edmund-build-and-env.
• What counts as sufficient evidence to ship → edmund-validation-and-qa.
• The AppKit theory behind the fixup/marked-text mechanisms → textkit2-appkit-reference.

Provenance and maintenance

Verified 2026-07-05 against docs/dev-guides/live-repro-guide.md, Sources/edmd/App/ReproScript.swift, and Sources/EdmundCore/TextView/EditorTextView+Diagnostics.swift.

grep -oiE '"(sleep|caret|type|backspace|bypassdelete|assertcaret|logsel)"' Sources/edmd/App/ReproScript.swift | sort -u
grep -n 'debug.reproScript' Sources/edmd/App/ReproScript.swift
grep -rn 'traceSelectionOrigin\|LEN-MISMATCH\|shouldTrace' Sources/EdmundCore/TextView/EditorTextView+Diagnostics.swift Sources/EdmundCore/Diagnostics/Log.swift
grep -n 'healing storage edit' Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift

Re-verify the scripts against docs/dev-guides/live-repro-guide.md §4 if the debug-bundle assembly recipe changes.

Edmund — release & operate

Date-stamped 2026-07-05. Verified against .github/workflows/release.yml, scripts/release.sh, scripts/build-app.sh, scripts/changelog-to-html.py, appcast.xml, Info.plist, CHANGELOG.md, docs/ARCHITECTURE.md §8/§13, and the Settings/CrashReporter sources. Where a doc and a script disagree, the script is the truth; disagreements are flagged inline.

House rule: releases happen only when the maintainer explicitly asks. Never tag, push, create a release, or merge on your own initiative — see edmund-change-control. Everything in §1–§4 below is a runbook for when the maintainer says "cut a release", not a standing instruction.

When NOT to use this skill

1. Release flow — CI path (the normal one)

Ship via a tag; CI does the rest. In order:

1. Bump versions in Info.plist — both keys:
   • CFBundleShortVersionString — marketing version, e.g. 0.1.3
   • CFBundleVersion — build number, monotonic integer (0.1.3 = 4)
2. Add a ## [x.y.z] section to CHANGELOG.md — format is load-bearing, see §2. The version MUST match Info.plist exactly.
3. Merge to main and push (via the normal PR flow).
4. Tag and push the tag:

   git tag vX.Y.Z && git push origin vX.Y.Z
   

5. CI (.github/workflows/release.yml, trigger push: tags: 'v*', runner macos-14, job release / "Build & publish") runs the steps below.
6. Afterwards, verify per §4 post-flight.

release.yml step anatomy (actual step names)

Local path (scripts/release.sh)

Mirrors CI: build-app.sh → create-dmg (+ rename) → EdDSA sign → update appcast.xml locally → gh release create. Two differences:

• Signing: with SPARKLE_ED_PRIVATE_KEY in the env it uses the stdin path (CI-style); otherwise sign_update pulls the key from the login keychain (put there by Sparkle's generate_keys) with no flag at all.
• The appcast commit/push is left to you. The script ends with the exact commands: git add appcast.xml && git commit -m 'Release <v>' && git push.

Prereqs for the local path: gh auth status authenticated, npm create-dmg installed, swift build has run at least once (so sign_update exists under .build).

Stale doc: misc/how-to-release.md still says the artifact is a zip ("signs the zip", "Zip it to build/Edmund-1.0.zip"). That predates the DMG switch. The truth is DMG throughout — per release.yml, release.sh, and ARCHITECTURE §13. Trust the scripts, and fix that doc when touching it.

2. CHANGELOG format contract (release notes are machine-extracted)

Both release.yml and release.sh extract the GitHub Release body with:

awk "BEGIN{p=0} /^## \[${VERSION}\]/{p=1;next} p && /^## \[/{exit} p{print}" CHANGELOG.md

So the section header must start at column 0 as ## [x.y.z] — literally ## [0.1.3] — 2026-07-04 in house style (em dash + ISO date after the bracket is fine; the match only requires the ^## \[x.y.z\] prefix). Extraction runs until the next ^## [ line. If nothing matches, the release body falls back to "See CHANGELOG for details." — a silent-ish failure, so get the header right. (Version dots are unescaped in the regex; harmless in practice, don't rely on it.)

The Sparkle update-dialog notes come from the same section via scripts/changelog-to-html.py <version>, a deliberately tiny converter that only understands Keep-a-Changelog shapes:

• ### Added / ### Changed / ### Fixed → <h3> — use ###, not ##. The 0.1.2 appcast item literally shows <p>## Changed</p> because the section used ## subheads at release time; the converter passed them through as paragraphs.
• - / * bullets → <ul><li>; indented continuation lines fold into the previous bullet.
• `code` and **bold** are converted. Markdown links are NOT — [docs](docs/foo.md) appears literally in the update dialog (see the 0.1.2 item). Keep appcast-facing notes link-free or accept the raw brackets.
• Blank lines and --- are skipped; anything else becomes a <p>.
• Missing section → empty output → the <description> is simply omitted.

House format (verified from CHANGELOG.md): Keep a Changelog 1.1.0 + SemVer, newest first, sections separated by ---.

3. The sharp edges (each one killed or nearly killed a real release)

3.1 sign_update -s is FATAL — key goes on stdin

Sparkle deprecated -s <key>; for newly generated keys it prints a deprecation warning and exits 1 ("no longer supported"). This killed the first 0.1.0 release. The only correct invocation with a key-in-hand:

echo "$SPARKLE_ED_PRIVATE_KEY" | sign_update --ed-key-file - <dmg>

Both release.yml and release.sh do exactly this. Never "simplify" it back to -s. Output format: sparkle:edSignature="<sig>" length="<n>" — the scripts grep those two attributes out for the appcast item.

3.2 Bundle sealing (the "improperly signed" update failure)

At install time Sparkle re-validates the update's Apple code signature (SUUpdateValidator), independent of the EdDSA signature. A bundle that is code-signed but not sealed (no _CodeSignature/CodeResources) fails that check and every update dies with "The update is improperly signed and could not be validated" — which is exactly what broke the v0.1.0 → 0.1.1 update when the old script signed only the bare binary.

build-app.sh therefore signs inside-out and in a very deliberate order:

1. codesign --force --deep --sign - Sparkle.framework (nested XPC helpers must be signed before macOS will launch them),
2. codesign --force --deep --sign - --identifier "com.i7t5.edmd" on the whole .app while its root holds only Contents/ — codesign refuses to seal a bundle with extra items at the root,
3. copy the SwiftMath resource bundle to the .app root after sealing (its generated Bundle.module looks at Bundle.main.bundleURL; without it the app crashes on the first LaTeX render).

Consequence: codesign --verify (CLI) and --strict will complain about that one unsealed root item. That is expected and fine — Sparkle's actual check is non-strict (SecStaticCodeCheckValidityWithErrors with kSecCSCheckAllArchitectures) and tolerates it; verified end-to-end against that API. Do not "fix" the verify warning by moving the SwiftMath bundle or re-signing after the copy.

3.3 Keypair discipline

One EdDSA keypair, three places, all of which must agree:

If the signing key and SUPublicEDKey diverge, everything looks fine — the DMG signs without error — but every user's update fails signature verification. Sanity check when in doubt: sign_update --verify <dmg> <sig> against the Info.plist public key.

3.4 Appcast push to protected main — RELEASE_TOKEN

The workflow's last step commits appcast.xml and pushes to main, which requires the test status check. The default GITHUB_TOKEN / github-actions[bot] is not an admin, so that push is rejected with GH006 … protected branch hook declined. Branch protection has enforce_admins: false, so an admin's push bypasses the check — hence the fine-grained admin PAT in the RELEASE_TOKEN secret (Contents: read/write), set as the token: on the checkout step, not on the push. That placement matters: actions/checkout persists an http.<host>.extraheader credential that overrides inline-URL credentials, so rewriting the push URL would keep pushing with the bot token anyway.

RELEASE_TOKEN expires 2027-06-27. Rotate it before then or every release fails at the appcast push while the GitHub Release itself succeeds (a confusing half-shipped state — see §4 post-flight).

3.5 create-dmg quirks

• It's the npm package create-dmg (sindresorhus), installed via npm install --global create-dmg. Homebrew's create-dmg is a different tool with an incompatible CLI. Requires Node ≥ 20 (CI pins it).
• It exits 2 when it can't Developer-ID-sign/notarize the image (Edmund ships ad-hoc) but still produces the .dmg. Both scripts run it with || true and then verify the file exists, failing loudly only if no dmg was produced. Don't remove the || true; don't trust the exit code.
• Output is named "Edmund <version>.dmg" — with a space. Both scripts rename to Edmund-<version>.dmg (hyphen), which is the name the appcast enclosure URL expects. If a rename is skipped, the release asset URL 404s for every updater.

4. Pre-flight and post-flight

Pre-flight (distilled from misc/before-you-release.md — read it too)

• swift test green on main, not just the branch; git status clean.
• No debug flags / launch args left on (repro drivers, verbose tracing — see edmund-config-and-flags, ARCHITECTURE §8).
• Visual sanity: build and screencapture the editor in light and dark mode; click through everything the CHANGELOG claims ("fixed X" → actually reproduce X and confirm).
• CHANGELOG.md has ## [x.y.z] — YYYY-MM-DD for this release and the version matches Info.plist (CFBundleShortVersionString); ### subheads, not ## (§2).
• CFBundleVersion bumped (monotonic int).
• RELEASE_TOKEN not expired (2027-06-27).
• Local path only: gh auth status ok; keychain key matches SUPublicEDKey (§3.3).

Post-flight

• GitHub Release vX.Y.Z exists with the right notes and the Edmund-<v>.dmg asset (hyphenated name).
• appcast.xml on main got the new <item> — with <description>, correct sparkle:version (= CFBundleVersion) and enclosure URL.
• Nothing to do for user prompts: Sparkle checks roughly daily; existing users see the update within ~24 h. Don't panic if it isn't instant.

If the Release exists but the appcast commit is missing, the release half-shipped (usually §3.4). Fix the token, then add the <item> manually or re-run the job.

5. Gatekeeper story (why users see "damaged")

Edmund is ad-hoc signed, not notarized (no $99/yr Developer ID). First launch of a downloaded copy trips Gatekeeper with the "app is damaged" dialog. This is expected; the app is fine. The README documents both workarounds (verified, README ~line 53):

• xattr -dr com.apple.quarantine /Applications/Edmund.app, or
• right-click → Open.

Known upgrade path (open/candidate, not scheduled): Developer ID certificate

• notarization would remove the prompt entirely and also clean up the non-strict-sealing compromise in §3.2. Don't promise it in user-facing text.

6. Operating the app

Launching

open Edmund.app foregrounds a running instance instead of relaunching — you'll stare at old code. And never pkill -x edmd blindly: the maintainer's own Edmund session may be running (the Mach-O is edmd for both). Check first (pgrep -x edmd), kill only PIDs you started, or launch the binary directly: build/Edmund.app/Contents/MacOS/edmd file.md &. Full launch / stale-build / screencapture mechanics: edmund-build-and-env.

Logs — ~/.edmund/logs/edmund-YYYY-MM-DD.log

• One file per day, human-readable lines tagged LEVEL [category] (categories: app, document, io, render, compose, selection, lazy, callout, edit — grep by concern).
• Controlled by Settings ▸ Advanced ▸ Diagnostics ("Save diagnostic logs"). The toggle defaults OFF (AppSettings.diagnosticLogging defaults false) — i.e. opt-in in the shipped app, despite Log.swift's header comment calling it "always-on (opt-out)"; the code is the truth. (The UserDefaults keys are named settings.general.* for legacy reasons; the UI lives in Advanced.)
• Retention picker ("Clear logs after:") next to the toggle; a separate "Verbose editor tracing" opt-in gates keystroke-level trace lines — leave off except during repros (edmund-live-repro-and-diagnostics).
• Release builds write info and up; DEBUG builds also write debug.
• Logs may contain document text; they never leave the machine.

Crash reports — ~/Library/Logs/DiagnosticReports/edmd-*.ips

• macOS names crash reports after the Mach-O executable: look for edmd-<timestamp>.ips, not "Edmund-…".
• Uploading is opt-in and currently INERT. The Settings toggle is commented out in Sources/edmd/Settings/AdvancedSettingsView.swift ("dormant until the receiving server exists"), and CrashReporter.reportingEndpoint is a placeholder (https://REPLACE-ME.invalid/crash). Nothing is ever sent in shipped builds. Don't tell users crash reporting exists; don't uncomment the toggle without a real server. Code: Sources/EdmundCore/Diagnostics/CrashReporter.swift.
• Reading works only because Edmund is not sandboxed; adopting App Sandbox would force a MetricKit rewrite (noted in CrashReporter's header).
• Triage of a user's .ips: it's JSON — a one-line metadata header, then the report body. Look at exception (type/signal), faultingThread, and walk that thread's frames for images named edmd or Sparkle. Ad-hoc builds ship no dSYM, so expect addresses rather than symbol names for app frames; correlate with ~/.edmund/logs from the same timestamp instead. .ips files embed the user's home path and device model — treat as mildly personal data.

Update mechanics (user side)

• SUFeedURL = https://raw.githubusercontent.com/I7T5/Edmund/main/appcast.xml — the raw-GitHub URL of the checked-in appcast; committing to main is publishing.
• SUEnableAutomaticChecks is true; no custom interval is set, so Sparkle uses its default ~24 h cadence (plus a check on launch).
• Sparkle downloads the DMG enclosure, verifies EdDSA against SUPublicEDKey, mounts the DMG, re-validates the Apple code signature (§3.2), installs.

7. Versioning & appcast conventions

appcast.xml (checked into repo root): RSS 2.0 with the sparkle: namespace. One <channel> (title/link/description/language) containing one <item> per release. Items are inserted before </channel>, so the file reads oldest → newest; Sparkle doesn't care about order — it picks by version. Per item:

<item>
    <title>Edmund 0.1.2</title>
    <pubDate>Fri, 03 Jul 2026 19:03:59 +0000</pubDate>
    <description><![CDATA[ …HTML from changelog-to-html.py… ]]></description>
    <enclosure url="https://github.com/I7T5/Edmund/releases/download/v0.1.2/Edmund-0.1.2.dmg"
               sparkle:version="3"                <!-- CFBundleVersion -->
               sparkle:shortVersionString="0.1.2" <!-- marketing version -->
               sparkle:edSignature="…"
               length="7608991"
               type="application/x-apple-diskimage"/>
</item>

<description> is optional (omitted when the CHANGELOG section is missing).

8. Roadmap context (for release-content judgment)

• Edmund is in beta (0.1.x line, first public release 0.1.0 on 2026-06-27). Small, frequent releases.
• v0.2.0 goal: "Polished editing experience" (misc/backlog.md § Now).
• Priority ordering: Marketing = Bugs >= UI/UX > Features — when deciding what makes a release, bug fixes and polish beat new features.
• Long-range plan (v1.0 = onboarding + full GFM + extensions groundwork): docs/ROADMAP.md; working backlog with per-bug detail: misc/backlog.md.

Provenance and maintenance

Written 2026-07-05 from direct reads of: .github/workflows/release.yml, scripts/release.sh, scripts/build-app.sh, scripts/changelog-to-html.py, appcast.xml, CHANGELOG.md, Info.plist, README.md, docs/ARCHITECTURE.md (§8, §13), misc/how-to-release.md, misc/before-you-release.md, docs/ROADMAP.md, misc/backlog.md, Sources/EdmundCore/Diagnostics/CrashReporter.swift, Sources/EdmundCore/Diagnostics/Log.swift, Sources/edmd/Settings/AdvancedSettingsView.swift, Sources/edmd/Settings/AppSettings.swift.

Known stale docs at time of writing: misc/how-to-release.md (zip vs DMG, §1); Log.swift header ("always-on (opt-out)" vs the actual default-off toggle, §6). Minor oddity, deliberate: build-app.sh signs with --identifier "com.i7t5.edmd" while the bundle id is com.i7t5.edmund.

Re-verify when any of these change: release.yml step names or secrets, build-app.sh signing order, the CHANGELOG header format (the awk regex in two places must match it), SUFeedURL, RELEASE_TOKEN rotation (hard deadline 2027-06-27), notarization status, or the crash-report server going live (which un-inerts §6's crash uploading and this skill's wording).

Edmund research frontier

Where Edmund could go past the state of the art. Ambition is product-first: "the CotEditor of Markdown editors" (README). Advanced TextKit 2 techniques are means, not ends — a technique is worth pursuing when it makes the product better, and it becomes publishable as a side effect.

Everything here is candidate / open. Nothing is proven. Each item routes its proof through edmund-research-methodology (hypothesis predicts numbers) and its changes through edmund-change-control. Verified 2026-07-05 against the repo; assets cited are real, outcomes are not.

Frontier 1 — Viewport-stable TextKit 2 at scale (>100k UTF-16)

Why SOTA fails: TK2 lays out only near the viewport; off-screen fragment heights are estimates corrected as layout reaches them. This makes the scroller jump and scroll-to-target miss in every TK2 app, including TextEdit — a widely documented limitation. Above fullLayoutMaxLength (100k) Edmund enters this regime.

Edmund's asset: the mitigations already in TextView/ — scheduleFullLayoutSettle, preservingViewportAnchor, repairContentAboveOrigin, centerViewportOnCaret re-measure, and the diff-based undo restore that avoids resetting fragments to estimates; plus the ScrollStabilityTests / HeightStabilityTests harnesses. (Note: repairContentAboveOrigin is mitigated-unconfirmed live per docs/investigations/viewport-glitch-investigation.md — a real result here would also retire that honest gap.)

First three steps in this repo:

1. Build a large-doc fixture (makeLargeMarkdown in TestHelpers.swift) >100k and a scripted scroll-accuracy metric (ReproScript caret + a logsel-style position dump, or extend PerfHarnessTests).
2. Quantify the estimate-error distribution: for N scroll-to-target operations, record predicted vs actual landing pixel offset.
3. Prototype persistent per-fragment height caching across the settle (or across sessions) and re-measure the same distribution.

You have a result when: scroll-to-target lands within a stated pixel budget on a 1 MB document, measured by script, with zero repairing content above origin events across a scroll soak — reproducibly.

Frontier 2 — Caret integrity by construction

Why SOTA fails: every NSTextView consumer depends on didChangeText pairing that AppKit itself violates (the drag-move bypass). The delete-drift class is the symptom of building sync on a callback contract AppKit doesn't keep.

Edmund's asset: the heal machinery, the pendingEdit model, six documented rounds of mechanism knowledge, and the ReproScript + soak methodology. The campaign skill runs individual rounds reactively; this frontier is the structural endgame — eliminate the class.

First three steps:

1. Inventory every storage-mutation entry point (grep replaceCharacters, setAttributes, the edit-flow paths) and tabulate which currently rely on a callback firing.
2. Design a sync layer keyed on a storage-version counter that reconciles rawSource regardless of which callbacks fired (not a new guard per path).
3. Falsify it against all historical .repro scripts plus a new randomized bypass-fuzzer script.

You have a result when: all historical .repro scripts and a randomized bypass soak stay green with the callback-pairing assumption deleted from the code. Candidate, big — likely a multi-PR redesign; do not start without the methodology skill's evidence bar in front of you.

Frontier 3 — The 10 MB class (performance headroom)

Why it matters: README claims "~1–2 MB files"; native-with-no-Electron is the differentiator, so headroom is a product claim, not vanity.

Edmund's asset: viewport-based lazy styling, the idle drain, incremental reparse (pendingEdit window), PerfHarnessTests.

First three steps:

1. Extend PerfHarnessTests with 5/10 MB fixtures (makeLargeMarkdown).
2. Profile the block-parse and restyle hot paths (Log.measure single-line durations are already in place).
3. Set explicit latency budgets for open, first-paint, and per-keystroke restyle at 10 MB.

You have a result when: open + steady-state typing latency on a 10 MB file meets a stated budget, measured by the harness (not hand-timed).

Frontier 4 — A native extensions API

Why SOTA fails: Obsidian/VS Code plugin ecosystems are Electron; there is no strong precedent for a native, safe, fast extension surface for live-preview Markdown on macOS. ROADMAP v1.0.0 lists "Extensions API, documentations, primitive marketplace" and flags Advanced Syntax Highlighting / Advanced Math as "official extension" candidates.

Edmund's asset: the custom-parser seam (Parsing/SyntaxHighlighter+CustomParsers.swift), the BlockKind/styleBlock architecture, and already-modular opt-in syntax (math, Obsidian syntax).

First three steps:

1. Catalog which existing features could be re-implemented as extensions (dogfood: callouts? highlight? wikilinks?) — this defines the real extension points.
2. Define the minimal seam: block parser? inline parser? theme hook? Draw the line at what the custom-parser architecture already supports.
3. Spike one official extension behind a flag and measure restyle cost vs the built-in.

You have a result when: one built-in syntax feature runs as an extension with no measurable restyle regression against the built-in baseline.

Frontier 5 — Accessibility / RTL / localization as a differentiator

Why it matters: native apps can excel where Electron editors are weak; ROADMAP v1.x lists Localization, RTL, Accessibility. Locale-aware content width already ships as precedent that the pipeline can be locale-sensitive.

Edmund's asset: the attribute-only pipeline (structure is in the string, not in inserted characters), the existing locale-aware content-width path.

First three steps:

1. VoiceOver audit of EditorTextView's custom drawing — does the accessibility tree expose headings/lists/callouts, given they're drawn as decorations?
2. Test RTL behavior of the attribute-only styling on a right-to-left document.
3. Scriptable a11y check (structure read-out) as a regression guard.

You have a result when: a scripted VoiceOver audit reads document structure (headings, list items, callouts) correctly on a mixed document.

How to start one

1. Predict numbers first (edmund-research-methodology §2) — every milestone above is a number, not a vibe.
2. Instrument to make the current failure/limit cheap to measure.
3. Prototype behind a flag; measure predicted vs observed.
4. Route changes through edmund-change-control (branch, tests, no auto-push).
5. When the first milestone lands, the item graduates to misc/backlog.md or docs/ROADMAP.md and stops being a frontier.

What NOT to start (no current asset)

• iOS / iPadOS port — explicitly TBD in ROADMAP; no shared UI layer today.
• Collaborative / real-time editing — zero repo support (no CRDT, no sync, single NSDocument model). Would be a new product, not a frontier of this one.
• Anything that requires breaking an invariant (storage == rawSource; TextKit 2 only) to work — that's not a frontier, it's a rewrite (edmund-architecture-contract).

When NOT to use this skill

• Running an accepted investigation (a known bug) → edmund-caret-integrity-campaign / edmund-debugging-playbook.
• The method of turning a hunch into proof → edmund-research-methodology.
• Whether a public claim is allowed yet → edmund-external-positioning.
• Shipping the change → edmund-change-control.

Provenance and maintenance

Verified 2026-07-05. Assets exist; outcomes are unproven by definition — never quote a milestone here as achieved.

grep -n 'fullLayoutMaxLength' Sources/EdmundCore/TextView/EditorTextView.swift
grep -rn 'repairContentAboveOrigin\|preservingViewportAnchor' Sources/EdmundCore/TextView/
ls Sources/EdmundCore/Parsing/SyntaxHighlighter+CustomParsers.swift
grep -n 'Extensions API\|RTL\|Localization\|iPadOS' docs/ROADMAP.md
grep -rn 'func makeLargeMarkdown' Tests/EdmundTests/TestHelpers.swift

When an item's milestone lands, move it to ROADMAP/backlog and delete it here — a frontier list that keeps solved problems is lying.

Edmund validation & QA

The discipline of proof. The central lesson: a green headless test is necessary but not sufficient for the bug classes that cost the most time here. Know which evidence each change actually requires.

Framework: Swift Testing (import Testing, @Test, #expect, #require) — NOT XCTest. Verified 2026-07-05: 810 @Test cases across Tests/EdmundTests/.

1. The evidence hierarchy

Ordered weakest → strongest. The rule at the bottom names which class each change type requires.

The trap that defines this skill: the delete-drift round-6 regression test passes with AND without the fix — the harness runs the queued selection fixup synchronously, so headless can't see the bug. For caret/IME/drag/viewport-timing bugs, class (a) is not evidence of a fix; you need (c)+(d).

Required evidence by change type (gates enforced in edmund-change-control):

2. Test-suite anatomy

Run: swift test (full suite; ARCHITECTURE cites ~750+ tests ≈10s — 810 @Test cases as of 2026-07-05). One suite: swift test --filter <Suite>. swift test also runs automatically as a Stop hook (.Codex/settings.json) at the end of any turn touching code, so failures surface before you commit.

Map of Tests/EdmundTests/ (what the files actually cover):

• Parsing: BlockParserTests, SyntaxHighlighterTests, IncrementalParseFuzzTests, PendingEditTests, EscapeRenderingTests, HTMLTagRenderingTests, EmojiRenderingTests, LineEndingTests.
• Rendering / styling: BlockStylingTests, CalloutRenderingTests, CalloutTests, CommentRenderingTests, NestedBlockStylingTests, InlineStylingTests, MathRenderingTests, ImageRenderingTests, CodeHighlighterTests, FootnoteTests, WikiLinkTests, TableAlignmentTests, RenderingRegressionTests.
• Editor behavior: EditorIndentationTests, ListContinuationTests, BlockquoteContinuationTests, BlockquoteDeletionTests, FormattingTests, ActiveBulletMarkerTests, NewListItemAlignmentTests.
• Edit-pipeline integrity (the costly class): BypassedEditSyncTests, MarkedTextDesyncTests, WrappedParagraphCaretTests, EditorDiagnosticsTests, UnmatchedDebugTests, InternationalInputTests.
• Viewport / layout / undo: LazyRenderingTests, ScrollStabilityTests, HeightStabilityTests, TypewriterCenteringTests, UndoRedoViewportTests, EditorUndoTests, RecomposeTests, RecomposeEquivalenceTests.
• Export / read mode: HTMLRendererTests, DocumentHTMLTests, ReadModeWebViewTests, HTMLThemeTests, EditorThemeTests, ViewModeTests, ContentWidthTests.
• Infra / harness: LogTests, CrashReporterTests, PerfHarnessTests, StatusBarPrefsTests, FileIntegrationTests, EditorDocumentTests, TestHelpers.swift. _RenderDump.swift / _RenderEdit.swift are local dev tools (gitignored intent) that dump Read-mode HTML / edit output for tmp/sample.md — not part of the assertion suite.

Two invariant-guarding patterns worth copying:

• Recompose equivalence (RecomposeEquivalenceTests, helper assertMatchesFullRecomposeOracle): an incremental restyle must produce the same result as a full recompose. This is the safety net for the lazy / incremental styling paths.
• Incremental-parse fuzz (IncrementalParseFuzzTests): random edits must keep the parser's window-reparse consistent with a full reparse.

3. Test helpers (TestHelpers.swift)

@MainActor helpers you build on (verified exports):

styleBlock(_:cursorPosition:) is a method on EditorTextView (Rendering/EditorTextView+Rendering.swift), called from tests — it renders one block to an attributed string.

4. How to add a test

Skeleton (Swift Testing, @MainActor because the editor is main-thread):

import Testing
import AppKit
@testable import EdmundCore

@MainActor
@Test func deletingAtCalloutBottomKeepsInvariant() {
    let editor = makeEditor()
    editor.loadRawSource("> [!note]\n> body\n")
    drainAllStyling()
    // ... drive the edit ...
    #expect(editor.rawSource == editor.string)   // storage == rawSource invariant
}

Rules:

1. Every bug fix ships with a test even if it can't discriminate a live-only mechanism — it still locks the headless contract so a future refactor can't silently re-break the model half. For the live half, keep the frozen .repro script alongside (edmund-live-repro-and-diagnostics).
2. Assert the invariant where you can (rawSource == string), not just the surface symptom — that's what BypassedEditSyncTests / MarkedTextDesyncTests do.
3. Name the test for the behavior/bug, put edit-pipeline repros next to their siblings (the *Desync* / *Bypassed* / *CaretTests families).
4. New drawing behavior additionally needs a screencapture check (§6).

5. Golden / certified inventory

• RenderingRegressionTests + RecomposeEquivalenceTests are the closest thing to golden checks — they pin styled output and incremental-vs-full equivalence.
• test-files/*.md (callout.md, decorations.md, math.md, menu.md, test.md) are the user's manual test corpus — hand-testing fodder. Do not rewrite them to fit an automated test; build your own fixtures (helpers in §3, or a scratch dir).
• misc/bug-repros/ holds field evidence (.mov screen recordings + .log traces) for open bugs — reference these when reproducing, don't delete them.

6. Visual QA

Anything that draws is verified by screencapture pixel measurement, in light AND dark mode (per misc/before-you-release.md), never by eyeballing headless layout. Method + scripts: edmund-live-repro-and-diagnostics §5. Headless layout tests (HeightStabilityTests, ScrollStabilityTests) check geometry numbers but cannot confirm the pixels are right.

7. Flakiness & CI

• A fix/flaky-math-test branch exists in history — math rendering has shown timing flakiness; if a math test flakes, check that branch's approach before inventing a new one (verify: git log --oneline --all -- '*Math*').
• CI: .github/workflows/ci.yml on macos-14, latest-stable Xcode, SPM cache keyed on Package.resolved, concurrency: cancel-in-progress (private-repo macOS minutes bill 10×). CI runs the same swift test.

8. Performance evidence

• PerfHarnessTests measures the hot paths; makeLargeMarkdown builds big fixtures. Use it (don't hand-time) for any perf claim.
• The README claim "handles ~1–2MB files" and fullLayoutMaxLength = 100_000 UTF-16 (EditorTextView.swift:80) mark the boundary between the full-layout regime (≤100k, geometry is real) and the estimate regime (>100k, viewport glitches possible). A perf/viewport claim must state which regime it was measured in.

When NOT to use this skill

• The gate/branch/commit rules → edmund-change-control.
• Running the live repro or measuring pixels → edmund-live-repro-and-diagnostics.
• The caret-integrity investigation end to end → edmund-caret-integrity-campaign.
• Why a mechanism works → textkit2-appkit-reference / edmund-architecture-contract.
• Release verification → edmund-release-and-operate.

Provenance and maintenance

Verified 2026-07-05.

grep -rh '@Test' Tests/EdmundTests/*.swift | wc -l         # ~810 cases
grep -c 'import Testing' Tests/EdmundTests/TestHelpers.swift # confirms Swift Testing, not XCTest
grep -oE 'func [a-zA-Z]+' Tests/EdmundTests/TestHelpers.swift # helper inventory (§3)
ls Tests/EdmundTests/                                        # suite map (§2)
grep -n 'fullLayoutMaxLength' Sources/EdmundCore/TextView/EditorTextView.swift

If a helper in §3 no longer greps it was renamed; update §3 and any test skeletons. Re-derive the suite map from ls if files are added/removed.

TextKit 2 / AppKit reference (as it applies to Edmund)

The background a mid-level engineer or Sonnet-class model usually lacks. Each concept: brief theory, then where it bites in Edmund with a verified file pointer. This is not a textbook — it is only the parts that matter here.

Facts checked against source 2026-07-05. Items labeled (background) are general AppKit/TextKit behavior grounded in Apple's documentation, not directly grep-able in this repo.

1. The TextKit 2 object model (background + repo)

TextKit 2 replaced the TextKit 1 NSLayoutManager stack. The players:

• NSTextContentStorage — owns the backing string + attributes (the model).
• NSTextLayoutManager — lays text out (the TK2 analogue of the old layout manager).
• NSTextLayoutFragment — one laid-out chunk (≈ a paragraph); has a real geometric frame only once laid out.
• NSTextElement / NSTextParagraph — the model-side elements fragments render.

Viewport-based layout is the headline difference: TK2 lays out only the content near the visible viewport, not the whole document. That is what makes big documents fast — and it is the root of most viewport pain (§2).

Where it bites: Edmund subclasses the fragment as DecoratedTextLayoutFragment (EditorTextView+TextKit2.swift) to draw callout boxes, bars, and overlays.

2. Height ESTIMATES — the master cause of viewport glitches

A fragment that has not been laid out yet has an estimated height, not a real one; the total document height is the sum of real + estimated fragment heights. As layout reaches a fragment, its estimate is replaced by the true value and everything below shifts. Consequences: the scroller thumb jumps, and "scroll to offset Y" lands wrong because Y was computed from estimates. This is a widely documented TK2 limitation — even TextEdit shows it (background).

Where it bites / Edmund mitigations (verify names by grep; all in TextView/):

• fullLayoutMaxLength = 100_000 (EditorTextView.swift:80): documents ≤ 100k UTF-16 units are kept fully laid out (no estimate regime) by a coalesced next-run-loop settle.
• scheduleFullLayoutSettle / preservingViewportAnchor: the settle runs inside an anchor block so corrections never shift what is on screen.
• repairContentAboveOrigin (+LazyStyling.swift, logs repairing content above origin): fixes the case where an edit near the top strands the first fragment at negative y (unreachable above the scroller top).
• centerViewportOnCaret: re-measures after its first scroll and corrects the residual estimate error.

Rule: never trust an off-screen fragment's y-coordinate without laying out its span first. Deep write-up: docs/investigations/viewport-glitch-investigation.md.

3. The TextKit 1 fallback trap

An NSTextView can silently and permanently revert from TK2 to the legacy TK1 stack. Two known triggers: accessing NSTextView.layoutManager (the mere getter engages TK1), and storing NSTextBlock/NSTextTable attributes. Once reverted, TK2 APIs still exist but do nothing useful, and the whole editor misbehaves subtly.

Where it bites: Edmund ships a DEBUG tripwire — an observer on NSTextView.willSwitchToNSLayoutManagerNotification that asserts if the switch happens (EditorTextView.swift:273+, message "TextKit 1 fallback triggered"). Never add code that reads layoutManager or stores table attributes; draw tables as decorations instead (EditorTextView+TableRendering.swift).

4. Attribute-only mutation semantics

Edmund renders by writing attributes onto the storage, never by inserting or deleting characters (the storage == rawSource invariant). Two consequences from the text system:

• setAttributes does not re-measure geometry. After a restyle that changes a block's height or indent, you must call invalidateLayout(for:) on its range or the fragment keeps a stale frame (empty bands / clipped lines). recomposeDirty and the idle drain already do this; new paths must too.
• NSTextAttachment is only honored on the U+FFFC object-replacement character (background). rawSource never contains U+FFFC, so attachments can't be used — Edmund draws images/icons as overlays (§5) instead.

5. The custom drawing model (fragments, decorations, overlays)

DecoratedTextLayoutFragment draws two attribute families behind/over text:

• .blockDecoration (paragraph-level): callout boxes, quote bars, table borders, thematic-break rules, code backgrounds. Fragments tile vertically, so a multi-line run renders as one continuous box. A box's bottomPad grows the last fragment's frame (TK2 omits trailing paragraph spacing from the fragment, so padding done otherwise would be dead space).
• .fragmentOverlay (character-level): an image or a stroked vector path drawn at a glyph's laid-out position — rendered math, list bullets/checkboxes, callout header icon, the custom-title callout icon (path). The anchor glyph is hidden (≈0.01 pt font + clear color) and .kern reserves the drawing's advance width.

The image-on-wrapping-fragment wedge: drawing an image overlay on a multi-line (wrapping) fragment re-triggers a layout pass that collapses the fragment to one line. Drawing a shape/path does not. So the wrapping callout title's icon is a stroked CGPath (parsed by SVGPath from vendored Lucide geometry), never an image. Full saga: docs/investigations/archives/callout-title-wrap-investigation.md. This constraint holds for any new overlay that could share a line with wrapping text.

Hiding text = hiddenFont (≈0.01 pt) + clear foregroundColor. This is how delimiters (**, `, [!note]) vanish without changing the string.

6. The queued selection fixup (the round-6 delete-drift mechanism)

When you mutate an NSTextView's storage, AppKit queues a private step, -[NSTextLayoutManager _fixSelectionAfterChangeInCharacterRange:], that repairs the selection against the new character coordinates. Normally it fires promptly. But if an edit bypasses the normal close-out (see §7), the fixup stays queued and fires at the next endEditing — even an attribute-only restyle — where it maps the now-stale selection against post-edit coordinates and leaps the caret blocks away. It will move even a freshly set, valid caret.

Where it bites: this is delete-drift round 6. The heal must set the caret (from the pendingEdit hull) before the sync and re-assert it after (EditorTextView+EditFlow.swift). Recognize a variant by: a suspicious selection change arriving mid-recompose (up=Y in traces); traceSelectionOrigin will log the call stack of whoever moved it.

Critical for testing: a headless test harness runs this deferred fixup synchronously, so this bug class cannot reproduce in a unit test — the round-6 regression test passes with and without the fix. Only the live in-process repro discriminates (edmund-live-repro-and-diagnostics).

7. The AppKit edit pipeline contract (and where AppKit breaks it)

Normal edit: shouldChangeText(in:replacementString:) → the view calls replaceCharacters → didChangeText(). Edmund's didChangeText syncs rawSource from storage and restyles the edited block(s).

AppKit does NOT always send didChangeText. A drag-move of selected text whose drop lands on no valid target (e.g. released past the end of the document) deletes the dragged range via shouldChangeText → replaceCharacters and never calls didChangeText — silently freezing rawSource/blocks, after which every edit drifts and autosave writes stale content (delete-drift round 4). Edmund heals this: shouldChangeText schedules a next-run-loop bypass check (scheduleBypassedEditSyncCheck, +EditFlow.swift); an unconsumed storage pendingEdit by then means the close-out never came, and the editor runs the sync itself (breadcrumb: healing storage edit that bypassed didChangeText).

Never build a sync path on the assumption that didChangeText follows every edit.

The authentic key route (background + repo): keyDown → interpretKeyEvents → insertText: / deleteBackward:. This is why the repro driver synthesizes real NSEvents and pushes them through window.sendEvent(_:) rather than calling insertText directly — shortcuts skip deleteBackward's selection machinery, which is exactly where round 6 lived.

8. IME / marked text lifecycle

While an input method is composing (e.g. CJK, accents), the view holds provisional "marked" text in storage; hasMarkedText() is true. During this window storage == rawSource is transiently false, and didChangeText defers syncing until the composition commits.

The cascade: any styling path that runs beginEditing/setAttributes/invalidateLayout mid-composition can strand the marked text in the input context. After that, didChangeText keeps bailing on its own guard and the invariant stays broken — so every later edit drifts the caret (the original delete-drift bug). Therefore every storage-touching styling path must guard !hasMarkedText() — including async ones scheduled before composition began (the caret-move restyle in +SelectionTracking). becomeFirstResponder resyncs from storage as a catch-all. Full write-up: docs/investigations/delete-drift-investigation.md.

9. Responder chain & nil-target actions (background + repo)

The responder chain is AppKit's search order for who handles an action. Menu items and toolbar buttons with a nil target send their action up the chain until something responds. Edmund's Format menu (FormatMenu.swift) is a declarative command table whose items use nil targets and route to the focused EditorTextView's @objc format… actions — the same wiring as undo/redo. The first responder is normally the focused EditorTextView.

10. NSWindow.sendEvent — the pre-toolbar event funnel

Every event a window receives passes through sendEvent(_:) before the toolbar acts. This matters because with NSToolbar.allowsUserCustomization = true, the toolbar claims any secondary (right/control) click over the toolbar — including a custom item view — for its own "Customize Toolbar…" menu, downstream of view-level handlers (menu, rightMouseDown, gesture recognizers all lose). Edmund's fix for the view-mode button: intercept in DocumentWindow.sendEvent(_:), pop the menu when the click is inside the button's bounds, and swallow it (return); other clicks fall through to super. (Caveat: true fullscreen moves the toolbar to a separate window, so this main-window hook wouldn't cover it.)

11. Drag sessions (background + repo)

• Text drag-move arming: AppKit only starts a text drag after a mouse-down hold (~400 ms); a CGEvent driver must hold before moving or the drag never arms.
• Drag-select autoscroll: dragging past the viewport edge autoscrolls.
• Reveal at nearest end: a selection taller than the viewport must be revealed at its nearest end (Edmund's scrollRangeToVisible override) — always revealing the top fought the drag-select autoscroll and oscillated the viewport mid-drag.

12. swift-markdown walker model (brief)

Edmund parses with apple/swift-markdown (CommonMark/GFM) and walks the resulting Document with two back-ends: a SpanCollector-style walk that produces editor attributes, and HTMLRenderer that produces HTML for Read mode. One parser, two outputs — so Edit and Read can't drift. Custom (non-CommonMark) syntax — callouts, ==highlight==, wikilinks, comments, footnotes, math — is handled by SyntaxHighlighter+CustomParsers.swift.

When NOT to use this skill

• The project's rules/invariants (what you must not do) → edmund-architecture-contract.
• Which symptom means which mechanism → edmund-debugging-playbook.
• Reproducing a live bug / reading traces → edmund-live-repro-and-diagnostics.
• The history of how these mechanisms were discovered → edmund-failure-archaeology.
• Running the caret-integrity campaign → edmund-caret-integrity-campaign.

Provenance and maintenance

Verified 2026-07-05. Re-verify the load-bearing identifiers:

grep -n 'fullLayoutMaxLength' Sources/EdmundCore/TextView/EditorTextView.swift
grep -n 'willSwitchToNSLayoutManager' Sources/EdmundCore/TextView/EditorTextView.swift
grep -n 'scheduleBypassedEditSyncCheck\|healing storage edit' Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift
grep -rn 'repairContentAboveOrigin\|preservingViewportAnchor' Sources/EdmundCore/TextView/
grep -rn 'blockDecoration\|fragmentOverlay\|hiddenFont' Sources/EdmundCore/
grep -rn 'hasMarkedText' Sources/EdmundCore/TextView/

Items marked (background) are AppKit/TextKit behavioral facts documented by Apple and in docs/*-investigation.md, not directly observable by grep. If any Edmund mitigation name above no longer greps, it was renamed — update this file and docs/ARCHITECTURE.md §5/§8 together.

Edmund architecture contract

Edmund is a native macOS Markdown editor with live preview: AppKit + TextKit 2, SwiftPM, macOS 14+. Two targets (Package.swift):

Project ambition (maintainer, 2026-07-05): product-first — "the CotEditor of Markdown editors". Bias toward polish of the editing experience over feature count. The hardest live problem class to date is delete-drift (caret/selection integrity, 6 investigation rounds); the costliest failures were delete-drift and undo/redo viewport drift. Every rule below traces to one of those scars.

Ground truth this file distills: docs/ARCHITECTURE.md (repo root). Treat that doc as authoritative if the two ever disagree, and fix this skill.

Glossary (each term defined once)

• rawSource — the document's Markdown text, the single source of truth (EditorTextView.rawSource).
• storage — the NSTextStorage the text view displays (EditorTextStorage, Sources/EdmundCore/TextView/EditorTextStorage.swift).
• Block — one logical Markdown block (paragraph, heading, list run, code fence, table, quote/callout run). Model: Sources/EdmundCore/Model/Block.swift.
• Active block — the block under the caret; it renders its raw markdown (delimiters visible/editable) while all others render styled.
• Recompose — restyling storage from blocks (Sources/EdmundCore/TextView/EditorTextView+Composition.swift).
• Fragment — an NSTextLayoutFragment, TextKit 2's per-paragraph layout unit. Off-screen fragments have estimated heights until laid out.
• Overlay — an image or stroked path drawn at a character's laid-out position by the custom fragment class (see §4), replacing what NSTextAttachment would do in TextKit 1.
• Delete-drift — the bug class where rawSource/storage/selection desync and every later edit lands the caret in the wrong place. Chronicle: docs/investigations/delete-drift-investigation.md.
• IME composition — an input method's provisional "marked text" (hasMarkedText()), present in storage before the user commits it.

1. The two non-negotiable invariants

Break either and the editor misbehaves in subtle, delayed ways. Every design review starts here.

Invariant 1 — storage == rawSource (attribute-only rendering)

The displayed text storage is always character-identical to rawSource. Rendering only ever adds/changes attributes. Delimiters (**, `, [!note], …) are hidden, never stripped: hiddenFont (0.01pt system font, Sources/EdmundCore/Rendering/EditorTextView+Rendering.swift:55) plus a clear foregroundColor makes them invisible without touching the string.

Rationale. Identity mapping between display offsets and raw offsets means there is no offset-translation layer — caret math, selection, undo diffs, incremental reparse, and autosave all operate on one coordinate system.

Consequences you must respect:

The incident. The original delete-drift bug: an async restyle fired during IME composition, stranded the marked text, didChangeText kept bailing on its own guard, and the invariant stayed silently broken — caret drift on every subsequent edit. becomeFirstResponder now resyncs from storage as a catch-all. Full write-up: docs/investigations/delete-drift-investigation.md.

Invariant 2 — TextKit 2 only

Never touch NSTextView.layoutManager (the TextKit 1 NSLayoutManager accessor) and never store NSTextBlock/NSTextTable attributes. Either one silently and permanently reverts the view to TextKit 1 — no error, no log, just different (and wrong-for-us) layout from then on.

Rationale. All custom drawing rides NSTextLayoutFragment subclassing (§4), and viewport-based layout (only on-screen content laid out) is what makes large documents fast. Both are TextKit 2 facilities; a TK1 fallback kills them.

The tripwire. DEBUG builds observe NSTextView.willSwitchToNSLayoutManagerNotification and assertionFailure if the fallback ever triggers — textKit1FallbackTripwire(_:), Sources/EdmundCore/TextView/EditorTextView.swift:272-303. If you see that assertion, some code path you touched used a TK1 API or attribute. Find it; do not suppress the assert.

Corollary: Edit-mode tables cannot use NSTextTable. Alignment is done by distributing slack via .kern on hidden pipe glyphs — Sources/EdmundCore/Rendering/EditorTextView+TableRendering.swift.

2. Render pipeline

rawSource ──BlockParser──▶ [Block] ──styleBlock per block──▶ attributed runs in storage
                                        │
                                        └─ SyntaxHighlighter (swift-markdown walker
                                           + custom parsers: callouts, ==highlight==,
                                           wikilinks, comments, footnotes, math,
                                           backslash escapes, inline HTML tags)

Recompose entry points (pick the narrowest that works — a full recompose resets every fragment height to an estimate, see §6):

Lazy styling (Sources/EdmundCore/TextView/EditorTextView+LazyStyling.swift): a large dirty set styles only the viewport synchronously; the rest is finished by the idle drain (time-budgeted main-thread slices) and scroll promotion (style blocks as they enter the viewport).

Gotcha: attribute-only changes do not re-measure geometry in TextKit 2. If a restyle changed a block's height/indent, call invalidateLayout(for:) on its range or the fragment keeps a stale frame. recomposeDirty and the idle drain already do this; any new path must too.

3. Edit flow & undo

Normal edit: shouldChangeText (records a coalesced undo snapshot) → NSTextView mutates storage → didChangeText syncs rawSource and restyles the edited block(s) (Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift, +Composition.swift). Edits capture a pendingEdit on EditorTextStorage and reparse a window, not the whole document.

Undo/redo is custom (Sources/EdmundCore/TextView/EditorTextView+Undo.swift): stacks of rawSource snapshots, bypassing NSTextView's built-in undo. Restoring diffs the snapshot against current text (textDiff(old:new:), single contiguous span) and applies it with the range-bounded recomposeReplacing — never a full recompose, because a full recompose resets every fragment to a TextKit 2 height estimate and the follow-up scroll lands wrong (this was the undo/redo viewport-drift failure). The changed text drives the viewport: hold if any of it is on-screen, else center it.

AppKit does NOT pair every storage mutation with didChangeText. Proven incident (delete-drift round 4): a drag-move of selected text dropped on no valid target deletes the dragged range via shouldChangeText → replaceCharacters and never calls didChangeText — silently freezing rawSource/blocks; every later edit drifts the caret and autosave writes stale text. The heal: shouldChangeText schedules a next-run-loop bypass check (scheduleBypassedEditSyncCheck, +EditFlow.swift) — a pendingEdit still unconsumed by then means the closing didChangeText never came, and the editor runs the same sync itself. Breadcrumb in ~/.edmund/logs: healing storage edit that bypassed didChangeText. Never build a sync path on the assumption that didChangeText follows every edit.

Round 6 corollary: a bypassed edit also leaves TextKit 2's private selection fixup (_fixSelectionAfterChangeInCharacterRange:) queued; it fires at the next endEditing — even an attribute-only restyle — and leaps the caret blocks away, moving even a freshly set valid caret. The heal sets the caret before the sync and re-asserts it after (+EditFlow.swift). This class does not reproduce headless; see the routing in §8.

4. TextKit 2 drawing model

All custom visuals are drawn by DecoratedTextLayoutFragment (custom NSTextLayoutFragment, Sources/EdmundCore/TextView/EditorTextView+TextKit2.swift:160), vended via the layout-manager delegate. Two custom attribute keys (same file, lines 28/32):

The image-wedge constraint (open, not solved). Drawing an image overlay on a multi-line (wrapping) fragment re-triggers a layout pass that wedges the fragment to one line. Drawing a shape (stroked CGPath) does not. That is why the wrapping callout custom-title icon is a stroked path parsed from vendored Lucide geometry, never an image. Any new overlay that could share a line with wrapping text must be a shape, not an image. Full saga: docs/investigations/archives/callout-title-wrap-investigation.md.

5. Read mode contract

Read mode is a separate WKWebView, not an editor styling mode (Sources/EdmundCore/Export/). The contract: one parser, two back-ends — the same swift-markdown Document the editor parses is walked by SyntaxHighlighter.SpanCollector (→ editor attributes) and by HTMLRenderer (→ HTML), themed from the same EditorTheme via HTMLTheme, so the two renderings cannot drift. When adding a feature, implement it in both back-ends or document the divergence.

Hard properties of the web view (keep them):

• JavaScript disabled; every asset inlined (math as high-DPI PNG data URIs — SwiftMath has no SVG path; icons as inline Lucide SVG) so it needs no file/network reach. Remote images off by default (Sources/EdmundCore/Export/ReadRenderOptions.swift).
• Private URL schemes route navigation without JS: x-edmund-wiki: / x-edmund-link: (Sources/EdmundCore/Export/HTMLRenderer.swift:26,31).
• Inline HTML: only the whitelist SyntaxHighlighter.htmlFormatTags (u/kbd/mark/sub/sup, Sources/EdmundCore/Parsing/SyntaxHighlighter.swift:22) renders in either mode; everything else stays escaped/color-only. A real <br> break would need to mutate storage — forbidden by Invariant 1.
• Export/Print run the same HTML through WKWebView.printOperation (Sources/EdmundCore/Export/MarkdownPrinter.swift) for vector text.

6. Known weak points (open as of 2026-07-05)

State these plainly when designing near them; none is solved.

1. TextKit 2 height estimates are the root of most viewport glitches: an off-screen fragment's frame (and the total document height) is an estimate until layout reaches it — scroller jumps, scroll-to-target lands wrong (a documented TK2 limitation; TextEdit shows it too). Mitigations in place, not cures: documents ≤ fullLayoutMaxLength (100k UTF-16, Sources/EdmundCore/TextView/EditorTextView.swift:80) are kept fully laid out by scheduleFullLayoutSettle() wrapped in preservingViewportAnchor (+LazyStyling.swift:121, +TypewriterScroll.swift:22); repairContentAboveOrigin() (+LazyStyling.swift:151) fixes content stranded above y=0; centerViewportOnCaret re-measures after its first scroll. Never trust an off-screen fragment's y-coordinate without laying out the span first.
2. The image-wedge constraint (§4) applies to every new overlay.
3. Open bugs (misc/backlog.md): callout at end-of-file renders an extra un-prefixed line in the callout color (live incremental-restyle path, not static rendering); footnotes don't render in either mode; attached images create blank space below; math doesn't render in read mode (and has wrong padding in edit mode); delete caret drift and viewport-estimate glitches remain on the ongoing list.
4. Crash reporter endpoint is a placeholder: CrashReporter.reportingEndpoint is https://REPLACE-ME.invalid/crash (Sources/EdmundCore/Diagnostics/CrashReporter.swift:27) and the Settings ▸ Advanced toggle is commented out (Sources/edmd/Settings/AdvancedSettingsView.swift). Do not treat crash uploading as live.

7. Before you design something new — checklist

Run this before proposing any new mechanism, subsystem, or refactor:

• Invariant 1: does it insert/strip characters, use NSTextAttachment, or mutate storage outside the shouldChangeText→didChangeText path (or during IME composition)? If yes, redesign as attributes/overlays.
• Invariant 2: does it touch NSTextView.layoutManager or store NSTextBlock/NSTextTable? If yes, stop.
• Sync assumptions: does it assume didChangeText follows every mutation, or that a set caret stays put across the next endEditing? Both assumptions are proven false (§3).
• Geometry: does it read an off-screen fragment frame, or restyle without invalidateLayout(for:) when height changed? (§2, §6.)
• Both back-ends: does a rendering feature cover Edit and Read (§5)?
• Prior art: check ARCHITECTURE.md §14 — especially nodes-app/swift-markdown-engine, an independent AppKit+TextKit 2 live-preview engine solving the same problems — before inventing a new mechanism for an editing-experience problem.
• Weak points (§6): does the design lean on anything listed there? Label it as such; unproven mitigations are "open/candidate", never "fixed".
• Verification plan: unit test if headless can repro; otherwise plan a live repro (ReproScript) — do not ship a caret/IME/viewport fix on reasoning alone. Visual claims are measured from screencapture pixels, not eyeballed.

Process rules live in sibling skills, but never contradict them here: branch per fix off main; never auto-push/PR/merge; swift test green + visual verification before commit; never blanket pkill -x edmd (the maintainer's daily-driver app shares the binary name — pgrep and kill only your own PID); never request macOS Computer Access permissions.

When NOT to use this skill

Provenance and maintenance

Facts verified against the repo on 2026-07-05. If a grep below stops matching, the fact drifted — update this file and cite the new location.

# Invariant 2 tripwire still present
grep -n "textKit1FallbackTripwire" Sources/EdmundCore/TextView/EditorTextView.swift
# Recompose entry points
grep -n "func recompose" Sources/EdmundCore/TextView/EditorTextView+Composition.swift
# Bypass heal
grep -n "scheduleBypassedEditSyncCheck" Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift
# Custom draw attributes + fragment class
grep -n "blockDecoration\|fragmentOverlay\|class DecoratedTextLayoutFragment" Sources/EdmundCore/TextView/EditorTextView+TextKit2.swift
# hiddenFont hiding trick
grep -n "hiddenFont" Sources/EdmundCore/Rendering/EditorTextView+Rendering.swift
# Viewport mitigations
grep -n "fullLayoutMaxLength" Sources/EdmundCore/TextView/EditorTextView.swift
grep -n "scheduleFullLayoutSettle\|repairContentAboveOrigin" Sources/EdmundCore/TextView/EditorTextView+LazyStyling.swift
# Read-mode schemes + HTML whitelist
grep -n "wikiScheme\|linkScheme" Sources/EdmundCore/Export/HTMLRenderer.swift
grep -n "htmlFormatTags" Sources/EdmundCore/Parsing/SyntaxHighlighter.swift
# Crash-reporter placeholder (delete §6.4 once this is a real URL)
grep -n "REPLACE-ME.invalid" Sources/EdmundCore/Diagnostics/CrashReporter.swift
# Open-bug list
sed -n '/^Bugs/,/^UI\/UX/p' misc/backlog.md

Edmund — build & environment runbook

All paths relative to the repo root. Facts date-stamped 2026-07-05 are volatile — re-verify per the last section.

When NOT to use this skill

1. Environment from scratch

Requirements (verified 2026-07-05):

create-dmg trap: install via npm, NOT Homebrew. brew install create-dmg is a different tool with an incompatible CLI. Not needed for dev work — only for cutting releases (see edmund-release-and-operate).

Dependencies are fetched by SPM on first build — nothing to install by hand (verified against Package.swift / Package.resolved, 2026-07-05):

• swift-markdown ≥0.5.0 (CommonMark/GFM parsing; pulls swift-cmark transitively)
• SwiftMath ≥1.7.0 (LaTeX rendering — its resource bundle is a launch-crash landmine, §3)
• Sparkle ≥2.6.0 (auto-update — its framework is a dyld-abort landmine, §4)

Two SPM targets: EdmundCore (library + all tests; most work happens here) and edmd (the app shell executable). The binary is named edmd even though the app presents as "Edmund" — deliberate, see the comment in Package.swift.

2. Core commands

swift build                    # debug build of both targets
swift test                     # full suite: ~750+ tests, ~10s (2026-07-05)
swift test --filter Callout    # one suite
./scripts/build-app.sh         # release build → build/Edmund.app

swift test also runs automatically as a Stop hook after code-touching turns.

3. What build-app.sh actually does (and why the order matters)

scripts/build-app.sh → build/Edmund.app. Steps, in order:

1. swift build -c release
2. Assemble build/Edmund.app/Contents/{MacOS,Resources}; copy .build/release/edmd, Info.plist, Resources/AppIcon.icns.
3. Compile Resources/Assets.xcassets with actool (falls back to /Applications/Xcode.app/.../actool if xcode-select points at the CLT).
4. Embed Sparkle.framework into Contents/Frameworks/ (found under .build/; SwiftPM links Sparkle but never copies the framework — without it the updater crashes on first check) and install_name_tool -add_rpath "@executable_path/../Frameworks" so @rpath resolves post-install.
5. Codesign inside-out: Sparkle.framework first (nested XPC helpers must be signed before macOS will launch them), then the whole .app (ad-hoc, --deep, identifier com.i7t5.edmd). Sealing the bundle — not just the binary — is what Sparkle's update validator requires.
6. Only after sealing: copy .build/release/*.bundle (SwiftMath's math fonts) into the .app root.

Why step 6 is last and at the root — two constraints collide:

• codesign refuses to seal a bundle with any extra item at the .app root ("unsealed contents present in the bundle root"), so the seal must happen while the root holds only Contents/.
• SwiftMath's generated Bundle.module accessor hardcodes Bundle.main.bundleURL — the .app root — with only a hardcoded absolute .build path as fallback. So the bundle must sit at the root.

Resolution: seal first, copy after. The one unsealed root item makes codesign --verify and --strict complain, but Sparkle's actual check is non-strict and tolerates it (verified end-to-end; details in docs/ARCHITECTURE.md §8).

Missing SwiftMath bundle = instant crash the moment the app renders any LaTeX. App launches fine, opens documents fine, dies on the first math block. If you see that crash, check ls build/Edmund.app/*.bundle first.

4. Debug bundle fast path (EdmundDbg.app)

For live runs of a debug build, skip build-app.sh and hand-assemble (from docs/dev-guides/live-repro-guide.md §4):

swift build
mkdir -p build/EdmundDbg.app/Contents/MacOS
cp Info.plist build/EdmundDbg.app/Contents/
cp .build/arm64-apple-macosx/debug/edmd build/EdmundDbg.app/Contents/MacOS/
cp -R .build/arm64-apple-macosx/debug/Sparkle.framework build/EdmundDbg.app/Contents/MacOS/

• Sparkle.framework must sit next to the binary — dyld aborts without it.
• A bare .build/debug/edmd runs but never creates a window. It needs the bundle (Info.plist) around it.
• Launch by direct exec of the bundle binary, never open -a:

build/EdmundDbg.app/Contents/MacOS/edmd /path/to/test.md \
  -ApplePersistenceIgnoreState YES &

LaunchServices (open -a) can silently run a stale cached/translocated copy — you'd be executing last hour's code. Direct exec runs exactly the binary you just copied. -ApplePersistenceIgnoreState YES stops state restoration from reopening previous (possibly mutated) documents.

• Recreate the test document fresh before every run — autosave mutates it.

5. THE STALE BUILD DISEASE

The single most expensive trap in this repo: it has produced entire wrong debugging conclusions ("my fix doesn't work" when the fix was never in the binary).

Symptom: swift build prints Build complete! having compiled a changed file but not relinked edmd. The app then runs old code. Release builds (swift build -c release / build-app.sh) reuse stale objects too.

Detection — before trusting ANY binary you just built:

# 1. Grep for a LONG string literal unique to your new code:
strings .build/arm64-apple-macosx/debug/edmd | grep 'your long unique literal'
# 2. Hash before/after the build:
shasum .build/arm64-apple-macosx/debug/edmd

Literal length matters: string literals ≤15 bytes are stored inline in the Mach-O on arm64 and never appear in strings output. A short probe literal gives a false "stale" verdict. Use a long one (a distinctive log message works well).

Cure:

swift package clean          # first resort
rm -rf .build                # visual change "doesn't take" → nuke it all

Never hand-delete .build/…/edmd.build/ — that corrupts SwiftPM's output-file-map and wedges the target until a full clean anyway.

6. Running for visual checks — launch/kill hygiene

The user's daily-driver app has the same binary name (edmd). A blanket pkill -x edmd kills their live session. Always, in order:

# 1. Who is running, and since when?
pgrep -lx edmd
ps -o lstart=,command= -p <pid>
# 2. Kill ONLY your own PID — or, if you launched the debug bundle:
pkill -f EdmundDbg

Other run gotchas:

• open Edmund.app foregrounds a running instance instead of relaunching — you'll be looking at the old binary. Kill your instance first or direct-exec the binary.
• Always pass -ApplePersistenceIgnoreState YES (see §4).
• After many rapid launch/kill cycles the window server can glitch (tiny windows, broken state restoration): rm -rf ~/Library/"Saved Application State"/com.i7t5.edmund.savedState and relaunch.
• Verification method (window-id screencapture, offscreen render fallback): edmund-validation-and-qa and docs/ARCHITECTURE.md §8.

7. CI environment

.github/workflows/ci.yml (verified 2026-07-05): runs swift test on macos-14 with latest-stable Xcode (Swift 6.0 needs Xcode 16+), triggered on PRs and pushes to main.

• SPM cache: .build is cached keyed on spm-v2-${{ runner.os }}-${{ hashFiles('Package.resolved') }}. The v2 token exists because the repo rename md → Edmund changed the checkout path and invalidated absolute paths baked into the cached module cache — bump the token to discard a poisoned cache.
• Concurrency: cancel-in-progress: true per branch/PR — private-repo macOS minutes bill at 10x, so superseded commits' runs are cancelled.
• Release pipeline (release.yml, tag-triggered) is a separate beast: edmund-release-and-operate / docs/ARCHITECTURE.md §13.

8. Checklists

Fresh clone to green

• sw_vers — macOS 14+; swift --version — Swift 6.x (Xcode 16+)
• git clone + cd Edmund
• swift build — SPM fetches swift-markdown, SwiftMath, Sparkle
• swift test — ~750+ tests green in ~10s
• Read docs/ARCHITECTURE.md (mandated by CLAUDE.md before non-trivial work)
• Visual work planned? ./scripts/build-app.sh, confirm build/Edmund.app exists and ls build/Edmund.app/*.bundle shows the SwiftMath bundle
• Releases planned? node --version ≥20, npm install --global create-dmg

Before trusting any run

• Binary is fresh: strings <binary> | grep '<long unique literal>' and/or shasum changed since the edit (§5)
• pgrep -lx edmd — user's live instance identified; you will kill only your own PID (§6)
• Launched by direct exec, not open -a (§4)
• -ApplePersistenceIgnoreState YES passed
• Test document recreated fresh (autosave mutated the last one)
• Debug bundle: Sparkle.framework sits next to the binary
• Release bundle: SwiftMath *.bundle at the .app root (or the first LaTeX render crashes)

Provenance and maintenance

Every claim above was read from the files below on 2026-07-05. Re-verify:

• Toolchain/deps: cat Package.swift (tools-version, platforms, dep versions); grep identity Package.resolved
• Build anatomy: cat scripts/build-app.sh (step order, sealing comments)
• Test count/time: swift test 2>&1 | tail -3
• Debug bundle recipe: docs/dev-guides/live-repro-guide.md §4
• Stale-build disease, launch gotchas: docs/ARCHITECTURE.md §8 ("Stale release builds", "open Edmund.app", savedState)
• CI facts: cat .github/workflows/ci.yml (cache key comment, concurrency)
• create-dmg quirks: docs/ARCHITECTURE.md §8 ("create-dmg — npm only")

If a command here disagrees with those files, the files win — update this skill.

Caret-integrity campaign (the delete-drift class)

Six rounds are settled; new rounds are expected. This class does not reproduce in headless tests — the harness runs AppKit's deferred machinery synchronously, so a green unit test proves nothing here. Success is measured by PASS/FAIL grep and byte counts, never by eye or by reasoning.

Verified 2026-07-05 against docs/investigations/delete-drift-investigation.md (456 lines) and the code. Read that doc fully before a deep dive.

QUICK CARD (the whole loop)

0. CLASSIFY   grep logs for the 4 signatures. Not this class? → debugging-playbook.
1. FENCE      check the 6 settled battles + guards still hold. Don't re-fight them.
2. EVIDENCE   run with verbose diags; find FIRST bad line; walk BACKWARDS;
              traceSelectionOrigin names who moved the caret; rebuild the doc.
3. REPRO      ReproScript: needles not offsets; real events; replicate internal
              call sequences verbatim. Freeze a script whose logsel/assertcaret
              DISCRIMINATES broken vs current build. No repro → hypothesis wrong.
4. SOLVE      rank candidates (missing guard < extend heal < reorder fixup <
              structural). Each states what it must PROVE.
5. PROMOTE    fix flips frozen repro to PASS same run → soak 4–5 cycles,
              byte-identical rawLen → swift test green → add test (locks headless
              contract even if non-discriminating) + keep .repro → update the
              investigation doc → branch/commit via change-control. Never ship on
              reasoning alone.

PHASE 0 — Classify: is it actually this class?

Grep ~/.edmund/logs/edmund-<date>.log (run the app with -settings.general.diagnosticLogging YES -settings.advanced.verboseEditorDiagnostics YES):

scripts/grep-trace.sh in edmund-live-repro-and-diagnostics surfaces all four at once.

If none match and the symptom is scroll/viewport-shaped (jump, wrong landing, can't-scroll-up) with the caret not leaping → this is the viewport class, not caret integrity → edmund-debugging-playbook + docs/investigations/viewport-glitch-investigation.md. Do not run this campaign on a viewport bug.

PHASE 1 — Fence off the six settled battles

Confirm each shipped guard still holds before hypothesizing a new mechanism. The most likely round-7 shape is a new code path that lacks an existing guard, not a new mechanism.

Confirm the guards exist:

grep -rn 'hasMarkedText' Sources/EdmundCore/TextView/
grep -n 'scheduleBypassedEditSyncCheck\|healing storage edit' Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift

FENCED WRONG PATHS (each proven dead — do not retry)

• Fixing by nudging the caret at symptom time. The symptom is armed seconds-to-minutes earlier (round 6: drift at 22:13 armed at 22:11:57). You'd patch the wrong instant.
• Trusting a headless regression test. The round-6 test passes with and without the fix. Headless runs the fixup synchronously.
• Shipping on reasoning alone. Rounds 1–5 all came back. Round 6's first fix candidate "worked by reasoning" and failed in the repro within a minute.
• Assuming didChangeText pairs with every mutation. AppKit violates this (round 4).
• Mutating storage mid-composition. That is the original bug (rounds 1–3).
• Expecting a scripted keystroke replay to arm round 7. Round 7 was replayed faithfully from a reconstructed t0 (every keystroke + capped pauses through the whole drift window) and it did not produce the block-end leap. Programmatic caret moves (clickoff) and imprecise synthetic clicks (realclickoff — lands off-by-a-few, diverges, crashes) do not fully arm it. The arming needs real mouse clicks at real positions and probably the real session's two-document window switching (becomeFirstResponder resync is the prime suspect). Round-8 lead: two open docs + real clicks, or instrument becomeFirstResponder/the caret-move restyle to catch the next live occurrence. Compressed replays also coalesce a bypass with the next keystroke into one pendingEdit hull (never happens live — the heal runs first), producing off-by-one breadcrumb noise; don't trust it as a repro.

PHASE 2 — Capture evidence

1. Launch with verbose diagnostics (debug bundle; file arg is argv[1]):

   build/EdmundDbg.app/Contents/MacOS/edmd DOC.md \
     -settings.general.diagnosticLogging YES \
     -settings.advanced.verboseEditorDiagnostics YES \
     -ApplePersistenceIgnoreState YES
   

2. Decode the trace fields: sel/active/marked/up/undo/blocks/storLen/rawLen. up=Y = event arrived mid-recompose (suspicious). Healthy ordering: shouldChangeText → selectionDidChange (up=N) → synced; a transient ⚠︎LEN-MISMATCH between those is normal, a persisting one is not.
3. Find the FIRST bad line, then walk BACKWARDS. The visible symptom is often the second half of a two-part mechanism.
4. traceSelectionOrigin logs the call stack of whoever moved the selection mid-recompose — this is what named _fixSelectionAfterChange in round 6. If the caret moves and you don't know who moved it, this answers it in one run.
5. Reconstruct the document. Wrapped-paragraph geometry and block kinds matter — repro against a lookalike, never "hello world".

Gate: you have a candidate trigger hypothesis + the first-bad-line timestamp. Otherwise instrument (add a Log.shouldTrace breadcrumb — one call stack or state dump beats ten speculative fixes) and wait for the next occurrence.

PHASE 3 — Build the deterministic repro

Use the in-process ReproScript driver (Sources/edmd/App/ReproScript.swift, DEBUG only; full guide in edmund-live-repro-and-diagnostics). Commands: sleep / caret / type / backspace / bypassdelete / assertcaret / logsel.

Worked example — the round-6 minimal repro (the first deterministic repro in six rounds):

sleep 2000
bypassdelete Sizemore,
sleep 800
logsel            # broken build: 321   fixed build: 290
backspace 2
logsel

The deciding output was logsel 321 → 290 with the fix, every run, window not even visible.

Rules that make repros survive editing:

• Needles, not offsets — offsets go stale the instant the script edits.
• Real events, not method shortcuts — insertText("") skips deleteBackward's selection machinery, exactly where round 6 lived.
• Replicate AppKit-internal call sequences verbatim — bypassdelete does shouldChangeText→replaceCharacters, no didChangeText, not an approximation. For a new internal path, pin its real sequence from a traceSelectionOrigin stack first, then replay it (extend ReproScript ~10 lines).

Gate: a frozen script (exact commands + document) whose logsel / assertcaret PASS/FAIL output discriminates the broken build from the current one.

No repro after honest attempts? The hypothesis is wrong, or fidelity is too low — a mouse-only path (real drag-select/drag-move) needs the CGEvent driver (edmund-live-repro-and-diagnostics §4). Loop back to Phase 2.

PHASE 4 — Solution menu (ranked; each with a proof obligation)

Pick by the observation pattern. Cheaper is higher.

1. Add a missing guard on an existing invariant (cheapest, most likely for a new round). Guard inventory: !hasMarkedText() on the offending styling path; bypass-check scheduling on a new mutation entry point; caret re-assertion after a restyle. Proof: the frozen repro flips to PASS and no other .repro regresses. Selects when: a specific new code path shows the round-1/4/6 signature that its siblings already guard.
2. Extend the heal to a new bypass source. Proof: first add a ReproScript command that replays the new source's exact call sequence, show it reproduces the freeze, then show the extended heal fixes it. Selects when: trace shows a shouldChangeText with no close-out from a path other than drag-move.
3. Intercept/reorder the queued fixup. Proof obligation: explain when TK2 queues and fires _fixSelectionAfterChange and show the reorder does not fight AppKit's machinery (no oscillation, no double-move). Selects when: traceSelectionOrigin names the fixup and the caret is valid before it fires. Higher risk — you are stepping into private AppKit ordering.
4. Structural: make rawSource sync independent of didChangeText pairing (e.g. a storage-version counter that reconciles regardless of which callbacks fired). Biggest change; candidate, unproven — route through edmund-research-frontier (frontier item "caret integrity by construction"). Proof: all historical .repro scripts + a randomized bypass-fuzzer soak stay green with the callback-pairing assumption removed.

PHASE 5 — Validate and promote

1. Fix candidate flips the frozen repro to PASS within the same run. (If it only "works by reasoning," it is not done — round history.)
2. Soak (edmund-live-repro-and-diagnostics §3): one script, one run, 4–5 trigger cycles at different document positions with ordinary editing between, assertcaret after every predictable step. Green across all cycles and byte-identical final rawLen across repeated runs = deterministic.
3. swift test green (also the Stop hook).
4. Add a regression test even if it can't discriminate the live mechanism — it locks the headless contract (assert rawSource == string; see the BypassedEditSyncTests / MarkedTextDesyncTests family). Keep the .repro script in the repo for the live half.
5. Update docs/investigations/delete-drift-investigation.md with the new round (symptom → root cause → repro recipe → fix → status), and docs/ARCHITECTURE.md §8 if an invariant changed — same PR.
6. Route through edmund-change-control: branch fix/… off main, small commits, never auto-push/PR/merge. (No screencapture unless the fix also draws.)

Never promote a fix that only "works by reasoning."

When NOT to use this skill

• Viewport/scroll drift where the caret itself does not leap → edmund-debugging-playbook + docs/investigations/viewport-glitch-investigation.md.
• Just need the repro driver mechanics / trace decoding → edmund-live-repro-and-diagnostics.
• The AppKit theory behind the mechanisms → textkit2-appkit-reference.
• The historical record of prior rounds → edmund-failure-archaeology.
• The structural (round-∞) redesign as a research project → edmund-research-frontier + edmund-research-methodology.

Provenance and maintenance

Verified 2026-07-05 against docs/investigations/delete-drift-investigation.md, Sources/edmd/App/ReproScript.swift, and Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift.

grep -nE '^## Round' docs/investigations/delete-drift-investigation.md          # round chronicle
grep -n 'scheduleBypassedEditSyncCheck\|healing storage edit' Sources/EdmundCore/TextView/EditorTextView+EditFlow.swift
grep -rn 'hasMarkedText' Sources/EdmundCore/TextView/
grep -oiE '"(bypassdelete|assertcaret|logsel)"' Sources/edmd/App/ReproScript.swift | sort -u
# round-6 discriminating numbers (321 broken / 290 fixed):
grep -n '321\|290' docs/investigations/delete-drift-investigation.md

When round 7 lands, add its row to Phase 1 and its dead ends to the fenced list.

Edmund change control

Last verified: 2026-07-05, against main @ fe8a1f5 (release 0.1.3).

This is the gatekeeping doc: what class of change you are making, which gate it must pass, and the rules that are never traded away. The rules exist because each was paid for — the incident column is not decoration.

0. Before you start (task setup)

[ ] Read docs/ARCHITECTURE.md before any non-trivial change (its own rule)
[ ] git status — note any uncommitted work; never clobber it
[ ] Not on main? Fine. On main? Branch NOW, before the first edit
[ ] Classify the change (§1) so you know the gate before you write code
[ ] Edit-pipeline / selection work? Plan the live repro FIRST — if you can't
    reproduce the bug, you can't prove the fix (§3, last row)

1. Classify the change, apply the gate

Classify FIRST, before writing code. The class decides the verification bar.

Notes on the gates:

• swift test (~750+ tests, ~10s) also runs automatically as a Stop hook (.claude/settings.json: swift test 2>&1 | tail -5) at the end of every turn. That is a safety net, not the gate — run it yourself before committing so the failure is yours to see, not the hook's.
• A change can be in multiple classes. Apply the union of gates. A caret fix that also moves a decoration needs test + screencapture + live repro.
• "Draws" is broad: padding, insets, colors, wrapping, fragment frames. If a human could see the diff, screenshot it.

Classification edge cases that have gone wrong before:

• "It's just an attribute change" is NOT automatically the code-logic class. If the attributes change measured geometry (font size, paragraph spacing, hidden-delimiter width), it draws AND it needs invalidateLayout(for:) — see §3.
• "It's just a restyle helper" that runs beginEditing/setAttributes on storage is edit-pipeline class if it can fire during IME composition or after a bypassed edit. When in doubt, grep for hasMarkedText guards on the sibling paths and match them.
• A test-only change is docs-class for gating purposes (nothing to screenshot), but the Stop hook still must pass — a broken test is a broken commit.
• Release-adjacent edits (Info.plist versions, CHANGELOG.md, appcast.xml, scripts/release.sh, .github/workflows/) are release class even when tiny. The v0.1.0→0.1.1 Sparkle failure came from the build script's signing step, not from app code.

2. Git discipline

From CLAUDE.md + ARCHITECTURE §12 + the repo's own history (git branch -a).

• Branch off main for every fix. Never commit straight to main. One feature/fix per branch.
• Branch prefixes actually in use (verified): fix/, feat/, feature/, docs/, chore/, uiux/, ui/, ux/, markdown/, bug/, refactor/, ci/, release/. Prefer fix/, feat/, docs/, chore/ for new work; uiux/ for visual polish; markdown/ for syntax-feature work.
• Small, logical commits; commit frequently. A commit that mixes the fix with a drive-by refactor is two commits done wrong.
• NEVER auto-push, open a PR, or merge. Only when the maintainer explicitly asks. No exceptions for "it's just docs."
• Never discard uncommitted changes. No git checkout -- ., git reset --hard, git clean on a dirty tree without explicit permission.
• Commit messages follow the observed style: fix(editor): …, docs: …, ui: …, chore: … — short imperative subject.

3. The non-negotiables

Each rule was established by an incident. Verify against the cited doc before arguing an exception.

The two incidents that shaped this table

Worth knowing as stories, because the rules read as pedantry until you see the cost:

• Delete-drift (six rounds). The hardest live problem this repo has had. A caret that drifted after deletes. Round 1 blamed IME stranding — plausible fix, shipped, recurred. Round 2 disabled remaining marked-text sources — recurred. Round 3 stopped guessing and built diagnostics (selection tracing, event logs). Round 4's diagnostics caught a drag-move deleting storage with no didChangeText — the heal was born. Round 5: the heal itself leaped the caret via a stale selection. Round 6 found the actual drift mechanism — TextKit 2's queued _fixSelectionAfterChange firing at the next endEditing — and held only because the ReproScript driver could replay the exact keystroke sequence deterministically. Five shipped fixes failed; the one preceded by a frozen repro stuck. That asymmetry IS the change-control policy for this bug class.
• Undo/redo viewport drift. Undo restored a snapshot via full recompose, which reset every fragment to a TK2 height estimate; the follow-up scroll-to-caret then landed wrong and the viewport jumped. The fix (5bb2b40) diffs the snapshot against current text and applies only the changed span with recomposeReplacing. Moral: in TK2, layout state is part of the document state you must preserve — "re-render everything" is never the safe fallback here, it is the bug.

4. Review expectations

• ARCHITECTURE.md is updated in the same PR whenever you learn something non-obvious or change an invariant. The doc's own header demands this; the gotchas in §8 all arrived this way.
• Quirks are documented as comments at the code site — the edge case, the workaround, the why. Not in commit messages, not in CLAUDE.md.
• New known issues go in ARCHITECTURE §9 with a one-line repro and a pointer to any deeper write-up in docs/.
• Big investigations (multi-round bugs) get a docs/*-investigation.md chronicle — see edmund-failure-archaeology for the pattern.

5. Pre-commit checklist (copy-paste)

The workflow that worked (ARCHITECTURE §12 + CLAUDE.md). Run it verbatim:

[ ] swift test — all green (also enforced by the Stop hook; don't rely on it)
[ ] New behavior / bug fix → a test exists that fails without the change
[ ] Draws anything? → build app, screencapture window-by-id, look at the PNG
[ ] Edit-pipeline / selection change? → live repro or soak script passed
[ ] On a branch off main (fix/…, feat/…, docs/…, chore/…), NOT on main
[ ] Diff touches only what the task needs; style matches surroundings
[ ] Learned something non-obvious? → ARCHITECTURE.md updated in this change
[ ] Quirk introduced/found? → comment at the code site
[ ] Commit is small and logical; message matches repo style (fix(scope): …)
[ ] NOT pushing, NOT opening a PR, NOT merging (unless explicitly asked)

6. Ask the maintainer first — always

Never do these unprompted; ask and wait for an explicit yes:

When NOT to use this skill

Provenance and maintenance

• Sources: CLAUDE.md (repo root), docs/ARCHITECTURE.md §1 §2 §8 §9 §12, .claude/settings.json (Stop hook), misc/before-you-release.md, misc/how-to-release.md, docs/investigations/delete-drift-investigation.md (rounds 1–6), docs/investigations/archives/callout-title-wrap-investigation.md, git log / git branch -a as of fe8a1f5 (2026-07-05).
• Commits cited were verified in git log: 5bb2b40 (diff-based undo restore), 9f99795 (round-4 heal), ae61644 (stroked-path callout icon), 1b1420a (round-6 caret re-assert).
• Two rules rest on maintainer statements rather than repo docs: the measure-from-pixels rule and the test-files/ ownership rule. If either gets written into ARCHITECTURE.md, point at it here.
• Maintain: when a new incident produces a new rule, add a row to §3 with the incident pointer in the same PR that adds the rule to ARCHITECTURE.md. When the Stop hook in .claude/settings.json changes, update §1's note.

Edmund configuration & flags

Ground-truth catalog of every knob. Code wins over docs — every value below was read from source on 2026-07-05; re-verify with the greps at the end before trusting a value in a decision.

Two source-of-truth files:

• Sources/edmd/Settings/AppSettings.swift — every UserDefaults key + typed accessor.
• Sources/edmd/Settings/*View.swift (Appearance / General / Advanced) + FontSettings — the SwiftUI panes (@AppStorage).

Definitions used below: UserDefaults = macOS per-app persisted key/value store; argument domain = passing -<key> <value> on the command line overrides that default for one launch; @AppStorage = SwiftUI wrapper binding a view to a UserDefaults key.

1. User settings (UserDefaults keys)

Every key is a static let in AppSettings.swift. The key string (not the Swift name) is what you pass as a launch arg.

Content width (the physical-column design): persisted as centimetres (maxContentWidthCm); contentWidthUnit is a display unit only. The column is an absolute physical cap converted to points via the display's real PPI (NSScreen.physicalPPI, from CGDisplayScreenSize), applied as a symmetric textContainerInset.width. Default is locale-aware — 5 in (US) / 12 cm (elsewhere) — and doubles as the slider's magnetic snap point. Recomputed on resize and on NSWindow.didChangeScreenNotification. Consumer path lives in EditorTextView+ContentWidth.swift.

Window sizing trap: persistence must round-trip the frame size, not the contentView.bounds size — reapplying content size grows the window by the title-bar + toolbar height on every reopen, and heights below minSize get silently rejected. Save window.frame.size, reapply with window.setFrame(_:) after the toolbar is installed. (Note: the key on disk is settings.window.lastHeight — code, not the lastWindowSize some docs say.)

Crash uploading is inert: sendCrashLogs defaults off AND the Settings ▸ Advanced toggle is commented out in AdvancedSettingsView.swift, and CrashReporter.reportingEndpoint is a REPLACE-ME.invalid placeholder (CrashReporter.swift:27, // TODO: real server). Nothing uploads today. Un-inert it only when a receiving server exists (see edmund-release-and-operate).

2. Launch arguments

macOS reads -<UserDefaults-key> <value> into the argument domain. Pass the key string from §1, not the Swift name. The file to open must be argv[1] (before the flags).

build/EdmundDbg.app/Contents/MacOS/edmd FILE.md \
  -settings.general.diagnosticLogging YES \
  -settings.advanced.verboseEditorDiagnostics YES \
  -debug.reproScript SCRIPT.repro \
  -ApplePersistenceIgnoreState YES

-debug.reproScript is the only Edmund-specific debug key; it does not have an AppSettings accessor — it is read directly in ReproScript.swift. It is compiled out of release builds.

3. Compile-time axes

#if DEBUG gates live in: EditorTextView.swift, EditorTextView+EditFlow.swift, Diagnostics/Log.swift, edmd/App/main.swift, edmd/App/ReproScript.swift. What they gate:

• The TextKit-1 tripwire (EditorTextView.swift:273+): a DEBUG observer on NSTextView.willSwitchToNSLayoutManagerNotification that asserts if the view ever falls back to TextKit 1. Ships only in DEBUG; the fallback itself is silent and permanent (see edmund-architecture-contract).
• ReproScript — the whole in-process keystroke driver.
• Log level threshold — Log.swift compiles a lower floor in DEBUG (debug+) than release (info+); see §4.

Named tuning constants (not user-facing, but they behave like knobs):

4. Logging config

Read Sources/EdmundCore/Diagnostics/Log.swift and EditorTextView+Diagnostics.swift.

• API: Log.{debug,info,error}(_:category:), Log.measure(_:) { … }.
• File: ~/.edmund/logs/edmund-YYYY-MM-DD.log, written on a private serial queue.
• Config flow: AppSettings.applyLogging() pushes the toggle + retention into Log.configure at launch and on change; retention pruning happens there.
• Two independent switches: diagnosticLogging (writes anything at all) and verboseEditorDiagnostics (adds the per-event editor trace). For a live repro you almost always want both on. Verbose lines are gated behind Log.shouldTrace.
• The log is opt-out (on by default), retention-pruned; the user only toggles it and picks a retention window in Settings ▸ General ▸ Diagnostics.

Trace-field decoding (sel/active/marked/up/undo/blocks/storLen/rawLen, ⚠︎LEN-MISMATCH, traceSelectionOrigin) is covered in edmund-live-repro-and-diagnostics and edmund-debugging-playbook — one home per fact; this skill only says which flags turn the trace on.

5. ReproScript command surface

Sources/edmd/App/ReproScript.swift, DEBUG only. One command per line, # comments allowed.

Adding a command is ~10 lines in ReproScript.swift. Usage, soak patterns, and launch recipe: edmund-live-repro-and-diagnostics.

6. How to ADD a setting (checklist)

Worked from an existing real path (sourceMode / content width). To add a user-facing setting:

1. Add a static let key + typed accessor in AppSettings.swift (namespace the key string: settings.<area>.<name>).
2. Bind it in the relevant SwiftUI pane with @AppStorage(AppSettings.<key>).
3. If it must affect open documents live, add/extend an applyTo… broadcast (see the font/line-height/content-width applyTo… helpers) so every open Document.editor picks it up — a setting that only takes effect on next open is usually a bug.
4. Pick a sane default (register it, or make the accessor default when absent).
5. New behavior needs a test + (if it draws) a screencapture check — route through edmund-change-control and edmund-validation-and-qa.

When NOT to use this skill

• Understanding why an invariant exists → edmund-architecture-contract.
• Release/signing/appcast flags, RELEASE_TOKEN, Sparkle keys → edmund-release-and-operate.
• Interpreting log output / running a repro → edmund-live-repro-and-diagnostics.
• Which change needs which gate → edmund-change-control.
• Build-time flags in the toolchain sense (stale builds, swift package clean) → edmund-build-and-env.

Provenance and maintenance

Verified 2026-07-05 against source. This skill drifts fastest — re-verify each table before relying on it:

# §1 all keys + strings:
grep -nE 'static let [a-zA-Z]+ = "[a-zA-Z0-9._]+"' Sources/edmd/Settings/AppSettings.swift
# §1 crash toggle still commented out / endpoint still placeholder:
grep -n 'Crash reports:' Sources/edmd/Settings/AdvancedSettingsView.swift
grep -n 'reportingEndpoint' Sources/EdmundCore/Diagnostics/CrashReporter.swift
# §2 repro flag key:
grep -n 'debug.reproScript' Sources/edmd/App/ReproScript.swift
# §3 tripwire + constant:
grep -n 'willSwitchToNSLayoutManager' Sources/EdmundCore/TextView/EditorTextView.swift
grep -n 'fullLayoutMaxLength' Sources/EdmundCore/TextView/EditorTextView.swift
# §5 repro commands:
grep -oiE '"(sleep|caret|type|backspace|bypassdelete|assertcaret|logsel)"' Sources/edmd/App/ReproScript.swift | sort -u

Known doc-vs-code discrepancies (code wins): ARCHITECTURE §7 calls the window-size key lastWindowSize; the code key is settings.window.lastHeight (lastWindowHeight). If you touch window persistence, trust the code.

Edmund debugging playbook

Date-stamped 2026-07-05. Runbook for triaging any Edmund bug. Start at the triage table, run the discriminating first check before forming a theory, and check the open-bug inventory before declaring a discovery.

When NOT to use

• Making a change, not chasing a bug → edmund-change-control.
• You already know the bug is live-only and need to build a deterministic repro → edmund-live-repro-and-diagnostics (full ladder detail; summary in §5 here).
• Caret-drift class specifically, with its six-round history → edmund-caret-integrity-campaign.
• Build/toolchain/stale-binary mechanics beyond the quick checks here → edmund-build-and-env.
• Release, signing, appcast, Sparkle pipeline → edmund-release-and-operate.
• TextKit 2 / AppKit API semantics reference → textkit2-appkit-reference.
• Launch flags and settings keys reference → edmund-config-and-flags.
• How past investigations were run and why → edmund-failure-archaeology, edmund-research-methodology.
• Pre-merge verification of a fix → edmund-validation-and-qa.

1. First 15 minutes — any new bug

Run this checklist before hypothesizing. Every step is cheap; skipping them is how rounds 1–5 of delete-drift shipped fixes that came back.

1. Check the open-bug inventory (§6). If the symptom matches a known open bug, you are done triaging — link the backlog entry and its repro asset.
2. Get the logs. ls -t ~/.edmund/logs/ and read the day's file (edmund-YYYY-MM-DD.log). Grep for the three permanent breadcrumbs:

   grep -n "healing storage edit that bypassed didChangeText\|repairing content above origin\|recovered stranded desync on focus regain" ~/.edmund/logs/edmund-*.log
   

   Also grep for invariant: (the always-on storage==rawSource tripwire) and ⚠︎LEN-MISMATCH.
3. Find the first bad line and walk BACKWARDS. The user-visible symptom is often the second half of a two-part mechanism — the round-6 caret drift was armed by a silent bypass 80 seconds and dozens of healthy edits before the leap. Never start reading at the symptom timestamp.
4. Rule out a stale build if this follows a rebuild: grep strings .build/arm64-apple-macosx/debug/edmd for a long string literal unique to the new code (≤15-byte literals are inlined on arm64 and never appear); shasum the binary. See §3c.
5. Check git history for prior art. git log --oneline -- <suspect file> plus the investigation docs in docs/. The viewport-glitch investigation found four earlier fixes all working around the same unnamed root cause.
6. Reconstruct the document. Get the user's file or rebuild it from the trace's block counts/lengths. Wrapped-paragraph geometry and block kinds matter; do not repro against "hello world".
7. Before touching any running app: pgrep -lx edmd then ps -o lstart=,command= -p <pid>. The user's daily-driver app shares the binary name. Never blanket pkill -x edmd — kill only the PID you launched.
8. Row found in §2 → run its discriminating check. No row → escalate per §5, and add the new row here when it's understood.

2. The triage table

3. The traps that cost real time

Each of these burned hours to days. Read before shipping any fix.

(a) Shipping caret fixes on reasoning alone. Delete-drift rounds 1–5 each shipped a plausible, well-argued fix — and each came back. Only round 6, the first with a frozen deterministic live repro (bypassdelete script), named the actual mechanism (_fixSelectionAfterChangeInCharacterRange queued by a bypassed edit, firing at the next endEditing) — and its first fix attempt failed in the repro within a minute, which reasoning would never have caught. Lesson: time spent making the failure cheap to observe beats time spent reasoning about the fix. Freeze the repro before writing the fix.

(b) Undo/redo viewport drift. Two defects hid behind one symptom: restoreSnapshot ran a full recompose (discarding all TK2 layout, so the follow-up scroll measured freshly manufactured estimates) and performUndo recorded the redo snapshot with the caret at undo-invocation time, not at the edit. Lesson: a wrong-scroll symptom can be a geometry bug and a plain stale-state bug stacked; fix and verify them separately. The contract since 5bb2b40: diff the snapshot, apply via recomposeReplacing, select the changed text, let the changed range drive the viewport.

(c) Stale binaries produce false conclusions. In round 6, swift build twice printed Build complete! while linking a stale edmd — the compile ran, the relink silently didn't — and two "failed" fix iterations were phantoms. Detect: grep strings on the binary for a long literal unique to the new code. Cure: swift package clean (or rm -rf .build for release weirdness). Never hand-delete .build/…/edmd.build/ — that corrupts the output-file-map and wedges the target until a full clean.

(d) Headless-green ≠ fixed for input-layer bugs. The round-6 unit test reconstructs the exact document and gesture and passes with and without the fix: the test harness runs AppKit's deferred selection fixup synchronously, so the broken state never forms. A green test proves nothing about the live NSTextView / TextKit 2 / input-context class. The scripted live repro is the regression harness; the unit test is only a contract spec.

(e) open -a runs stale cached copies. LaunchServices can foreground an already-running instance instead of relaunching, and can execute a stale cached/translocated copy of the bundle — you debug last hour's code. Always launch by direct exec: build/Edmund.app/Contents/MacOS/edmd file.md & (after the §1 step-7 pgrep check).

(f) Trusting off-screen fragment y-coordinates. A TK2 fragment's frame is real only once laid out; everything off-screen, plus total document height, is an estimate. Any code that measures before ensuring layout of the viewport↔target span lands wrong (this is Bug 1a, the typewriter-scroll gotcha, and most historical viewport glitches). Ensure layout for the target range first, then align to real geometry — and never verify a visual fix from headless layout: measure from screencapture pixels.

4. Discriminating experiments — cheap checks that split hypothesis spaces