docs: revamp README as Perspective Map Explorer (v2)

[patcon]

Summary

The current README is minimal and developer-focused. We want a polished, user-facing README that communicates the project's value, features, and status clearly — using Perspective Map Explorer (v2) as the project name.

This is a v2 successor to the original prototype: https://github.com/patcon/polislike-opinion-map-painting

---

Desired README Structure

1. Title + one-liner tagline

• Name: Perspective Map Explorer (v2)
• Tagline: e.g. "A map-like interface for exploring opinion landscapes built from polis-like conversation data."
• Immediately below the tagline, call out two core design principles:
  • Mobile-first — designed primarily for touch/phone use
  • Google Maps-inspired UX — familiar pan/zoom/paint interactions borrowed from mapping apps

2. Hero screenshot (full-width)

• Use a picsum placeholder initially: https://picsum.photos/seed/polis-hero/1200/600
• Replace with a real screenshot once available

3. Key Features (as a checkbox list)

Implemented features shown as [x], planned/upcoming shown as [ ].

Suggested list (to be refined during implementation):

Implemented:

• Mobile-first, Google Maps-inspired UX (pan, zoom, paint on touch)
• Interactive 2D opinion map (D3-powered scatter plot of participants)
• Lasso/freehand painting tool to define participant groups
• Per-statement vote heatmap overlay (agree / disagree / pass)
• Metrics layer: vote count intensity, PCA dimensions, obs-column annotations
• Categorical annotation legend with Tableau 20 palette
• Import .h5ad (AnnData) files for full conversation datasets
• In-browser SQL queries via DuckDB-WASM (no server needed)
• Representative + distinguishing statements per painted group
• Multiple 2D embedding algorithms (UMAP, PaCMAP, LocalMAP) with live switching
• Keyboard shortcuts (← / → to cycle statements and annotations)

Planned:

• Continuous metric color legends
• Export / share painted group configurations
• Permalink / shareable URL for a specific view
• Direct Polis CSV / JSON import

4. Live Demo link

Point prominently to the deployed app, specifically the #perspective-explorer hash route. Something like:

Open Perspective Map Explorer →

5. Screenshot gallery (table with captioned headers)

A 2-column table with 3–4 smaller screenshots and short captions describing each view/feature.
Use picsum placeholders initially: https://picsum.photos/seed/polis-N/600/400 (N = 1, 2, 3, 4).

Suggested captions:

Screenshot	Caption
picsum seed polis-1	Vote heatmap overlay — see how each statement landed across the map
picsum seed polis-2	Painting groups — lasso participants into color-coded clusters
picsum seed polis-3	Metrics layer — visualize annotation columns from your dataset
picsum seed polis-4	Statement explorer — find representative and distinguishing statements per group

6. Data Format section (abbreviated)

Condense the existing h5ad table — keep it, but trim prose. Link out to the valency-anndata data model for full details.

7. Getting Started (brief)

npm install
npm run dev
# Then open http://localhost:5173/#perspective-explorer

Link to the demo Storybook for the no-install path.

8. Background / Prior Work

Brief mention that this is a redesign of the v1 prototype, with a link.

9. Parameter Explorer (passing mention, near the bottom)

One short paragraph noting there is a secondary Parameter Explorer (#parameter-explorer) for algorithm/pipeline comparison — framed as a developer curiosity that will eventually be migrated to a separate tool.

---

Notes

• Images should start as picsum placeholders and be replaced with real screenshots in a follow-up.
• The #perspective-explorer link should be the primary call-to-action — surface it early and prominently.
• The README tone should be accessible (not purely developer-facing) while still including the data format table for technical users.
• Follow Keep a Changelog conventions — update CHANGELOG.md in the same PR.