Edmund

Documentation of record for the Edmund repo: which doc owns which fact, and how to write in the house style. Load whenever you are writing or updating ANY project doc — docs/ARCHITECTURE.md, CHANGELOG.md, README.md, docs/ROADMAP.md, misc/backlog.md, a docs/<topic>-investigation.md write-up, release docs — or deciding WHERE a newly learned fact, gotcha, bug, or feature idea belongs. Covers the docs-of-record map, the fact-routing decision table, the investigation-doc template, CHANGELOG format (machine-extracted for release notes), commit-message conventions, and doc maintenance duties. Not for making the code change itself, release mechanics, or debugging — see "When NOT to use this skill".

The load-bearing design contract of the Edmund Markdown editor. Load BEFORE any non-trivial code change in this repo; when asking "why is it built this way"; before proposing a new mechanism, subsystem, or refactor; whenever you are tempted to insert/strip display characters, use NSTextAttachment, touch NSTextView.layoutManager, store NSTextBlock/NSTextTable attributes, or add a new overlay/decoration; and before designing anything that syncs storage, selection, undo, or the viewport. Covers the two hard invariants (storage == rawSource; TextKit 2 only), the render pipeline, edit/undo flow, the TextKit 2 drawing model, the read-mode contract, and the known weak points. Not for build/run/release mechanics, debugging triage, or live-repro drivers — see "When NOT to use this skill".

Build, environment, and toolchain runbook for the Edmund repo (native macOS Markdown editor; AppKit + TextKit 2, SwiftPM). Load this skill when: setting up the environment from scratch (fresh clone, new machine, CI mirror); a build fails or a "successful" build behaves stale (change "doesn't take", old code runs, Build complete! but nothing changed); the app crashes on launch or the instant it renders LaTeX; you need to construct the debug bundle (EdmundDbg.app) for live runs; or BEFORE trusting any binary you just built for a visual check or repro run. Covers swift build/test, build-app.sh anatomy (codesign sealing order, SwiftMath bundle placement), the stale-build disease and its detection, safe launch/kill hygiene around the user's live instance, and the CI environment.

Build, environment, and toolchain runbook for the Edmund repo (native macOS Markdown editor; AppKit + TextKit 2, SwiftPM). Load this skill when: setting up the environment from scratch (fresh clone, new machine, CI mirror); a build fails or a "successful" build behaves stale (change "doesn't take", old code runs, Build complete! but nothing changed); the app crashes on launch or the instant it renders LaTeX; you need to construct the debug bundle (EdmundDbg.app) for live runs; or BEFORE trusting any binary you just built for a visual check or repro run. Covers swift build/test, build-app.sh anatomy (codesign sealing order, SwiftMath bundle placement), the stale-build disease and its detection, safe launch/kill hygiene around the user's live instance, and the CI environment.

The executable, decision-gated campaign for Edmund's hardest live problem: the delete-drift class (caret/selection integrity in the live NSTextView / TextKit 2 / input-context layer). Load when the caret or selection lands in the wrong place after a delete/type/IME/drag interaction, when text edits corrupt or desync, when autosave writes stale content, or when logs show ⚠︎LEN-MISMATCH or the "healing storage edit that bypassed didChangeText" breadcrumb. Runs round 7+ at the retiring maintainer's standard: classify, fence off six settled battles, capture evidence, build a deterministic repro, pick from a ranked solution menu with proof obligations, then validate and promote through change control. Not for viewport/scroll drift (that's edmund-debugging-playbook → viewport docs) unless the caret itself moves.

How changes are classified, gated, and reviewed in the Edmund repo. Load at the START of any task that will modify the repo; before committing, branching, or proposing a merge or release; when deciding whether a change needs a test, a screencapture visual check, or a live repro; when unsure what requires explicitly asking the maintainer (push, PR, merge, release, deleting uncommitted work, touching test-files/, adding dependencies). Contains the non-negotiable rules with the historical incident behind each one.

Catalog of every configuration axis in the Edmund Markdown editor — user settings (UserDefaults keys, defaults, where consumed), launch arguments (diagnostic + repro flags), compile-time gates, and logging config. Load when adding or changing a setting, hunting which flag controls a behavior, launching the app with debug flags, auditing defaults, or wiring a new preference into the live editor. This skill drifts fastest of the set — every table ends with a re-verification grep. Not for the invariants (see edmund-architecture-contract), release flags (edmund-release-and-operate), or how to READ the logs (edmund-live-repro-and-diagnostics).

Load this FIRST when any bug report or unexpected behavior arrives in Edmund: caret lands in the wrong place after delete/typing, viewport jumps or scroll-to-target misses, rendering is wrong or missing, empty bands or clipped lines, everything suddenly renders as plain text, app crashes or won't launch, a code change "doesn't take" after rebuild, undo/redo lands the viewport wrong, IME/CJK/accent input misbehaves, right-click shows the wrong menu, window grows on reopen, or a Sparkle update fails. Symptom-to-mechanism triage table, the traps that cost real debugging time, discriminating trace checks, the repro escalation ladder, and the open-bug inventory so known bugs are not rediscovered fresh.

Load when writing anything an outsider will read about Edmund — README edits, blog posts, release notes, marketing copy, social posts, webpage text, Show HN drafts — or when comparing Edmund to other editors (Typora, Obsidian, MarkEdit, Nodes), deciding what may be publicly claimed vs. what is still unproven, labeling a technique "novel", or planning ecosystem work (licenses, attribution, notarization messaging, appcast, issue templates, discovery listings). This skill is the overclaim firewall: what the positioning is, what evidence backs each claim, and what must exist before a claim gets stronger.

The chronicle of every major bug investigation, dead end, rejected fix, and revert in the Edmund Markdown editor. Load BEFORE re-investigating any caret/selection symptom (drift, jump, desync), any viewport/scroll glitch (lurch, oscillation, wrong landing, can't-scroll-up), any rendering wedge (clipped wrap, one-line collapse, blank space), or any release/update failure (signing, appcast, Sparkle "improperly signed"). Load before proposing a fix that might already have been tried and reverted, when a bug report "looks familiar", when a test passes but the live app still misbehaves, or when wondering why the code does something weird (a guard, a re-assert, a deliberately-missing icon). Every entry: symptom, root cause, evidence (commit hashes, docs), status, and what NOT to retry.

How to MEASURE Edmund instead of eyeballing it — the diagnostic tools, interpretation guides, and working scripts. Load when a bug involves LIVE behavior (caret, IME, drag, viewport timing), when a unit test cannot reproduce a report, when you need to read diagnostic traces, drive the running app with scripted keystrokes, or measure pixels from a screenshot. Contains the repro escalation ladder, the ReproScript driver, the CGEvent fallback, and screencapture measurement, plus scripts/ helpers. Not the symptom→mechanism table (edmund-debugging-playbook), not the campaign (edmund-caret-integrity-campaign), not build hygiene (edmund-build-and-env).

Load when cutting or debugging an Edmund release, or operating the shipped app. Triggers: version bump (Info.plist CFBundleShortVersionString / CFBundleVersion), tagging vX.Y.Z, CHANGELOG.md release sections, release.yml / release.sh / build-app.sh, appcast.xml or Sparkle update failures ("improperly signed", update never offered), sign_update / EdDSA keys / SPARKLE_ED_PRIVATE_KEY / RELEASE_TOKEN, create-dmg or DMG naming problems, Gatekeeper "damaged" reports, launching the built app, reading ~/.edmund/logs, crash reports (edmd-*.ips), or roadmap/priority questions.

Open problems where the Edmund Markdown editor could advance the state of the art — product-first, everything labeled candidate/open, nothing proven. Load when picking the next big problem, evaluating whether an ambitious idea is worth starting, or answering "what would move this project beyond state of the art". Each frontier: why current SOTA fails, Edmund's specific asset, the first three concrete steps IN THIS REPO, and a falsifiable "you have a result when…" milestone. Not for running an accepted investigation (edmund-caret-integrity-campaign), the method of proof (edmund-research-methodology), or shipping the change (edmund-change-control).

The discipline that turns a hunch into an accepted result in the Edmund Markdown editor — the evidence bar, hypothesis-predicts-numbers, the first-principles analysis recipes, the idea lifecycle, and where good ideas historically came from. Load when forming a hypothesis about a bug's mechanism, evaluating whether an investigation's conclusion is trustworthy, deciding if a fix is actually proven, or turning an idea into an accepted change. This skill also absorbs the proof-and-analysis toolkit (prove it, don't just install it). Not the caret-integrity campaign itself (edmund-caret-integrity-campaign), not the repro tooling (edmund-live-repro-and-diagnostics).

What counts as EVIDENCE in the Edmund Markdown editor, and how to add tests. Load when writing or adjusting tests, deciding what proof a fix needs before it can ship, judging whether a change is actually "verified", interpreting the test suite, or adding a golden/regression check. Covers the evidence hierarchy (headless is necessary but not sufficient for live-input bugs), the test-suite map, the Swift Testing helpers, how to add a test, the golden inventory, visual QA, and performance evidence. Not the gating rules themselves (edmund-change-control) or how to run the live repro (edmund-live-repro-and-diagnostics).

Domain-theory pack for the AppKit text system as it applies to the Edmund Markdown editor. Load when working on layout, selection, IME, undo, drag, or eventing behavior; when TextKit 2 or NSTextView does something surprising; or when terms like NSTextLayoutManager, layout fragment, marked text, queued selection fixup, responder chain, or sendEvent appear and you lack AppKit text-system background. Explains the mechanisms the invariants and gotchas are built on. Not the invariants themselves (edmund-architecture-contract), not a triage table (edmund-debugging-playbook), not the repro drivers (edmund-live-repro-and-diagnostics).

Documentation of record for the Edmund repo: which doc owns which fact, and how to write in the house style. Load whenever you are writing or updating ANY project doc — docs/ARCHITECTURE.md, CHANGELOG.md, README.md, docs/ROADMAP.md, misc/backlog.md, a docs/<topic>-investigation.md write-up, release docs — or deciding WHERE a newly learned fact, gotcha, bug, or feature idea belongs. Covers the docs-of-record map, the fact-routing decision table, the investigation-doc template, CHANGELOG format (machine-extracted for release notes), commit-message conventions, and doc maintenance duties. Not for making the code change itself, release mechanics, or debugging — see "When NOT to use this skill".

How changes are classified, gated, and reviewed in the Edmund repo. Load at the START of any task that will modify the repo; before committing, branching, or proposing a merge or release; when deciding whether a change needs a test, a screencapture visual check, or a live repro; when unsure what requires explicitly asking the maintainer (push, PR, merge, release, deleting uncommitted work, touching test-files/, adding dependencies). Contains the non-negotiable rules with the historical incident behind each one.

What counts as EVIDENCE in the Edmund Markdown editor, and how to add tests. Load when writing or adjusting tests, deciding what proof a fix needs before it can ship, judging whether a change is actually "verified", interpreting the test suite, or adding a golden/regression check. Covers the evidence hierarchy (headless is necessary but not sufficient for live-input bugs), the test-suite map, the Swift Testing helpers, how to add a test, the golden inventory, visual QA, and performance evidence. Not the gating rules themselves (edmund-change-control) or how to run the live repro (edmund-live-repro-and-diagnostics).