Run any Skill in Manus with one click

edmund-external-positioning

Stars112

Forks4

UpdatedJuly 9, 2026 at 21:44

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.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

I7T5

I7T5/Edmund

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

More from this repository

same repository

edmund-docs-and-writing

I7T5/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".

2026-07-13112

edmund-architecture-contract

I7T5/Edmund

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".

2026-07-10112

edmund-build-and-env

I7T5/Edmund

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.

edmund-caret-integrity-campaign

I7T5/Edmund

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.

2026-07-09112

edmund-change-control

I7T5/Edmund

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.

2026-07-09112

name

edmund-external-positioning

description

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

You are doing	Use instead
Actually cutting a release (tags, appcast, Sparkle, CI)	edmund-release-and-operate
Internal docs, ARCHITECTURE.md, investigation chronicles	edmund-docs-and-writing
Understanding the invariants / render pipeline itself	edmund-architecture-contract
Deciding whether a code change is allowed	edmund-change-control
Reproducing or debugging a bug	edmund-debugging-playbook, edmund-live-repro-and-diagnostics
Judging research novelty for internal direction (not public claims)	edmund-research-frontier, edmund-research-methodology
Verifying behavior before shipping	edmund-validation-and-qa

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)

#	Claim (verbatim)
1	"Live preview: Typora/Obsidian-style WYSIWYG."
2	"File-based: Open `.md` files from anywhere. No vaults or dedicated folders required."
3	"Native: 100% Swift. Based on AppKit and TextKit 2. No Electron. Minimal dependencies."
4	"Fast: Handles ~1-2MB files with ease. No launch lag."
5	"Extensible: Opt-in math and Obsidian syntax. Extensions system coming soon!"
6	"Private: Offline by default. Optional blocking of external links and HTML sanitization."

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.

Claim	Current evidence	Required before strengthening
Fast: "~1-2MB files with ease. No launch lag"	`Tests/EdmundTests/PerfHarnessTests.swift` (gated `MD_PERF=1`, default 1.5MB doc, prints latencies; assertions are deliberately "sanity bounds, not budgets"); viewport-first lazy styling with `fullLayoutMaxLength = 100_000` regime (`EditorTextView.swift:80`)	A reproducible public benchmark: pinned document + hardware noted + numbers an outsider can rerun (`MD_PERF=1 swift test`). No comparative "faster than X" claims without benchmarking X the same way.
Extensible: "Extensions system coming soon!"	Extensions API is `docs/ROADMAP.md` v1.0.0 — not shipped. Only opt-in math + Obsidian syntax exist today. README already hedges with "coming soon"	Keep it hedged until the API + docs + at least one working extension ship. Never write "extensible via plugins" in present tense.
Private: "Offline by default"	Grounded: Read webview disables JavaScript; all assets inlined as data URIs (math, icons, local images); remote images off by default (`ReadRenderOptions.allowRemoteImages = false`); inline HTML whitelisted via `HTMLRenderer.sanitizeInlineHTML`	Note: the "Block external images" Settings checkbox is a `misc/backlog.md` item, not shipped; "optional blocking of external links" in README is forward-leaning — verify against code before repeating it elsewhere. Exceptions to name if asked: Sparkle update check, opt-in crash-log upload (§7 ARCHITECTURE).
Native: "100% Swift … No Electron. Minimal dependencies"	True: SwiftPM, three deps (swift-markdown, SwiftMath, Sparkle) + vendored Lucide SVGs. Read mode is a WKWebView (system WebKit, JS off) — that is not Electron, but don't say "no web views"	Nothing; this claim is safe. Just never inflate to "zero dependencies".
Live preview: "Typora/Obsidian-style"	Shipped and demoed (README video, screenshots)	Safe. Comparative feature-parity claims vs. Typora/Obsidian need a feature-by-feature check first.
File-based: "No vaults"	Shipped by design	Safe.
Beta status	v0.1.3 (2026-07-04)	Must stay visible everywhere until v1.0.0.

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)

Candidate	Why it might be blog-worthy	Proof needed first
Attribute-only rendering with the storage == rawSource invariant (no attachment characters, no U+FFFC; delimiters hidden, never stripped; identity offset mapping)	A clean architectural answer to the classic WYSIWYG mapping problem	A survey showing how the named alternatives (incl. swift-markdown-engine) handle storage vs. display; the invariant's consequences demonstrated with runnable examples
Stroked-`CGPath` overlay workaround for the TK2 image wedge (image in a fragment overlay collapses the fragment's layout to one line; callout icon drawn as stroked path from vendored Lucide SVG instead)	A concrete, reproducible TK2 bug + workaround — the classic useful engineering post	A minimal frozen repro of the wedge outside Edmund; macOS version range where it reproduces
Bypassed-`didChangeText` heal + caret re-assertion (round-6 mechanism: TK2 leaves a `_fixSelectionAfterChange` queued after a bypassed edit; next-run-loop sync check heals storage and re-asserts the caret)	Deep TK2 internals nobody has documented; the delete-drift chronicle (`docs/investigations/delete-drift-investigation.md`) already exists as raw material	The frozen ReproScript repro kept green; behavior confirmed on current macOS before publishing (private-method behavior can change under us)
Diff-based undo restore that preserves TK2 layout (snapshot restore diffs rather than replaces, bypassing NSTextView undo)	Practical fix for a visible TK2 pain (undo viewport yank)	Before/after measurements (layout work saved, viewport stability) on a pinned document
In-process ReproScript methodology (`-debug.reproScript`, keystroke replay without CGEvents/TCC; `docs/dev-guides/live-repro-guide.md`)	Reusable testing methodology for any AppKit text app	Show it reproducing a real bug end-to-end in a fresh checkout; that IS the reproducibility standard

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).