docs: PDF-first positioning sweep — the PDF is what you share

[gkanitz]

Context

Launch-readiness item (owner decision 2026-07-04). Recruiters receive PDFs;
HTML attachments are a known phishing vector and get flagged or quarantined
by corporate mail gateways. The docs currently position the HTML as the
thing you "share by email" — the README's automation example literally
attaches report.html. For a trust product this is a positioning bug.

New positioning, to be stated consistently everywhere:
the PDF is the deliverable you share; the HTML is the attested
interactive copy you host; the JSON is for tooling. Nothing is demoted or
deprecated — HTML remains emitted and attested (it is the render engine and
the hosted-view artifact).

Goal

Docs-only sweep making PDF the headline shared artifact in every
user-facing surface.

In scope

• README: intro copy leads with the attested PDF; the "Self-contained
  output … share by email" bullet is rewritten to the three-artifact
  positioning; the automated-reports email example attaches
  report/report.pdf (body copy updated); the distribution-options table
  and "Report output" table are reordered PDF-first with one-line "when to
  use which" descriptions.
• New short section (README, linked from setup guides): "Which file do I
  share?" — PDF → send to recruiters/attach to applications; HTML → host
  it (personal site, LinkedIn featured link) or open locally for the
  interactive view; JSON (when it lands) → tooling and the career merge.
  Include one sentence on why PDF for email (mail gateways distrust HTML
  attachments).
• docs/setup/github.md, docs/setup/gitlab.md,
  docs/employer-onepager.md, docs/index.html: same positioning, same
  order; verification examples show the PDF verify command first.
• Verify-page copy (docs/verify/index.html): file-type hints mention PDF
  first, HTML second. Copy only — no behavior change.

Out of scope

• Any code, template, workflow, or attestation change. The PDF-embeds-JSON
  feature (v0.3, tracked in roadmap: v0.3 'Proof that travels' + v0.4 'Deeper evidence' (tracking) #51). Removing or deprecating the HTML artifact.

Acceptance criteria

Success

1. git grep -i over README + docs finds no remaining instruction to
   email or attach the HTML file.
2. The automation example attaches report.pdf and its email body copy
   matches.
3. "Which file do I share?" section exists and is linked from both setup
   guides.
4. All artifact tables/lists order PDF → HTML → (JSON when present), with
   the when-to-use line each.
5. The diff touches only Markdown/HTML docs and verify-page copy — zero
   code, template, or workflow changes.
6. No "deprecated"/"legacy" language about the HTML artifact anywhere.

Failure — QA red flags (any one observed → reject the PR)

• Any surviving "attach/email the HTML" instruction.
• HTML described as deprecated, legacy, or second-class-verified.
• Scope creep into templates, render code, or CI.
• The phishing/mail-gateway rationale overclaimed (e.g. "Gmail blocks
  HTML") — keep it to "commonly flagged or quarantined by corporate mail
  gateways".

Parallel-work contract

• Territory: README, docs/setup/*.md, docs/employer-onepager.md,
  docs/index.html, docs/verify/index.html (copy only).
• Depends on: nothing — start immediately. Coordinate trivially with
  docs: self-run setup guide — attested reports from a personal repo, no org needed #56 (self-run guide should be written PDF-first from the start) and launch: dogfood demo — publish the maintainer's own attested report (HITL) #59
  (landing demo links both: PDF as "the document", HTML as "the interactive
  view").

Definition of done

Criteria green; docs render correctly; PR references this issue.