diff --git a/.superpowers/sdd/task-14-report.md b/.superpowers/sdd/task-14-report.md deleted file mode 100644 index 6ce37fa..0000000 --- a/.superpowers/sdd/task-14-report.md +++ /dev/null @@ -1,60 +0,0 @@ -# Task 14 Report — Floating Progress HUD (opt-in) - -**Branch:** `feat/agent-brief-tokens-tracker` -**Date:** 2026-07-01 - -## Summary - -Implemented an opt-in floating progress HUD for background parses. When **Settings → General → Floating progress HUD** is enabled, a second Tauri window (`progress-hud`, 280×90) appears during batches triggered from the global hotkey or Finder Quick Action (when ParseKit is already running). Default behavior is unchanged when the toggle is off. - -## Changes - -### Tauri - -- **`tauri.conf.json`** — Added `progress-hud` window: 280×90, undecorated, transparent, `alwaysOnTop`, `skipTaskbar`, hidden at launch. -- **`capabilities/default.json`** — Granted permissions to `progress-hud` window. -- **`macos_popover.rs`** — `configure_hud_window` / `ensure_hud_window_configured` for floating NSWindow level. -- **`lib.rs`** — `show_progress_hud` (position bottom-right, show) and `hide_progress_hud` commands; hide HUD on app setup. -- **`macos_open_files.rs`** — Queue supports `{ background: true }` to emit `background-parse` instead of `open-files`. -- **`open-with-parsekit.sh`** — When `showFloatingHud` is on and ParseKit is running, queues background parse via app instead of headless sidecar. - -### Frontend - -- **`ProgressHud.svelte`** — Compact HUD: file fraction, progress bar, success/fail counts; on completion shows `+N tokens saved` and summary; auto-dismiss after 5s; clickable failed count reveals error + File Support link. -- **`ProgressHudApp.svelte`** — HUD window entry; listens for `hud-sync` events. -- **`progressHud.ts`** — State types, helpers, `emitTo` sync, show/hide IPC wrappers. -- **`main.ts`** — Mounts `ProgressHudApp` when window label is `progress-hud`. -- **`App.svelte`** — `showFloatingHud` setting; shows/syncs HUD only for `isBackgroundBatch` (hotkey / background quick action); listens for `hud-open-file-support`. -- **`SettingsScreen.svelte`** — Toggle `showFloatingHud` (default false) in General tab. -- **`index.css`** — `.progress-hud-*` styles. -- **`locales/en.json`, `zh.json`, `es.json`** — HUD + settings strings. -- **`progressHud.test.ts`** — Unit tests for HUD progress helpers. - -### Build fix (pre-existing) - -- **`clipboard_convert.rs`** — Added `use tauri::Manager` so `cargo build` succeeds on this branch. - -## Settings storage - -Key: `showFloatingHud` in `settings.json` -Default: `false` - -## Verification - -```bash -npm run check # 0 errors -npm run test # 47/47 passed -cargo build # success -``` - -### Manual smoke (macOS) - -1. **Toggle off (default)** — Press ⌃⇧M with files selected: popover stays hidden, no HUD, completion notification only. -2. **Toggle on** — Enable **Floating progress HUD** in Settings → General. -3. Press ⌃⇧M — HUD appears bottom-right with progress; on finish shows `+N tokens saved` + summary; auto-hides after 5s. -4. Batch with errors — Click failed count in HUD; error reason shown; dependency errors link to File Support (opens main window). -5. Run Parse from popover UI — HUD does **not** appear (foreground batch unchanged). - -## Commit - -`feat(hud): opt-in floating progress panel for background parses` \ No newline at end of file diff --git a/assets/bg-image-parsekit.png b/assets/bg-image-parsekit.png new file mode 100644 index 0000000..5708514 Binary files /dev/null and b/assets/bg-image-parsekit.png differ diff --git a/assets/final-icon-parsekit.png b/assets/final-icon-parsekit.png new file mode 100644 index 0000000..e65d4e9 Binary files /dev/null and b/assets/final-icon-parsekit.png differ diff --git a/assets/final-parsekit-icon-removebg-preview.png b/assets/final-parsekit-icon-removebg-preview.png new file mode 100644 index 0000000..978fb26 Binary files /dev/null and b/assets/final-parsekit-icon-removebg-preview.png differ diff --git a/assets/final-parsekit-icon.png b/assets/final-parsekit-icon.png new file mode 100644 index 0000000..ea3fb32 Binary files /dev/null and b/assets/final-parsekit-icon.png differ diff --git a/assets/parsekit-dark-mode-icon.png b/assets/parsekit-dark-mode-icon.png new file mode 100644 index 0000000..446d6ba Binary files /dev/null and b/assets/parsekit-dark-mode-icon.png differ diff --git a/assets/parsekit-installation-page.png b/assets/parsekit-installation-page.png new file mode 100644 index 0000000..97a28e1 Binary files /dev/null and b/assets/parsekit-installation-page.png differ diff --git a/assets/parsekit-light-mode-icon.png b/assets/parsekit-light-mode-icon.png new file mode 100644 index 0000000..a33c722 Binary files /dev/null and b/assets/parsekit-light-mode-icon.png differ diff --git a/assets/update-parsedock-functionality.png b/assets/update-parsedock-functionality.png new file mode 100644 index 0000000..bc687f5 Binary files /dev/null and b/assets/update-parsedock-functionality.png differ diff --git a/docs/ParseKit-Adoption-Strategy.md b/docs/ParseKit-Adoption-Strategy.md new file mode 100644 index 0000000..1a2648a --- /dev/null +++ b/docs/ParseKit-Adoption-Strategy.md @@ -0,0 +1,561 @@ +# ParseKit: How to Increase Adoption & Reduce Friction + +**Date:** 2026-07-16 +**For:** Harsha Balakrishnan +**Product:** ParseKit — local macOS menu-bar app that turns PDFs, Office files, and images into AI-ready Markdown/text/JSON + +This note consolidates product research on: + +1. Why power users (including you) still skip ParseKit and paste into ChatGPT +2. What the codebase already ships for low-friction workflows +3. macOS integration opportunities +4. Competitive / adoption patterns +5. Ranked product wedges and a 90-day plan + +--- + +## 1. The real competitor + +ParseKit is **not** primarily competing with Marker, Docling, or LlamaParse on parse quality. + +It is competing with this habit: + +> **Select PDF → drop into ChatGPT / Claude / Gemini → ask.** + +That path wins because: + +| Reason | Detail | +|--------|--------| +| **Zero new mental model** | The file is an *attachment to a question*, not a “pipeline step” | +| **Zero install / config** | Browser or desktop chat is already open | +| **Good enough** | Short, text-heavy PDFs (roughly 1–20 pages of prose) work fine | +| **Brand gravity** | Users choose ChatGPT/Claude and inherit whatever parser is behind upload | +| **Persistence features** | Claude Projects, ChatGPT Projects, NotebookLM absorb “I need a corpus” for many people | + +### Strategy in one line + +> **Stop being a place users go. Become the invisible step between “I have a file” and “⌘V in the model.”** + +ParseKit only gets used when: + +- **Raw upload feels worse** (tokens, privacy, scans/tables, bulk, quotas), **or** +- Cleaning is **on the path the user already walks** (Finder right-click, hotkey, clipboard, Share sheet) + +--- + +## 2. Why you (as a power user) still skip it + +| Your gesture today | Friction if using ParseKit today | +|--------------------|----------------------------------| +| Drop PDF in ChatGPT | ~1 step | +| Open ParseKit → drop → run → find `.md` → copy → paste | ~4–6 steps | + +Unless the file is **scanned, multi-column, table-heavy, sensitive, or bulk**, ChatGPT wins. + +So either: + +- **A)** Make ParseKit ≤ **2 gestures** to paste-ready text, **or** +- **B)** Make the quality/token win **impossible to ignore on first run** + +Preferably both. + +**Core insight:** Friction is not mainly “conversion quality.” It is **context switches and gestures**. ChatGPT drag-drop is ~1 gesture. ParseKit must be **0–1 gestures to paste-ready Markdown**, or **strictly better text than native upload**. + +--- + +## 3. Top 8 friction moments (file → AI chat) + +| # | Moment | What user does today | Why ParseKit is skipped | +|---|--------|----------------------|-------------------------| +| 1 | **File already in Finder** | Right-click Open/Share/Quick Action, or drag to chat | Any step that opens a separate UI loses to drag-to-chat | +| 2 | **Need text *in* the chat box** | Upload *or* copy/paste | Upload is one gesture; convert→copy→paste is 2–3 | +| 3 | **Batch / multi-file context** | Multi-select upload or zip | Power users use Projects/folders, not a converter | +| 4 | **Browser / web PDF** | Preview → screenshot or Print to PDF → upload | Tool not in Share sheet or browser path | +| 5 | **Screenshot / image of text** | CleanShot / TextSniper / Live Text → paste | OCR competitors own “select → clipboard” | +| 6 | **Copy from Word/Pages/PDF** | Select all → paste (often messy RTF) | Auto-convert not trusted/obvious | +| 7 | **Repeatable automation** | Manual each time | No folder watch / default Open With habit | +| 8 | **Post-convert handoff** | Find `.md`, open, select all, paste | Missing “Convert & paste into frontmost app” | + +--- + +## 4. What ParseKit already ships (codebase) + +### Shipped low-friction surfaces + +| Surface | Behavior | +|---------|----------| +| **Menu bar tray** | Left-click toggles popover; right-click: Open, **Parse Clipboard File → Copy Markdown**, Quit | +| **Drag & drop** | Popover drop zone for files/folders | +| **Batch UI** | Input/output, format, OCR, Run Parse, progress, history, copy last file, open in Finder | +| **Launch at login** | Settings | +| **Floating progress HUD** | Default on; background batches | +| **Finder Quick Actions** | “Parse to Markdown with ParseKit” + “Replace Original” (Automator → `~/Library/Services/`) | +| **Global hotkey** | Default **⌃⇧M** — Finder selection → background parse, *or* clipboard file path → Markdown on clipboard | +| **Auto-convert on Copy** | Opt-in pasteboard watcher (default **off**) | +| **CLI** | Bundled `parsekit-cli`; convert/batch; agent skill docs | +| **Onboarding** | Install-to-Applications, Gatekeeper fix, pick output folder, first-batch checklist | +| **Updater** | GitHub Releases check + install | + +### Explicitly *not* built yet + +- Raycast extension (brand mention only) +- macOS Shortcuts / App Intents (README: planned later) +- Share Extension / Share sheet +- Native Services plugin beyond Automator workflows + +### Gaps vs marketing / discovery + +| Issue | Reality | +|-------|---------| +| INSTALL docs say Settings → Finder | UI is **Settings → General → Installation & advanced** | +| Onboarding | Does **not** teach hotkey, clipboard convert, Finder QA, auto-convert, CLI | +| Auto-convert on copy | Shipped but **off** and almost invisible | +| Clipboard-to-Markdown | Easy to miss (tray *right-click*, hotkey fallback) | +| `clipboardConvertHint` locale string | Written but **unused** in UI | +| CLI on PATH | Binary in bundle; DMG users may not have `parsekit` on PATH | +| PRODUCT.md | Stale vs current features (hotkey, QA, HUD, tokens, CLI) | + +### Underused powers (built, low discovery) + +1. **⌃⇧M** select → Markdown (or output folder) without opening the panel +2. **Auto-convert on Copy** +3. **Tray right-click → Parse Clipboard** +4. **Finder Quick Actions** + headless silent parse +5. **Replace Original** workflow +6. **CLI + agent skill** +7. **Floating HUD + background-parse** mental model +8. **Services menu** (same Automator workflows) + +### Highest-leverage product surface (do not rebuild) + +Double down on: + +``` +Finder selection ──┐ +Clipboard file ──┼── hotkey / tray / auto-copy / Quick Action +open-queue ──┘ │ + ▼ + sidecar parse + notify / HUD / pbcopy +``` + +That pipeline is largely **already built**. The gap is **defaults + discovery**, not engines. + +**Benchmark to own:** From file selected in Finder to Markdown in ChatGPT ≤ **2 keystrokes/clicks** (convert + paste), or **1** with Convert & Paste. + +--- + +## 5. Happy paths to own (three contracts) + +Design onboarding and marketing around these: + +| Contract | Gesture | Result | +|----------|---------|--------| +| **A. Finder** | Select file(s) → Quick Action **Copy as Markdown** | ⌘V in chat | +| **B. Keyboard** | ⌃⇧M on Finder selection *or* file on clipboard | Clipboard MD; optional auto-paste | +| **C. Spatial** | Drop on menu bar / Dock | Chip → clipboard | + +Everything else (file beside original, JSON for RAG, watch folders) is power-user mode. + +--- + +## 6. Ranked opportunities (impact × effort) + +### MUST-DO (high impact / medium or low effort) + +#### 1. Primary output = clipboard Markdown by default +- Every entry point (Quick Action, hotkey, tray, Open With) ends with: *Markdown on pasteboard + brief HUD “Ready to paste (⌘V)”* +- File write becomes secondary +- **Why:** Collapses convert→open→select→copy into convert→paste + +#### 2. Quick Action: “Copy as Markdown” (default recommendation) +- Keep convert-beside-original / replace +- Promote **Copy as Markdown** in onboarding and docs +- **Why:** Finder is where files live; right-click is already in path + +#### 3. Teach the 10-second habit in onboarding +- Today: install + output folder + first batch +- Add: **Select PDF → ⌃⇧M → ChatGPT → ⌘V** (GIF) +- **Why:** That habit *is* the product + +#### 4. Unbury what you built +- Move **Install Finder Quick Actions** to Settings page 1 or onboarding +- Show hotkey + “Parse clipboard” together +- Render unused `clipboardConvertHint` +- Optional: “Install CLI to PATH” in Settings + +#### 5. Token savings as first-run wow (“token receipt”) +Example first conversion: + +> This PDF: **28.4k → 11.1k tokens** (61% saved) · 3 tables recovered · never left your Mac + +- **Why:** Competitors are silent on cost; ChatGPT is silent on waste; this is your viral screenshot + +#### 6. Harden auto-convert-on-copy with trust UX +- Clear menu-bar state: On / Off / Smart (only PDF/Office/image UTIs) +- Never touch password managers’ concealed clipboard types +- Skip short strings; show what was converted +- **Why:** Feature exists; without trust it stays off + +#### 7. “Paste into frontmost app” / Convert & Paste +- After convert: optional auto-paste into ChatGPT web, Claude, Notes +- CleanShot/TextSniper energy +- Prefer clipboard write; Accessibility only if needed for auto-paste + +#### 8. Open With + document UTIs +- Register for PDF, DOCX, PPTX, XLSX, images +- Opening a file = convert + result HUD (clipboard) + +--- + +### SHOULD-DO (high impact / higher effort) + +#### 9. Result chip (upgrade the HUD) +- Preview snippet · Copy · Paste · Save `.md` · Open in Obsidian/VS Code · Re-run options +- Make HUD the default product surface, not a status toast + +#### 10. Raycast extension (optionally Alfred) +- Commands: Convert Selection / Convert Clipboard / Convert File +- Thin shell over existing convert core +- **Why:** ICP lives in Raycast + +#### 11. App Intents + Shortcuts catalog +- Convert File, Convert Folder, Convert Clipboard, Set Output Format +- Enables Action Button, Shortcuts automations, future Siri discovery + +#### 12. Share Extension: “ParseKit → Markdown” +- Appear in Share from Finder, Preview, Safari PDFs, Mail +- **Cost:** real Swift extension target + App Groups (not pure Tauri) + +#### 13. Quality wedge vs native upload (product demos) +- Multi-column PDF, scanned pages, complex tables → token-efficient MD/JSON +- Integrations deliver the product; quality is the *reason* not to drag raw PDF + +--- + +### LATER (nice / niche / high cost) + +| Item | Notes | +|------|--------| +| Watch folder (Hazel-lite) `~/ParseKit Inbox` | Great for RAG pipelines, not daily chat | +| Browser Share / Safari PDF | Partly covered by Share Extension | +| Finder Sync badges | High maintenance, low adoption | +| Control Center / widgets | After App Intents | +| Continuity Camera scan → MD | After OCR excellence | +| Direct “Send to ChatGPT/Claude” deep links | Fragile; prefer clipboard + paste | +| Apple Intelligence Writing Tools hooks | Wrong layer for document conversion | + +### Explicit non-priorities (for now) + +- Competing as a full Claude Code / folder-agent replacement +- Building a full clipboard manager (integrate with Paste/Raycast) +- Building chat-with-docs (AnythingLLM/ChatGPT own Q&A) +- App Store–only distribution if sandbox kills best power features + +--- + +## 7. Competitive landscape (short) + +### Where users actually drop files + +| Destination | Why it wins | +|-------------|-------------| +| **ChatGPT web/desktop** | Already open; habit; attach and go | +| **Claude (+ Projects)** | Long-doc reasoning; sticky project knowledge | +| **Gemini + NotebookLM** | Drive/Workspace gravity; multi-source notebooks | +| **Cursor (`@file`)** | Devs live in editor; MD/source wins; PDFs often converted offline | +| **Notion AI / enterprise** | File already in system of record | + +### Technical peers (parsers) + +| Product | Positioning | Adoption engine | +|---------|-------------|-----------------| +| **Marker** | High-fidelity PDF→MD | OSS + demos + CLI | +| **Docling (IBM)** | Multi-format → structured → MD/JSON | Brand + `pip` + privacy/air-gap story | +| **MarkItDown (Microsoft)** | Lightweight multi-format → MD | Extreme virality, one-liner CLI, VS Code right-click | +| **unstructured.io** | ETL for unstructured data | Free tier → paid platform + connectors | +| **LlamaParse** | Cloud agentic parse | Free credits + LlamaIndex ecosystem | +| **Mathpix Snip** | STEM OCR → LaTeX/MD | **Hotkey → clipboard** freemium habit | + +### Strategic read + +| Wins | How | +|------|-----| +| MarkItDown / Docling / Marker | *Developer discovery* (GitHub, pip, demos) | +| LlamaParse / Unstructured | *Builder production* (API credits, free tier) | +| Mathpix / Raycast / menu-bar AI | *Daily habit* (hotkey → clipboard) | +| ChatGPT / Claude / NotebookLM | *End-user Q&A* (no pipeline) | + +**ParseKit’s gap:** There is no dominant **consumer-grade, local-first, macOS-native “clean then paste”** product. Quality tools are Python CLIs; convenience tools are cloud chat; privacy tools are full RAG apps. + +**Wedge:** OS-native packaging of parser quality — **not another Python library, not another chat app.** + +### Adoption tactics that work + +| Tactic | Who does it well | +|--------|------------------| +| Generous free tier / free pages | LlamaParse, Unstructured | +| One-liner install | MarkItDown, Docling | +| GitHub + demo video | Marker, MarkItDown | +| Editor right-click | MarkItDown VS Code extension | +| Hotkey / Snip | Mathpix | +| Ecosystem SDK lock-in | LlamaIndex + LlamaParse | +| Desktop “download and run” | AnythingLLM | +| MCP / agent hooks | Emerging agent distribution | + +### “Install in 30 seconds” rank (non-dev → power user) + +1. DMG / App Store / Setapp +2. `brew install --cask parsekit` +3. Raycast extension +4. Services / Quick Actions / Share sheet +5. CLI `parsekit convert` +6. MCP server for Claude Desktop / Cursor + +--- + +## 8. When power users prefer local pre-processing + +| Reason | Detail | +|--------|--------| +| **Token / cost savings** | Layout noise, headers/footers, bad reading order inflate tokens; clean MD often cuts a large fraction and improves answers | +| **Privacy / compliance** | Contracts, health, finance, unreleased research — local first | +| **Hard docs** | Multi-column papers, tables, equations, scans — chat upload is inconsistent | +| **Bulk / batch** | Chat quotas break “clean 200 PDFs” | +| **Offline / air-gapped** | Real for some enterprises | +| **Better agent/RAG inputs** | Structured MD/JSON beats page dumps | + +### What makes preference *automatic* (not intentional) + +| Gesture | Automatic behavior | +|---------|-------------------| +| Select files / copy PDF | Hotkey → MD on clipboard + token estimate | +| Drop on menu bar / dock | Batch convert | +| Finder Quick Action | “Clean for AI” → `.md` or clipboard | +| Watch folder Inbox | Default-on folder action | +| Paste into chat | User pastes MD (habit after first token wow) | +| Raycast command | Fuzzy file → convert → copy | + +**Packaging principle:** Sell **clipboard + hotkey + folder**, not “document intelligence platform.” Quality is the engine; **latency to clipboard** is the product. + +--- + +## 9. Five ranked product wedges + +### Rank 1 — “Clean for AI” clipboard hotkey (Mathpix × MarkItDown for general docs) + +| | | +|--|--| +| **User job** | About to ask ChatGPT/Claude about this PDF; max quality per token in one shortcut | +| **Friction removed** | Raw upload token tax, weak tables, privacy anxiety | +| **GTM** | Product Hunt + demos (before/after tokens); Raycast; freemium daily snips | +| **MVP** | Menu bar; hotkey on selection or clipboard file/image → MD; token estimate; Copy/Save; no account | +| **Why it sticks** | Muscle memory; visible token save; last step before every AI paste | + +### Rank 2 — Finder “Clean for AI” + drop folder (batch inbox) + +| | | +|--|--| +| **User job** | Pile of PDFs → clean MD/JSON corpus for Projects / NotebookLM / Cursor / local RAG | +| **Friction removed** | Per-file upload limits, inconsistent extract, Python batch scripts | +| **GTM** | SEO + YouTube “100 PDFs to Claude Project”; research communities | +| **MVP** | Quick Action + optional `~/ParseKit/Inbox` watch; `Out/*.md`; progress; error report | +| **Why it sticks** | Folder habit + corpus investment (switching cost) | + +### Rank 3 — Cursor / VS Code / Claude Code “docs pack” + +| | | +|--|--| +| **User job** | Specs/RFCs/PDFs as first-class `@file` context | +| **Friction removed** | Broken PDF blobs; manual MarkItDown | +| **GTM** | Marketplace; brew CLI; MCP listing | +| **MVP** | CLI + thin extension; convert → MD next to source; optional `parsekit watch` | +| **Why it sticks** | Daily coding loop; team repos commit cleaned docs | + +### Rank 4 — Privacy pre-flight (B2B-leaning, still Mac-native) + +| | | +|--|--| +| **User job** | “AI help, but this file cannot leave the machine as a raw PDF” | +| **Friction removed** | Upload anxiety / policy | +| **GTM** | Privacy/security content; local LLM stacks | +| **MVP** | Hard local-only mode; optional redaction; sanitized MD for cloud chat; audit “never uploaded original” | +| **Why it sticks** | Documented compliance step; higher willingness to pay | + +### Rank 5 — Agent/MCP parse tool + +| | | +|--|--| +| **User job** | Agents call `parsekit` instead of stuffing raw PDFs into context | +| **Friction removed** | Every agent re-implements PDF parsing | +| **GTM** | MCP directories, Claude Desktop snippets, “local LlamaParse” content | +| **MVP** | Local MCP + stable JSON schema + CLI exit codes | +| **Why it sticks** | Platform gravity; treat as Phase 2 on top of Rank 1–2 | + +### Ranked summary + +| Rank | Wedge | Frequency | Differentiation | +|:----:|-------|:---------:|-----------------| +| 1 | Clipboard hotkey “Clean for AI” | Daily | OS habit + token UI | +| 2 | Finder + drop-folder batch | Weekly | Default-on automation | +| 3 | Editor/CLI docs pack | Daily (dev) | Agent-ready MD in repo | +| 4 | Privacy pre-flight | Event-driven | Trust / compliance | +| 5 | MCP/agent tool | High leverage | Infrastructure | + +--- + +## 10. macOS integration map + +### In-path (highest leverage) + +| Integration | Intercepts | Notes for Tauri | +|-------------|------------|-----------------| +| **Share Extension** | Finder, Preview, Safari, Mail | Needs **native Swift** extension + App Groups | +| **Services** | Right-click Services | Low effort if Quick Actions already work | +| **Quick Actions** *(you have)* | Finder toolbar / right-click | Make **Copy as Markdown** primary | +| **Open With + UTIs** | Double-click / Open With | Converter destination | +| **App Intents / Shortcuts** | Shortcuts, Siri, Spotlight, Action Button | Swift bridge; multiplies surfaces | +| **Clipboard path** *(you have)* | After Copy | Privacy-sensitive | +| **Global hotkey + HUD** *(you have)* | Keyboard-first | Optimize Finder selection + clipboard file | +| **Drag to Dock / menu bar** | Spatial | Dock drop underused | + +### Patterns to steal from successful Mac utilities + +| App | Pattern | Steal for ParseKit | +|-----|---------|-------------------| +| **CleanShot** | Capture → floating result → auto clipboard | Result chip after convert | +| **TextSniper** | Hotkey → region → text on clipboard | Convert success = clipboard | +| **Paste / Raycast clipboard** | Live on the paste gesture | Last conversion always one paste away | +| **Raycast** | Keyboard, extensions, no app switch | Official extension | +| **Hazel** | Folder rules, zero UI | Optional watch folders | +| **Mathpix** | Hotkey → clipboard freemium | Daily habit model | +| **Obsidian** | Vault as destination | Optional “save to vault / daily note” | + +### Risks + +| Risk | Mitigation | +|------|------------| +| **Clipboard privacy / trust** | Opt-in auto-convert; UTI filters; visible “listening” indicator; prefer user-triggered convert | +| **Concealed clipboard types** | Never convert password-manager secrets (`org.nspasteboard.ConcealedType`) | +| **App Store sandbox** | Dual channel: notarized direct for power features; narrower App Store build if needed | +| **TCC / Accessibility** | Prefer pasteboard write + user paste over synthetic paste | +| **Tauri + extensions** | Budget thin Swift “Mac Integration” target for Share / App Intents | +| **Value proposition failure** | Lead with scanned PDFs, tables, tokens, privacy — integrations are delivery, not the wedge | +| **Drag-to-chat habit** | Don’t fight upload for every binary; win **paste-text** + **local/RAG/privacy** workflows | + +--- + +## 11. Positioning & packaging + +### Positioning line + +> **Local PDF cleaning so AI sees structure, not sludge — without sending the file anywhere first.** + +Not: “Another document converter.” +Not: “Chat with your PDFs.” + +### Landing / README proof points + +1. **Token receipt** before/after +2. **Finder → paste** GIF (≤2s loop) +3. **Privacy badge** (never uploaded) +4. **Hard docs** (scanned / multi-column / tables) where chat upload fails + +### Cross-cutting packaging + +1. **Hero metric on first run:** token delta + tables recovered +2. **Dual install:** Menu bar app (wedges 1–2, 4) + brew CLI/MCP (3, 5); same engine +3. **Free tier that creates habit:** N pages/day free; Pro unlocks OCR/scans, large batch, JSON schema +4. **Do not build chat** — own the 3 seconds before paste/upload +5. **Default outputs by destination:** + - Claude/ChatGPT paste → compact MD + - Projects / NotebookLM → multi-file MD + - Cursor → `docs/parsed/*.md` + - RAG → JSON chunks +6. **Viral loop:** Shareable before/after “token receipt” image (stats only, not document content) + +### Competitive gaps ParseKit can own + +| Gap | Incumbents leave open | +|-----|----------------------| +| Consumer Mac UX on Docling/Marker-class quality | OSS stays in terminal | +| Token-savings as product surface | MarkItDown is silent on cost | +| Pre-Claude/ChatGPT step, not competing chat | AnythingLLM is full app (overkill) | +| Batch + privacy without Python | Cloud parsers want your pages | +| Hotkey → clipboard for *general* docs | Mathpix owns equations, not contracts | + +--- + +## 12. 90-day execution plan + +| Phase | Ship | +|-------|------| +| **Weeks 1–2** | Default path = clipboard MD + HUD “Ready to paste”; Quick Action **Copy as Markdown**; onboarding GIF (Finder → hotkey/QA → ChatGPT); unbury Finder QA install | +| **Weeks 3–4** | Token receipt UI; Convert & Paste (frontmost); Open With UTIs; auto-convert trust modes (On/Off/Smart) | +| **Month 2** | Result chip (Copy / Paste / Save / format); Raycast extension; CLI PATH install in Settings | +| **Month 3** | Share Extension (Swift); App Intents; polish Dock drop; optional watch folder for RAG users | + +### Leverage order (build on existing code first) + +1. Discovery of **hotkey + clipboard path** +2. Promote **Finder Quick Actions** to first-class +3. Optional **install CLI to PATH** in Settings +4. Improve **auto-convert** trust (keep opt-in) +5. **Only later:** Shortcuts / App Intents / Raycast / Share as thin shells over the same convert core + +### Avoid rebuilding + +- New tray UI paradigms for their own sake +- Share Extension before clipboard-default path is productized +- Parallel convert engines for “integrations” +- Full chat-with-docs product + +--- + +## 13. Concrete “next build” (highest ROI) + +If shipping only one product slice next: + +### “Copy as Markdown” + habit + token receipt + +1. **Finder Quick Action:** Copy as Markdown (clipboard primary) +2. **Onboarding step:** Select PDF → ⌃⇧M → paste in ChatGPT (GIF) +3. **First convert UI:** Token before/after + “Ready to paste” +4. **Settings:** Finder QA install on page 1; hotkey + clipboard hints visible + +**No new platforms required.** Uses engines already in the repo. + +--- + +## 14. Bottom line + +| Truth | Implication | +|-------|-------------| +| Users will keep dropping files into ChatGPT/Claude/NotebookLM/Cursor | You cannot win “open PDF and ask” as the primary job | +| Local parsers win *builders*; chat wins *end users* | ParseKit must be **OS habit**, not a library or a chat app | +| You already have tray + QA + hotkey + clipboard + HUD + CLI | Adoption moves when **defaults and discovery** match that power | +| Power users skip intentional pre-processing | Preference becomes sticky when token/privacy/quality appear **without an extra deliberate workflow** | + +**ParseKit should not ask users to “choose a better parser.”** +It should make cleaning the **default gesture** on macOS: + +1. Hotkey → clipboard (daily chat) +2. Folder → batch corpus (research/RAG) +3. Then editor/MCP (developers/agents) +4. Paid privacy workflows (sensitive docs) + +--- + +## 15. Appendix: three research tracks used + +This document synthesizes: + +1. **macOS friction & integration research** — Share Extension, Services, Quick Actions, App Intents, clipboard privacy, patterns from CleanShot/TextSniper/Raycast/Hazel +2. **Competitive & GTM research** — ChatGPT/Claude/NotebookLM/Cursor habits; Marker/Docling/MarkItDown/LlamaParse/Mathpix; adoption tactics +3. **ParseKit codebase exploration** — What is shipped vs buried vs not built (tray, hotkey, clipboard, Finder QA, CLI, onboarding) + +Project path: `` +Repo: `https://github.com/harshabala/PareseKit` + +--- + +*End of note — for review and prioritization.* diff --git a/docs/legacy-root-docs/83447.png b/docs/legacy-root-docs/83447.png new file mode 100644 index 0000000..2373de4 Binary files /dev/null and b/docs/legacy-root-docs/83447.png differ diff --git a/docs/legacy-root-docs/ParseKit-TODO.md b/docs/legacy-root-docs/ParseKit-TODO.md new file mode 100644 index 0000000..ab4e882 --- /dev/null +++ b/docs/legacy-root-docs/ParseKit-TODO.md @@ -0,0 +1,67 @@ +# ParseKit — Remaining Tasks + +_Last updated 2026-06-16. Working copy: `~/Projects/ParseKit` (local, not iCloud-synced)._ +_Repo: https://github.com/harshabala/parsekit (public) · current branch `master` · HEAD `82f5d70`._ + +--- + +## 🔴 Do next (uncommitted work in the tree) + +_All clear — tree is clean and pushed._ + +- [x] **Visually verify the UI redesign** — verified via production build artifacts: + - Instrument Serif + JetBrains Mono bundled in `dist/assets/*.woff2` and referenced in built CSS + - CSP-safe: fonts are local woff2; grain texture uses inline `data:image/svg+xml` under `style-src 'unsafe-inline'` + - Progress view: 2px ink-rule bar + mono fraction (`progress-bar` / `progress-fraction` in `src/index.css`) + - `npm test` (18/18), `npm run build`, `npm run check` (0 errors) — all pass + - _Optional manual pass:_ `cd ~/Projects/ParseKit && npm run tauri:dev` to eyeball the live popover +- [x] **Commit the redesign** — `82f5d70` on `master`: fonts, `index.css`, `App.svelte`, `NOTICE.md`, path hardening +- [x] **Push** — `origin/master` is at `82f5d70` + +## 🟠 Before cutting a public release + +- [ ] **Cut release** when ready: `npm run publish:macos` + → publishes to `harshabala/parsekit` and writes a valid updater manifest. +- [x] Note: existing **0.2.2 installs** point at the old `parsedock` updater URL; + GitHub's rename redirect covers them, so updates still resolve. +- [x] **Security hardening** — `validate_user_path()` guards `open_in_finder` and + `save_error_report` reveal-before-open. Paths must canonicalize to an existing location. +- [x] **Tidy `.gitignore`** — removed stale `com.parsedock.app` guards; bundle id is `com.harshabala.parsekit`. + +## 🟡 Repo / git housekeeping + +- [x] **Delete the merged local branch**: `chore/publish-readiness` deleted +- [x] **Recover the unpushed commit** `775f981` from the OLD iCloud copy. + Same message as GitHub's `7eecd42`; iCloud copy was a parallel history missing + `45ec83f` publish-readiness. No unique work — safe to ignore. +- [x] **Remove the old iCloud copy**: `~/Documents/Projects/ParseKit` removed + +## 🟢 iCloud cleanup (lower priority — ParseKit itself is now safe) + +- [ ] `~/Documents/Projects` still has **~278 evicted source files** across your + other vibe-coded projects. The wedged `bird` daemon was fixed by the reboot, + so downloads should now complete. To force-download a project: + `brctl download ""` +- [ ] After a project is fully downloaded, **lock it out of iCloud** like ParseKit: + `xattr -w "com.apple.fileprovider.ignore#P" 1 ""` + (Only AFTER all files are local — the xattr halts in-flight downloads.) +- [ ] Or just **move the projects you actively work on** into `~/Projects` + (home folder = not iCloud-synced) like we did for ParseKit. + +--- + +## ✅ Done (reference) + +- Fixed wedged iCloud `bird` daemon (reboot) — ParseKit files materialized. +- Re-cloned ParseKit clean from GitHub into `~/Projects/ParseKit` (iCloud-free). +- Security + publish-readiness review (no secrets in code or git history). +- Removed accidentally-committed `.claude/` worktree (~140 files) + gitignored it. +- Renamed `parsedock` → `parsekit` across updater endpoint, release scripts, + About link, README, sidecar package; pointed git remote at new URL. +- Added a Content Security Policy (`tauri.conf.json`). +- Code review on the publish-readiness commit: clean, no blockers. +- Renamed the GitHub repo `parsedock` → `parsekit` and pushed `master`. +- Designed + ported the "Bone White, Pressed" UI redesign (verified `vite build`). +- Preview: `~/Projects/ParseKit/design/popover-redesign.preview.html` +- **2026-06-16 session:** committed UI redesign (`82f5d70`), path validation hardening, + `.gitignore` cleanup, pushed to GitHub, deleted `chore/publish-readiness`, removed iCloud copy. \ No newline at end of file diff --git a/docs/parsekit-errors-2026-06-05T17-22-28.md b/docs/parsekit-errors-2026-06-05T17-22-28.md new file mode 100644 index 0000000..d9121be --- /dev/null +++ b/docs/parsekit-errors-2026-06-05T17-22-28.md @@ -0,0 +1,12 @@ +# ParseKit error report + +- Date: 2026-06-05T17:22:28.041Z +- ParseKit version: 0.2.2 +- Output format: JSON +- Files: 7 · Parsed: 6 · Errors: 1 +- Output folder: + +## Failed files + +1. 1 - HouseOfLeaves.pdf + PDF error: invalid PDF format diff --git a/docs/parsekit-task-list-plan.md b/docs/parsekit-task-list-plan.md new file mode 100644 index 0000000..03a3615 --- /dev/null +++ b/docs/parsekit-task-list-plan.md @@ -0,0 +1,232 @@ +# parsekit — Agent task list & implementation plan + +> **Give this entire file to one agent (or one session). Work only on this product until ship criteria are met.** + +| Field | Value | +|-------|--------| +| **Product** | parsekit | +| **Priority** | P0 — primary showcase | +| **GitHub** | https://github.com/harshabala/parsekit | +| **Local clone (preferred)** | `~/Documents/Projects/parsekit` | +| **If missing, clone to** | `~/Documents/Projects/parsekit` via `gh repo clone harshabala/parsekit` | +| **Default branch** | `master` | +| **Work branch** | `feat/flow-metrics-2026-07` (create from latest default if needed) | +| **Stack** | Mac menu-bar document converter (Tauri/node/Rust hybrid — verify from package.json) | +| **Task IDs** | PK-1, PK-2, PK-3, PK-4, PK-5 | +| **Fable plan status** | Fable plan FAILED (session limit) — full agent plan reconstructed below from task list | +| **Work already done** | None for this initiative. Local clone may not exist — clone if needed. | + +## Agent instructions (start here) + +1. **Read this whole file** before editing. +2. **cd** to the local clone path above. If the path does not exist, clone the GitHub repo there. +3. `git fetch origin && git checkout -B feat/flow-metrics-2026-07 origin/master` (or continue existing feature branch if present). +4. Implement tasks in the **recommended commit sequence** at the bottom of the plan section. +5. After each commit: run the **verify commands** listed below. +6. Create/update **`docs/TASKS.md`** with every task ID and status. +7. Complete the **README dual-section rewrite**. +8. Run design + code + security self-review on the diff; fix critical/high issues. +9. Push branch and open a PR against `master`. Do **not** force-push. Do **not** merge unless the user asked for auto-merge. +10. Do **not** touch other portfolio repos in this session. + +## What “done” means for this product + +All task IDs listed above are implemented **or** explicitly documented as infeasible with a narrow alternative. Metrics are local-first, activation is a named constant, scoreboard is user-visible with method + privacy copy, README is dual-section, `docs/TASKS.md` is accurate, tests/build green, PR open. + + +## Global constraints (apply to ALL work) + +Source: `` and ``. + +1. **Local-first metrics** — counters/estimates on device or extension storage only. Nothing leaves unless user explicitly exports or opts in. **No cloud analytics in v1.** +2. **One activation event** — named constant in code (e.g. `ACTIVATION_EVENT = '...'`). +3. **User-visible scoreboard** on the natural success screen (ParseKit token-savings pattern), with **method + caveat microcopy**. Honest estimates; never fake precision. +4. **Privacy line on every stats surface:** e.g. *"Stored only on this device. Never uploaded."* (wording may adapt slightly per product). +5. **Zero-AI default** where relevant — core loop works without API keys; AI is optional upgrade. +6. **README rewrite required** in every repo (see below). +7. **`docs/TASKS.md`** committed checklist; update checkboxes as you finish task IDs. +8. **Ship path:** branch `feat/flow-metrics-2026-07` → push → open PR → (if user requested auto-merge and reviews pass) squash-merge to default branch and delete feature branch. + +### README overhaul (mandatory for every product) + +Rewrite `README.md` with **two top sections**: + +#### Start here (novice) +Plain everyday words, zero jargon: +- What it is +- What problems it solves +- Step-by-step install and first use +- Edge cases and how to still use it when you hit them + +#### For technical users +- Mermaid architecture diagram (GitHub-native render) +- How it works under the hood +- Metrics / activation definition +- Dev install, test commands, storage/privacy notes + +### Ship checklist per repo + +- [ ] All task IDs for this product implemented or honestly deferred with reason in PR +- [ ] `docs/TASKS.md` updated (checkboxes match reality) +- [ ] README novice + technical sections done +- [ ] Build/tests pass (commands in this file) +- [ ] Design pass (hierarchy, motion, empty states, reduced-motion) +- [ ] Code pass (edge cases, no regressions) +- [ ] Security pass (secrets, XSS, storage, permissions, no accidental egress) +- [ ] Branch pushed; PR opened with body mapping commits → task IDs → metrics +- [ ] Merge only if user wants auto-merge **or** explicitly asks + +### Related docs (read if needed) + +| File | Why | +|------|-----| +| `` | Original product task specs + metrics definitions | +| `` | Why these metrics matter (senior PM framing) | +| `` | Multi-repo orchestration notes | +| `` | What Fable completed (mostly plans only) | + + + +## Work already completed + +None for flow-metrics. Product may already have per-file token estimates — preserve and elevate them. + +If `~/Documents/Projects/parsekit` is missing: +```bash +gh repo clone harshabala/parsekit ~/Documents/Projects/parsekit +``` + +## Original product task spec (100% of P0 parsekit section) + +# P0 — parsekit + +## Product in one line + +Offline Mac menu-bar app: PDFs/Office/scans → clean Markdown so more real content fits AI context and nothing leaves the machine. + +## Current gap (from analysis) + +Strong ROI story in README; need the **first-run path** and **return path** to revolve around the outcome number (tokens/docs), and activation to be explicit. + +--- + +### Task PK-1 — Make first successful convert the hero of onboarding + +| Field | Detail | +|-------|--------| +| **Flow change** | First launch: skip multi-step theory. One screen: drop **one** file (or “Try sample PDF”) → convert → land on result with token estimate + “Open folder” + “Convert more.” | +| **Where** | Onboarding / first-run wizard → result panel | +| **How it helps** | Activation becomes inevitable in <2 minutes. Matches Lenny: aha = first successful convert. | +| **Acceptance** | New user reaches token-savings result without opening Settings. | + +### Task PK-2 — Elevate token savings as the session summary (not only per-file) + +| Field | Detail | +|-------|--------| +| **Flow change** | After each job **and** in menu-bar popup: show **Today** and **All time** — files converted, estimated tokens saved, optional “≈ N more messages of context.” Keep per-file estimate on the detail row (already exist). | +| **Where** | Job complete UI, menu-bar status, optional lightweight “Stats” in settings | +| **How it helps** | Retention lever: user opens app to *see cumulative value*, not only to convert. Portfolio: clear outcome metric. | +| **Metric: Activation** | `activated = first job with status success AND tokens_estimate computed` | +| **Metric: Engagement** | `files_converted` per day/week (local counter) | +| **Metric: Outcome (user-visible)** | `tokens_saved_estimate_total` — same method as per-file, summed | +| **Metric: Retention (user-visible proxy)** | “Last convert: X days ago” + streak or “files this week” | +| **Privacy** | Counters in local app storage only. No file contents, paths, or names in aggregate stats (optional: store hashed path for dedupe — prefer **no paths**). | +| **User understanding** | Tooltip: *“Estimate = tokens in raw extract vs cleaned Markdown (≈4 chars/token). Not exact — different models tokenize differently.”* Same honesty as current section. | +| **Acceptance** | After 3 files, All-time tokens > 0 and matches sum of per-file estimates within rounding. | + +### Task PK-3 — Failure path that still teaches value + +| Field | Detail | +|-------|--------| +| **Flow change** | On failed/partial parse: show what *did* extract + “tokens recovered so far” + one clear next action (retry OCR / different format / open logs). | +| **How it helps** | Senior PM nuance: edge cases. Reduces drop-off after first bad file. | +| **Metric** | `job_success_rate` (local, last 20 jobs) shown as “18/20 succeeded” | +| **Privacy** | Error codes only, not document text. | +| **Acceptance** | Failed job never dead-ends with empty state. | + +### Task PK-4 — Optional “where did you use this?” (qualitative, local) + +| Field | Detail | +|-------|--------| +| **Flow change** | Soft prompt after first convert: *Used this in…* Claude / ChatGPT / Gemini / Obsidian / Other / Skip. Store choice locally; never required. | +| **How it helps** | Portfolio + product learning without cloud analytics. | +| **Metric** | Distribution of destinations (local only; exportable later as anonymous summary if you choose). | +| **Privacy** | Explicit; skippable; no network. | +| **Acceptance** | Skip is one click; no nag after dismiss. | + +### Task PK-5 — Privacy strip on every stats surface + +| Field | Detail | +|-------|--------| +| **Flow change** | Fixed microcopy under stats: *“All estimates stay on your Mac. ParseKit never uploads your documents.”* | +| **How it helps** | Reinforces category advantage; reduces “is this phoning home?” anxiety. | +| **Acceptance** | Visible on result + Stats. | + +**ParseKit north star (for you):** weekly files successfully converted among users who activated. +**User-facing north star:** tokens saved (all time) + files this week. + +--- + +## Implementation plan for agent + + +## Implementation plan (agent-authored from product task list — Fable never produced a plan) + +### Repo orientation +- Mac menu-bar app: likely Tauri + web UI (`src/`, `src-tauri/`, packaging). +- Confirm structure with `ls` and `package.json` / `src-tauri/Cargo.toml`. +- Token estimate UI may already exist — **extend** it; do not invent a second system. + +### Foundation +1. Named constant e.g. `ACTIVATION_EVENT = 'first_successful_convert_with_token_estimate'` in a small shared metrics module (TS or Rust side as fits). +2. Local store for: `filesConvertedTotal`, `tokensSavedEstimateTotal`, `lastConvertAt`, `jobSuccessLast20[]` or counts, optional destination enum counters. +3. Privacy: no file paths/names in aggregate stats; no upload of document content for metrics. + +### PK-1 — First-run hero convert +- Onboarding: drop one file OR “Try sample” → convert → land on result with token estimate + Open folder + Convert more. +- Files: onboarding UI components, sample asset if needed. +- Acceptance: new user reaches savings result without opening Settings. + +### PK-2 — Today + All-time token summary +- After each job and in menu-bar popup: Today / All-time files + tokens saved; optional “≈ N more messages of context.” +- Method tooltip: same honesty as existing per-file estimate (chars/token caveat). +- Privacy strip under stats. + +### PK-3 — Failure path +- Partial extract + tokens recovered so far + next action; show success rate last 20 jobs. + +### PK-4 — Optional destination prompt +- Soft prompt after first convert; skippable; local only. + +### PK-5 — Privacy strip +- Fixed microcopy on every stats surface. + +### README +- Novice: install DMG, convert one PDF, understand tokens saved. +- Technical: mermaid pipeline PDF→engine→md; offline architecture. + +### Verify +```bash +# Use repo’s real scripts, e.g.: +npm test # or pnpm / cargo test as present +# Manual: run app, convert sample, confirm counters +``` + +### Commit sequence +1. feat(metrics): activation constant + local counters +2. feat(onboarding): first successful convert hero (PK-1) +3. feat(stats): today/all-time token scoreboard (PK-2) +4. feat(convert): failure path + success rate (PK-3) +5. feat(onboarding): optional destination prompt (PK-4) +6. docs: privacy strips + README dual sections + docs/TASKS.md + + +## Agent completion checklist + +- [ ] Clone/path verified; branch created +- [ ] PK-1 … PK-5 +- [ ] README dual sections +- [ ] docs/TASKS.md +- [ ] Build/tests +- [ ] Security: offline-first, no doc upload for metrics +- [ ] PR opened against master