learnharness/docs/release-0.3.md

First Release (0.3.0) — polish list + lock question

Historical planning notes (2026-10-06), not the current release checklist. Several items below have since shipped, including signing/notarization and automatic updates. See Desktop builds and releases for the current build, verification, and release procedure.

Started 2026-10-06, owner brain-dump round. Priority 1 — everything else (assessment levels → docs/vision-assessment.md) comes after. Items are captured as spoken; design decisions inside them are unruled unless marked.

Polish items (owner list, 2026-10-06)

1. Graph rendering toggle — separate from the extraction pipeline. Today's graph on/off switch toggles extraction. Wanted: two switches — one for the pipeline (named for what it does), one for rendering ("graph on/off" = the graph view renders or not). Data, chains model, extraction all keep working with rendering off.
   • Open: what is the home view when graph rendering is off? It must keep the import-notes button, the chains-view button, and the graph pipeline cost readout. Candidate raised and not rejected: the chains view (the chain table is already a complete non-graph presentation of propositions + chains). A "giant DAG" was raised and rejected. Unruled.
2. Keyboard navigation for questions — arrow buttons (next/previous question) are currently click-only; make them real keybinds, with VIM bindings (j/k or similar) as the goal. Maybe rebindable, maybe not — unruled.
3. Session naming. First-message-as-name is not clean (the first message is always long). Owner dislikes LLM-generated names. A naming popup after first send was considered — possibly annoying; unruled. (Fact: the top-bar title is already click-to-rename; whatever lands should agree with it.)
4. Export sessions as markdown — likely a right-click action on a session in the sidebar. (Fact: core/session-markdown.ts already renders whole sessions to markdown for extraction — the serialization exists.)
5. Export the reasoning chains / graph — format unruled (JSON is the obvious candidate: serve the graph snapshot). Placement unruled.
6. Graph default settings refinement — current defaults not ideal; minor.
7. Compaction summary dialog — covers the entire screen and doesn't look good; Esc prompts a dismiss question instead of just closing. Law stated: Esc always acts on the current element on screen.
8. General keyboard audit — everything must work from the keyboard; some minor things don't. Examples to be enumerated in the round.

What does "released" change in development? (the lock question)

Position agreed 2026-10-06: releasing means on-disk user data acquires compatibility obligations — after 0.3.0, persistent-schema changes are migrations with tolerant reads, not free edits plus wipe-your-dev-data. Nothing is frozen forever; the discipline changes.

Persistent surfaces (the obligation set):

• data/chats/*.json — ChatRecord: messages (pi-ai wire shapes: thinking blocks, toolCalls, usage), turns, kind, graphContext. The deepest lock — and coupled to the pi-ai library's serialization (a pi-ai bump becomes a migration event post-release).
• data/graph/ — nodes.jsonl, chains.jsonl, coverage.jsonl, sources.json, sessions.jsonl (append-only ledgers), positions.json, render-settings.json.
• data/settings.json (models, toggles, compaction…), auth.json (BYOK keys).
• Client localStorage (camera, filters, zoom, kind filter).
• data/jobs/ — treat as scratch/transient, no obligation.

Known gaps to close before release (proposals, unruled):

• No schemaVersion anywhere. Cheap now, load-bearing later: stamp ChatRecord, settings, and the ledgers with a version at write time; readers default missing → current. This is what makes later migrations painless.
• Pin pi-ai/pi-agent-core exact versions so record shapes move only deliberately.
• Release engineering outside code: signing/notarization await Apple Developer enrollment (DMG is unsigned today); no auto-updater (manual download acceptable for 0.3.0 if stated); packaged-app data location already correct (LH_DATA_DIR → userData).