sethbang · sethbang · May 19, 2026 · May 19, 2026 · May 19, 2026 · May 19, 2026
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,8 +1,8 @@
 name: Release
 
-# Triggered by pushing a tag like v0.2.0. Builds Markee.app from the tagged
-# commit, zips it, and publishes a GitHub Release with the zip attached and
-# the matching CHANGELOG.md section as the release body.
+# Triggered by pushing a version tag (v*). Builds Markee.app from the tagged
+# commit, Developer-ID-signs and notarizes it, zips it, and publishes a GitHub
+# Release with the zip attached and the matching CHANGELOG.md section as body.
 
 on:
   push:
@@ -14,7 +14,7 @@ permissions:
 
 jobs:
   release:
-    name: Build + publish Markee.app
+    name: Build + notarize + publish Markee.app
     runs-on: macos-14
     steps:
       - uses: actions/checkout@v4
@@ -37,36 +37,96 @@ jobs:
       - name: Test
         run: make test
 
-      - name: Build app bundle
+      - name: Import Developer ID certificate
+        env:
+          MACOS_CERT_P12: ${{ secrets.MACOS_CERT_P12 }}
+          MACOS_CERT_PASSWORD: ${{ secrets.MACOS_CERT_PASSWORD }}
+        run: |
+          if [ -z "$MACOS_CERT_P12" ]; then
+            echo "::error::MACOS_CERT_P12 secret is not set"; exit 1
+          fi
+          CERT_PATH="$RUNNER_TEMP/markee-cert.p12"
+          trap 'rm -f "$CERT_PATH"' EXIT  # remove the decoded cert on any exit
+          KEYCHAIN_PATH="$RUNNER_TEMP/markee-signing.keychain-db"
+          KEYCHAIN_PW=$(openssl rand -base64 24)
+
+          echo "$MACOS_CERT_P12" | base64 --decode > "$CERT_PATH"
+
+          security create-keychain -p "$KEYCHAIN_PW" "$KEYCHAIN_PATH"
+          security set-keychain-settings -lut 21600 "$KEYCHAIN_PATH"
+          security unlock-keychain -p "$KEYCHAIN_PW" "$KEYCHAIN_PATH"
+          security import "$CERT_PATH" -k "$KEYCHAIN_PATH" \
+            -P "$MACOS_CERT_PASSWORD" -T /usr/bin/codesign
+          security set-key-partition-list -S apple-tool:,apple: \
+            -s -k "$KEYCHAIN_PW" "$KEYCHAIN_PATH"
+          # Prepend our keychain to the search list, keeping the existing
+          # entries (System.keychain holds the Apple CA chain codesign needs).
+          # Read into an array so each path stays a single argument.
+          OLD_KEYCHAINS=()
+          while IFS= read -r kc; do
+            [ -n "$kc" ] && OLD_KEYCHAINS+=("$kc")
+          done < <(security list-keychains -d user | sed 's/[[:space:]]*"//; s/"[[:space:]]*$//')
+          security list-keychains -d user -s "$KEYCHAIN_PATH" "${OLD_KEYCHAINS[@]}"
+
+          echo "MARKEE_KEYCHAIN=$KEYCHAIN_PATH" >> "$GITHUB_ENV"
+
+      - name: Build app bundle (Developer ID signed)
         run: make app
 
       - name: Verify bundle layout
         run: |
           test -x Markee.app/Contents/MacOS/Markee
           test -f Markee.app/Contents/Resources/LICENSE
           test -f Markee.app/Contents/Resources/THIRD-PARTY-NOTICES.md
+          test -d Markee.app/Contents/PlugIns/QuickLookPreview.appex
+          test -d Markee.app/Contents/PlugIns/QuickLookThumbnail.appex
+
+      - name: Verify Developer ID signature
+        run: |
+          if codesign -dvv Markee.app 2>&1 | grep -q "Signature=adhoc"; then
+            echo "::error::Markee.app is ad-hoc signed — Developer ID certificate import failed"
+            exit 1
+          fi
+          echo "Markee.app carries a non-ad-hoc signature."
 
       - name: Verify Info.plist version matches tag
         run: |
           TAG_VERSION="${GITHUB_REF_NAME#v}"
+          # Strip any pre-release suffix so a tag like v1.0.0-rc.1 still
+          # validates against Info.plist 1.0.0 (lets you dry-run this workflow
+          # with an -rc tag before the real release).
+          BASE_VERSION="${TAG_VERSION%%-*}"
           PLIST_VERSION=$(defaults read "$PWD/Markee.app/Contents/Info" CFBundleShortVersionString)
-          echo "Tag: $TAG_VERSION, Info.plist: $PLIST_VERSION"
-          if [ "$TAG_VERSION" != "$PLIST_VERSION" ]; then
+          echo "Tag: $TAG_VERSION (base $BASE_VERSION), Info.plist: $PLIST_VERSION"
+          if [ "$BASE_VERSION" != "$PLIST_VERSION" ]; then
             echo "::error::Tag $TAG_VERSION does not match Info.plist version $PLIST_VERSION. Bump Resources/Info.plist before tagging."
             exit 1
           fi
 
+      - name: Notarize and staple
+        env:
+          NOTARY_KEY_P8: ${{ secrets.NOTARY_KEY_P8 }}
+          NOTARY_KEY_ID: ${{ secrets.NOTARY_KEY_ID }}
+          NOTARY_ISSUER_ID: ${{ secrets.NOTARY_ISSUER_ID }}
+        run: |
+          if [ -z "$NOTARY_KEY_P8" ]; then
+            echo "::error::NOTARY_KEY_P8 secret is not set"; exit 1
+          fi
+          KEY_PATH="$RUNNER_TEMP/notary-key.p8"
+          trap 'rm -f "$KEY_PATH"' EXIT  # remove the decoded API key on any exit
+          echo "$NOTARY_KEY_P8" | base64 --decode > "$KEY_PATH"
+          export NOTARY_KEY_P8_PATH="$KEY_PATH"
+          ./scripts/notarize-app.sh Markee.app
+
       - name: Zip Markee.app
         run: |
-          zip -r -y Markee.app.zip Markee.app
+          ditto -c -k --keepParent Markee.app Markee.app.zip
           ls -la Markee.app.zip
 
       - name: Extract changelog notes for this version
         id: changelog
         run: |
           VERSION="${GITHUB_REF_NAME#v}"
-          # awk through CHANGELOG.md: when we hit `## [VERSION]`, start
-          # printing; when we hit the next `## [`, stop.
           NOTES=$(awk -v ver="$VERSION" '
             $0 ~ "^## \\[" ver "\\]" { flag=1; next }
             flag && /^## \[/ { exit }
@@ -78,10 +138,6 @@ jobs:
           {
             echo "notes<<CHANGELOG_EOF"
             printf "%s\n" "$NOTES"
-            echo ""
-            echo "---"
-            echo ""
-            echo "**First launch:** Markee is ad-hoc codesigned, not yet notarized. Right-click \`Markee.app\` → **Open** → **Open** the first time, or run \`xattr -dr com.apple.quarantine Markee.app\`."
             echo "CHANGELOG_EOF"
           } >> "$GITHUB_OUTPUT"
 
@@ -95,3 +151,10 @@ jobs:
           draft: false
           prerelease: ${{ contains(github.ref_name, '-') }}
           fail_on_unmatched_files: true
+
+      - name: Clean up signing keychain
+        if: always()
+        run: |
+          if [ -n "${MARKEE_KEYCHAIN:-}" ]; then
+            security delete-keychain "$MARKEE_KEYCHAIN" 2>/dev/null || true
+          fi
diff --git a/.gitignore b/.gitignore
@@ -8,6 +8,7 @@ Markee.app/
 
 # Generated icon (built from AppIcon.svg by scripts/build-icon.sh)
 Resources/AppIcon.icns
+Resources/DocIcon.icns
 
 # Vendored JS/CSS libraries (fetched by scripts/fetch-vendor.sh)
 Resources/web/vendor/
@@ -23,9 +24,4 @@ Resources/web/vendor/
 # Internal design specs / AI-collaboration notes — kept private
 docs/superpowers/
 
-# Failed self-signing experiment from May 2026 — kept local for reference.
-# See CLAUDE.md "Known issues blocking public release" for why this doesn't
-# work (Gatekeeper requires Apple's CA chain, not a trusted self-signed cert).
-scripts/make-signing-cert.sh
-
 .DS_Store
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,30 @@ All notable changes to Markee are documented here. Format roughly follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project uses
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.0] — 2026-05-19
+
+The first publicly distributable release — Developer ID signed and notarized,
+so Markee installs and opens without Gatekeeper warnings.
+
+### Added
+- **Quick Look preview** — press Space on a Markdown file in Finder to see it
+  fully rendered instead of as raw source. A sandboxed Quick Look extension
+  that reuses the app's renderer.
+- **Per-file Finder thumbnails** — `.md` files show a thumbnail of their
+  rendered content in Finder's icon views, falling back to the document icon.
+- **Markdown document icon** — `.md` files now carry a branded Markee document
+  icon in place of the generic plain-text page.
+- **Developer ID signing & notarization** — the app and both Quick Look
+  extensions are signed with a Developer ID certificate and notarized by Apple,
+  so they install and open without Gatekeeper warnings. `make notarize` and the
+  release workflow handle it end to end.
+
+### Changed
+- Mermaid now loads lazily — only documents that contain a diagram pay its
+  ~2.5 MB parse cost, so cold-start render is faster for everything else.
+- Bundle version bumped to `1.0.0` (CFBundleShortVersionString) / `6`
+  (CFBundleVersion).
+
 ## [0.5.0] — 2026-05-18
 
 ### Added

diff --git a/CLAUDE.md b/CLAUDE.md
@@ -32,6 +32,8 @@ make test           # swift test + node --test Tests/util.test.js (both green at
 - `Resources/AppIcon.svg` — source; `Resources/AppIcon.icns` is built (gitignored)
 - `scripts/build-icon.sh` — `sips` + `iconutil` → AppIcon.icns
 - `scripts/fetch-vendor.sh` — pinned downloads from jsdelivr
+- `scripts/sign-app.sh` — Developer ID / ad-hoc bundle signing (used by `make app`)
+- `scripts/notarize-app.sh` — `notarytool` submit + staple (used by `make notarize`)
 - `Tests/MarkeeTests/` — Swift unit tests (`@testable import Markee`)
 - `Tests/util.test.js` — Node `--test` runner over `util.js`
 - `fixtures/sample.md` — exercises every feature
@@ -73,9 +75,17 @@ Watch + rerender, atomic-save aware, scroll preservation, GFM + footnotes + defl
 
 Visual identity redesign. Integrated window chrome (no system titlebar divider, custom 44pt gradient bar, traffic lights kept). Outline sidebar redesigned with H1/H2/H3 indent + live active-section highlight (driven by `currentHeadingID` published from JS IntersectionObserver). Full `theme.css` rewrite with new token palette (`--surface`, `--accent`, etc.), Soft Modern typography, custom task-list checkboxes, faded `<hr>`, lede paragraph after H1. Dark + light themes, system-following via `prefers-color-scheme`. See `docs/superpowers/specs/2026-05-11-ui-ux-redesign-design.md`.
 
+## What's done (v1.0 — Finder integration & notarization)
+
+Quick Look preview + per-file thumbnail extensions — a shared `MarkeeKit`
+renderer behind two `.appex` bundles in `Contents/PlugIns/`. Branded Markdown
+document icon. Mermaid now lazy-loaded (only diagram-bearing documents pay its
+cost). Developer ID code signing + notarization for the app and both
+extensions — see "Signing & notarization". The first publicly distributable
+release.
+
 ## Not done
 
-- Apple Developer ID signing / notarization (needed for distribution beyond your machine) — see "Known issues blocking public release" below
 - DMG / Homebrew cask
 - PreviewController test coverage: `toggleTask` drift bailout, line-ending preservation, export-HTML write
 - Print stylesheet (uses screen CSS; usually fine, breaks near page boundaries can be ugly)
@@ -85,8 +95,12 @@ Visual identity redesign. Integrated window chrome (no system titlebar divider,
 
 ## Known issues blocking public release
 
+*Issues #1 and #4 are resolved by Developer ID notarization (see "Signing & notarization" below). #2 and #3 remain.*
+
 ### 1. Open With picker grays out Markee; not in "Recommended Applications"
 
+**Status: RESOLVED — the app is now Developer ID signed and notarized (see "Signing & notarization" below), so `spctl -a` passes and the picker enables Markee normally. The diagnosis below is kept for historical context.**
+
 **Symptom.** Right-click .md → Open With → Other… shows Markee grayed out under "Recommended Applications" *and* under "All Applications". The bundle is registered, the binding is correct, and `open -Ra Markee` works — but the picker UI refuses to let users select it.
 
 **Why.** macOS (Sonoma+) gates the Open With picker on a Gatekeeper assessment (`spctl -a`). Ad-hoc signed apps fail this assessment. Self-signed certs — even trusted system-wide via `security add-trusted-cert -p codeSign` — *also* fail, because `spctl -a` specifically requires Apple's CA chain (Developer ID Application or notarized). There is no purely-local workaround. Note also: every file in the bundle carries `com.apple.provenance` xattr that `xattr -cr` cannot remove on Sonoma+; this is kernel-managed and Apple intends for it to stay.
@@ -95,7 +109,7 @@ Visual identity redesign. Integrated window chrome (no system titlebar divider,
 
 **Workaround we used during development.** Get Info → Open with → "Other…" → switch dropdown to "All Applications" → navigate to /Applications/Markee.app → it's grayed but still clickable in the file dialog → click Open → Change All. Once. Then it sticks.
 
-**Real fix for public release.** Either:
+**Real fix (done — see "Signing & notarization" below).** It was:
 - Enroll in the Apple Developer Program ($99/yr), get a Developer ID Application cert, codesign with that, notarize. After notarization, `spctl -a` passes and the picker enables Markee normally.
 - Or: ship a tiny first-run helper that writes the LSHandler entries directly to the user's `launchservices.secure.plist` and runs `lsregister`. Avoids the picker entirely but doesn't help discoverability for users who didn't go through the helper.
 
@@ -117,6 +131,37 @@ Reproduce + capture logs before public release.
 
 Do **not** symlink /Applications/Markee.app → repo path. Finder's "Other…" picker won't let users select symlinked apps even in "All Applications" mode (we confirmed this in the May 2026 session).
 
+### 4. Quick Look extensions need a notarized app — RESOLVED
+
+The Quick Look preview/thumbnail extensions (`Contents/PlugIns/*.appex`) only register with `pkd` when the host app passes Gatekeeper. Ad-hoc signing does **not** work — `pkd` silently refuses to register the extensions and `pluginkit -a` no-ops. This is resolved by Developer ID signing + notarization (see "Signing & notarization" below): a notarized build passes `spctl -a`, `pkd` registers the extensions, and Quick Look + the document icon work.
+
+## Signing & notarization
+
+Markee is distributed as a Developer-ID-signed, notarized app. Both the app and
+its two Quick Look `.appex` extensions are signed with the **Developer ID
+Application** certificate and the Hardened Runtime, then the bundle is notarized
+by Apple and the ticket stapled. The app itself is **not** sandboxed — it watches and writes Markdown files at arbitrary paths. The two Quick Look `.appex` extensions, however, **are** sandboxed (`Resources/QuickLookExtension.entitlements`): `pkd` refuses to register an unsandboxed Quick Look extension. Their entitlements are `com.apple.security.app-sandbox`, `com.apple.security.files.user-selected.read-only` (to read the previewed file), and `com.apple.security.network.client` — the last is **load-bearing**: without it `WKWebView`'s helper processes crash inside the sandboxed extension and the renderer hangs forever (preview shows an endless spinner). `sign-app.sh` signs the extensions with those entitlements and the app without.
+
+- `scripts/sign-app.sh` signs the bundle inside-out. With a Developer ID
+  identity in the keychain it signs Developer ID + Hardened Runtime; with none
+  it falls back to ad-hoc (so CI build-test and contributors still build).
+- `scripts/notarize-app.sh` zips, submits to `notarytool`, and staples.
+- `make app` signs; `make notarize` builds + signs + notarizes + staples.
+
+**Local setup (one-time):**
+- Install the "Developer ID Application" certificate in your login keychain
+  (Xcode → Settings → Accounts → Manage Certificates, or the developer portal).
+- Store the App Store Connect API key as a notarytool keychain profile:
+  `xcrun notarytool store-credentials markee-notary --key <AuthKey.p8> --key-id <KEY_ID> --issuer <ISSUER_ID>`
+- Then `NOTARY_KEYCHAIN_PROFILE=markee-notary make notarize` produces a
+  notarized, stapled bundle.
+
+**CI:** `release.yml` (tag-triggered) imports the cert and notarizes
+automatically. It needs five repo secrets: `MACOS_CERT_P12` (base64 of the
+Developer ID `.p12`), `MACOS_CERT_PASSWORD`, `NOTARY_KEY_P8` (base64 of the API
+key `.p8`), `NOTARY_KEY_ID`, `NOTARY_ISSUER_ID`. `ci.yml` (push/PR) stays
+ad-hoc — signing secrets must never reach PR builds.
+
 ## Useful one-liners
 
 ```sh

diff --git a/Makefile b/Makefile
@@ -1,12 +1,14 @@
 APP_NAME := Markee
 APP_BUNDLE := $(APP_NAME).app
 BIN := .build/release/$(APP_NAME)
+PREVIEW_BIN := .build/release/MarkeeQuickLookPreview
+THUMBNAIL_BIN := .build/release/MarkeeQuickLookThumbnail
 CONFIG := release
 
 INSTALLED_BUNDLE := /Applications/$(APP_BUNDLE)
 VENDOR_SENTINEL := Resources/web/vendor/.fetched
 
-.PHONY: all build app run clean fetch-vendor install install-cli icon test test-swift test-js
+.PHONY: all build app run notarize clean fetch-vendor install install-cli icon test test-swift test-js
 
 all: app
 
@@ -31,12 +33,25 @@ app: $(VENDOR_SENTINEL) build icon
 	cp $(BIN) $(APP_BUNDLE)/Contents/MacOS/$(APP_NAME)
 	cp Resources/Info.plist $(APP_BUNDLE)/Contents/Info.plist
 	cp Resources/AppIcon.icns $(APP_BUNDLE)/Contents/Resources/AppIcon.icns
+	cp Resources/DocIcon.icns $(APP_BUNDLE)/Contents/Resources/DocIcon.icns
 	cp -R Resources/web $(APP_BUNDLE)/Contents/Resources/
 	cp -R Resources/cli $(APP_BUNDLE)/Contents/Resources/
 	cp LICENSE $(APP_BUNDLE)/Contents/Resources/LICENSE
 	cp THIRD-PARTY-NOTICES.md $(APP_BUNDLE)/Contents/Resources/THIRD-PARTY-NOTICES.md
-	# Ad-hoc codesign so WKWebView and TCC don't barf
-	codesign --force --deep --sign - $(APP_BUNDLE) 2>/dev/null || true
+	# Assemble the Quick Look extensions into Contents/PlugIns/
+	mkdir -p $(APP_BUNDLE)/Contents/PlugIns/QuickLookPreview.appex/Contents/MacOS
+	mkdir -p $(APP_BUNDLE)/Contents/PlugIns/QuickLookPreview.appex/Contents/Resources
+	cp $(PREVIEW_BIN) $(APP_BUNDLE)/Contents/PlugIns/QuickLookPreview.appex/Contents/MacOS/MarkeeQuickLookPreview
+	cp Resources/QuickLookPreview-Info.plist $(APP_BUNDLE)/Contents/PlugIns/QuickLookPreview.appex/Contents/Info.plist
+	cp -R Resources/web $(APP_BUNDLE)/Contents/PlugIns/QuickLookPreview.appex/Contents/Resources/
+	mkdir -p $(APP_BUNDLE)/Contents/PlugIns/QuickLookThumbnail.appex/Contents/MacOS
+	mkdir -p $(APP_BUNDLE)/Contents/PlugIns/QuickLookThumbnail.appex/Contents/Resources
+	cp $(THUMBNAIL_BIN) $(APP_BUNDLE)/Contents/PlugIns/QuickLookThumbnail.appex/Contents/MacOS/MarkeeQuickLookThumbnail
+	cp Resources/QuickLookThumbnail-Info.plist $(APP_BUNDLE)/Contents/PlugIns/QuickLookThumbnail.appex/Contents/Info.plist
+	cp -R Resources/web $(APP_BUNDLE)/Contents/PlugIns/QuickLookThumbnail.appex/Contents/Resources/
+	# Sign the bundle: Developer ID + Hardened Runtime when an identity is
+	# available, ad-hoc otherwise. See scripts/sign-app.sh.
+	./scripts/sign-app.sh $(APP_BUNDLE)
 	@echo "Built $(APP_BUNDLE)"
 	@if [ -L "$(INSTALLED_BUNDLE)" ] || [ -d "$(INSTALLED_BUNDLE)" ]; then \
 		echo "Syncing to $(INSTALLED_BUNDLE)..."; \
@@ -55,6 +70,9 @@ install: app
 run: app
 	open $(APP_BUNDLE)
 
+notarize: app
+	./scripts/notarize-app.sh $(APP_BUNDLE)
+
 install-cli: app
 	@if [ -w /usr/local/bin ]; then \
 		ln -sf "$$(pwd)/$(APP_BUNDLE)/Contents/Resources/cli/markee" /usr/local/bin/markee; \

diff --git a/Package.swift b/Package.swift
@@ -6,12 +6,34 @@ let package = Package(
     platforms: [.macOS(.v13)],
     products: [
         .executable(name: "Markee", targets: ["Markee"]),
+        .executable(name: "MarkeeQuickLookPreview", targets: ["MarkeeQuickLookPreview"]),
+        .executable(name: "MarkeeQuickLookThumbnail", targets: ["MarkeeQuickLookThumbnail"]),
     ],
     targets: [
+        .target(
+            name: "MarkeeKit",
+            path: "Sources/MarkeeKit"
+        ),
         .executableTarget(
             name: "Markee",
+            dependencies: ["MarkeeKit"],
             path: "Sources/Markee"
         ),
+        .executableTarget(
+            name: "MarkeeQuickLookPreview",
+            dependencies: ["MarkeeKit"],
+            path: "Sources/MarkeeQuickLookPreview"
+        ),
+        .executableTarget(
+            name: "MarkeeQuickLookThumbnail",
+            dependencies: ["MarkeeKit"],
+            path: "Sources/MarkeeQuickLookThumbnail"
+        ),
+        .testTarget(
+            name: "MarkeeKitTests",
+            dependencies: ["MarkeeKit"],
+            path: "Tests/MarkeeKitTests"
+        ),
         .testTarget(
             name: "MarkeeTests",
             dependencies: ["Markee"],