PromptReady

A clean Markdown export is only useful if the source survived the pipeline.

• Problem: modern pages can look complete in the browser while extraction sees an empty shell, the wrong content region, or structurally damaged technical material.
• Decision: keep a local offline result as the product baseline, give extraction/conversion one owner each, and let optional AI cleanup improve formatting only when it preserves source structure.
• Proof: the current pipeline uses Defuddle as the sole extractor, DOMPurify as the HTML safety boundary, Joplin Turndown as the invoked Markdown converter, deterministic fixtures/evals, and fallback to the offline result when AI cleanup fails its quality gate.

The product boundary stayed local-first

PromptReady captures the active page and turns articles, documentation, discussions, research sources, notes, and everyday prompt context into Markdown and structured JSON.

Core capture, cleanup, Markdown export, and JSON export run locally. Optional AI cleanup is BYOK through OpenRouter and starts from the finalized offline Markdown rather than raw page HTML.

The core rule has not changed: AI is allowed to clean the document; it is not allowed to become the extraction engine.

The extraction architecture did change

Earlier portfolio notes described a Readability-style extraction path. That is no longer the current implementation.

PromptReady now pins defuddle@0.19.1 and uses Defuddle as the sole content-extraction engine. Defuddle returns HTML. PromptReady deliberately keeps Defuddle’s Markdown output disabled so the active conversion path stays explicit:

settled captured document
  -> offscreen Defuddle extraction
  -> DOMPurify HTML boundary
  -> Joplin Turndown conversion
  -> one canonical Markdown finalizer
  -> cache / export / optional AI cleanup

Strategies can change Defuddle reply handling or output formatting. They do not switch to a second extractor.

Why one extractor matters

The older architecture accumulated fallback and cleanup logic because difficult pages kept exposing new failure modes. More branches made individual cases easier to patch and the system harder to reason about.

The current direction is stricter: give Defuddle one coherent document, preserve the browser-extension process boundaries, sanitize once, convert once, finalize once, and make the evaluation corpus the release authority.

That also makes failures easier to localize. If content disappears, the system can inspect whether the loss happened during capture, Defuddle extraction, sanitization, Turndown conversion, or finalization instead of hiding everything behind a generic quality score.

Plain Markdown is a reference, not a code path

I am also using the local plain-markdown artifact as a quality reference for difficult extraction cases.

The goal is semantic/output parity where it matters, not copying Plain Markdown’s implementation topology or minified bundle. PromptReady keeps its own offscreen architecture, pinned Defuddle runtime, DOMPurify boundary, Joplin Turndown conversion, recovery policy, citation metadata, and deterministic cache contract.

The parity-hardening program is still in progress. Phase 0 established the deterministic corpus and repaired several extraction contracts; the broader program has not been presented as complete.

That distinction belongs on the public page because “we are evaluating against a stronger reference” is not the same claim as “we reached parity.”

The eval corpus is the useful proof

The current Phase-0 authority covers deterministic cases for articles/head metadata, GitHub/code/table structure, Reddit and old-Reddit ordering, Discourse and Hacker News threads, liveblogs, complex tables, hostile markup, client-rendered documentation, and bounded provider recovery.

The release question is not “did the Markdown get longer?” It is whether required content, order, structure, URLs, and safety invariants survive consistently.

That is a much better target than a subjective cleanliness score.

Optional AI still has to earn acceptance

When BYOK AI cleanup is enabled, it receives the offline Markdown as source context. The result is checked against the local baseline before it is accepted.

If cleanup loses headings, technical tokens, code structure, or too much source material, PromptReady keeps the local result instead of shipping the prettier but weaker document.

This keeps the product useful without an API key and keeps AI failure from erasing the deterministic path.

Current boundaries

PromptReady is not a crawler, website mirror, hosted content store, provider marketplace, or layout-preserving renderer. Deep capture can help with long or lazy-loaded pages, but it does not make every site extractable.

The current hardening work is intentionally unfinished. Difficult social/app pages, extraction policy, and parity evidence still need to be earned by the corpus rather than claimed from a demo.

Related notes

• Why PromptReady needed an offline Markdown baseline first
• When local capture failed: empty shells, lazy pages, and fixture tests
• Why AI cleanup should not be the extraction engine

Links

• Repository
• Chrome Web Store