Proof Pack

Turn shipped work into client-ready proof — local-first, no backend, no telemetry.

---

Most good work dies in scattered screenshots, chat threads, folders, and terminal output — so the value you delivered is impossible to review, approve, or reuse. Proof Pack is a proof desk: a structured workspace that turns a finished piece of work into a single packet answering one question — what proof did this work create?

It's built for consultants, fractional operators, security/ops reviewers, and product builders who need to hand a client something credible, fast. Everything runs locally in the browser (or a desktop app); nothing leaves your machine unless you export it.

Features

• Structured proof model — every packet captures problem, work performed, evidence, impact, risks, and a concrete next ask, plus client, owner, type, status, date, and tags.
• Five starter templates — Client Ops, Security Fix, Marketing Proof, Personal System, and Product Work, each pre-filled with sensible prompts so a packet is useful in under a minute.
• Completion scoring — a live 0–100 score over seven field checks tells you how close a packet is to send-ready.
• Quality audit — severity-weighted findings (high / medium / low) flag vague problem statements, missing evidence, weak impact, and unspecific asks before a client sees them.
• Markdown brief generation — every packet renders to a clean, deterministic Markdown brief you can copy or download.
• Per-packet and whole-workspace export — download any packet as Markdown or JSON, or export the entire workspace as a single JSON file.
• Import with merge — pull packets back in from JSON; imports merge by id and survive malformed input via defensive normalization.
• Fast search — filter across titles, clients, owners, tags, status, evidence, and packet body as you type.
• Resilient local storage — versioned localStorage store that quarantines corrupt data instead of losing your work.
• Local-first by design — no backend, no account, no telemetry; packets stay in your browser profile.
• Cross-platform desktop app — an Electron shell with a hardened sandbox ships installers for macOS, Windows 11, and Linux.

Architecture

flowchart LR
    Work["Shipped work +<br/>scattered evidence"]

    subgraph UI["App.tsx — operator UI"]
        TPL["Template picker<br/>(5 packet types)"]
        EDIT["Packet editor<br/>problem → next ask"]
        REVIEW["Review panel<br/>score · audit · brief"]
    end

    subgraph CORE["src/lib/proof.ts — domain logic"]
        SCORE["completionScore"]
        AUDIT["qualityAudit"]
        MD["toMarkdown"]
    end

    subgraph STORE["src/lib/storage.ts — persistence"]
        NORM["normalizeStore<br/>(schema + quarantine)"]
        LS[("localStorage<br/>proof-pack:v1")]
    end

    Work --> TPL --> EDIT
    EDIT --> SCORE --> REVIEW
    EDIT --> AUDIT --> REVIEW
    EDIT --> MD --> REVIEW
    EDIT <--> NORM <--> LS

    REVIEW --> OUT1["Copy / download<br/>Markdown brief"]
    REVIEW --> OUT2["Per-packet JSON"]
    NORM --> OUT3["Whole-workspace<br/>JSON export"]
    IMPORT["Import JSON"] --> NORM

    OUT1 --> CLIENT["Client-ready proof"]
    OUT2 --> CLIENT
    OUT3 --> CLIENT

    SHELL["electron/main.cjs<br/>proofpack:// shell"] -. serves built app .-> UI

Loading

Getting started

Requires Node.js 20+ (CI runs on Node 24).

npm install
npm run dev

Then open the URL Vite prints, usually http://127.0.0.1:5173.

Production build:

npm run build      # tsc -b && vite build
npm run preview

Tests and checks:

npm test           # vitest unit tests (proof model + storage)
npm run e2e        # Playwright browser smoke test
npm run typecheck  # tsc -b

Desktop app:

npm run electron:dev   # run the desktop shell in development
npm run pack           # unpacked desktop build
npm run dist:linux     # AppImage + deb (build per-OS on a matching runner)

dist:win and dist:mac produce Windows (NSIS + portable) and macOS (dmg + zip) installers; the release workflow builds all three on native GitHub Actions runners and attaches them to a draft release.

Tech stack

• UI: React + TypeScript
• Build/dev: Vite
• Testing: Vitest, Testing Library, jsdom (unit) · Playwright (browser smoke)
• Desktop: Electron + electron-builder
• CI/CD: GitHub Actions (install → test → e2e → typecheck → build; matrix desktop release)

How it works

• Local-first storage. Packets persist to a versioned localStorage key (proof-pack:v1). There is no server, account, or telemetry — data only leaves the machine when you export a file or copy Markdown.
• Defensive persistence. On load and import, every record is run through schema normalization that coerces unknown shapes into valid packets and drops junk; unparseable storage is moved to proof-pack:v1:corrupt rather than discarded, so a bad write never wipes your library.
• Quality is part of the model, not an afterthought. The completion score and severity-weighted audit live in src/lib/proof.ts and run on every keystroke, nudging a packet toward something a client can actually trust.
• Deterministic exports. Markdown and JSON output are stable and side-effect free, so the same packet always produces the same artifact — friendly to diffing, archiving, and re-import.
• Hardened desktop shell. The Electron main process uses context isolation, a sandboxed renderer, and no Node integration, serving the built app over a custom privileged proofpack:// protocol with a path-traversal guard; external links open in the OS browser.

Proof Pack is intentionally not a secrets manager. Keep API keys, credentials, and regulated personal data out of packets — see SECURITY.md.

License

MIT © 2026 Reese