vision docs: practice module, side chats, branching, parked persistent agent (2026-09-27 ideation round)

Four living documents capturing the post-explain ideation:

- vision-practice.md (priority 1): exams over chosen node sets; assessment
  record model (extractor observation = data point zero, practice appends,
  labels-for-extractor/numbers-for-everyone-else, aggregation TBD-Bayesian);
  problem-engineer agent flow with self-verifiable coverage metadata and
  commit-before-pose grading via a dedicated write-seam tool; formats
  configurable, theory pending from owner.
- vision-side-chat.md (priority 2): per-block hover-revealed mini threads,
  invisible to the teaching record; v1 = block-only context, escalation
  ladder documented; fork idea set aside (role confusion).
- vision-branching.md (unscheduled): tree-shaped records, plan-overlay UI;
  pi SDK has no native branching (verified) — our own record-model work.
- vision-persistent-agent.md (PARKED): markdown session records as the
  pull-based substrate, graph-as-truth over user.md, graph composer as
  interface, session kinds/three-surfaces note.

docs/vision-branching.md

@@ -0,0 +1,23 @@
+# Vision — Session Branching
+
+Started 2026-09-27, ideation round. No priority assigned yet (suggested slot: after practice + side chats — it is the deepest record-model change in this document set).
+
+Now that the app is fully pi-native, support **session branching**: the message history becomes a tree; the learner can navigate back in time and branch — explore "what if" continuations, revisit decision points, keep alternate lines.
+
+## The UI (owner sketched 2026-09-27)
+
+A popup overlay **in the chat area** — exactly the same overlay pattern as the plan window. It presents the session's **teacher messages, separated by teacher message**, and the user branches from those points.
+
+## Assessment (coordinator, 2026-09-27)
+
+- The overlay UI is the easy part. The record today is a **flat native message array**, and everything downstream assumes linearity: the view projection/grouping canon, the write-ahead persistence, the turn runner's one-turn-per-chat liveness, coverage fingerprints (keyed by message id), extraction idempotency (refs by toolCallId), subscription replay. Branching means a **tree-shaped record model** designed deliberately — not a UI feature bolted on.
+- **The pi SDK carries no native session-tree branching** (its `Branch*` exports are compaction summarization only, verified 2026-09-27). This is our own record-model work. Per the owner: read the full pi docs on sessions/branching before designing — confirmed as implementation-time step 1 regardless.
+- Value is real: rewind/replay fits the tutoring domain well (alternate explanations, "what if I'd answered differently"), and it composes cleanly with the parked persistent-agent idea later (branches as parallel histories to reconcile).
+
+## Open questions (unruled)
+
+- Tree representation: parent pointers per message vs. branch records referencing a base prefix.
+- What happens to graph evidence from **abandoned branches** — does extraction run per-branch, active-path only, or all paths with branch-scoped attribution?
+- Branch lifecycle: naming/labels, switching, deletion; is the original line just another branch?
+- Are user messages also branch points (edit-and-resend), or teacher-message anchors only, per the sketch?
+- Interaction with practice/side chats (presumably none — they attach to their own surfaces).

docs/vision-persistent-agent.md

@@ -0,0 +1,28 @@
+# Vision — The Persistent Agent (PARKED)
+
+Started 2026-09-27, ideation round. **Parked by the owner 2026-09-27** — "a much later thing." This document preserves the ideation so nothing is re-derived. Practice module and side chats go first; branching after those.
+
+## The pitch
+
+A **tutor of record** — an agent that teaches nothing. It is the general interface to the accumulated learner model: it knows where the session records live, can read them, holds access to the knowledge graph, and keeps a detailed, longitudinal record of the user's understanding.
+
+## The substrate — sessions as markdown
+
+- Sessions get converted to **markdown records, persisted as files** — the corpus other agents read with the read/ls/find/grep tools every pi agent already has. This is the pull-based (pi-native) version of context sharing, philosophically opposite to the removed Wave-7 pushed-injection.
+- **JSON stays canonical; markdown is a derived export with a defined shape** — regenerable, no second source of truth.
+- Two audiences, one artifact: the human archive and the agent food want the same *distilled session record* — goal, the plan map (already mermaid — markdown-native), nodes covered, checks with outcomes, misconceptions found, where the session left off (~40 lines, not a 400-line verbatim transcript; the verbatim JSON exists forever).
+- Open: who writes the record — dumb code folding the record, or an agent summarizing at session end. Could ship standalone before the rest of this document (it serves export value immediately and this agent later).
+
+## The agent itself (ideation, unruled)
+
+- **Queries the graph, doesn't hold it.** The graph lives in stores with query tools; holding it as context text is stale-copy risk and token burn. Context stays small; truth stays in the stores.
+- **user.md — a living synthesis the agent maintains** — with the discipline that **the graph is the truth and user.md is the index**: the graph is evidence-backed (every node traceable to extraction); free-form prose memory has no audit trail. Disagreements resolve toward the graph. Otherwise it's a second brain with no epistemics.
+- **The graph-view composer becomes its interface** — the natural home: the page where you see everything you know, and ask about it. This also makes the graph a control surface: **sessions created from the graph** (select nodes → "teach me this" → a session whose plan could seed from the selection; the probe could focus or skip accordingly).
+
+## Session kinds (relevant once practice exists too)
+
+Three fundamentally different session types — teaching, practice, the persistent agent's chats — should not sit mixed in one flat list. Agreed direction: **one session store with a `kind` discriminator, three surfaces** — teaching in the sidebar (untouched), practice entering from the graph/sessions, the tutor-of-record chat at the graph composer. Icons alone say what a thing is; surfaces put it where its activity lives. (The store-side kind field becomes real as soon as the practice module lands — see vision-practice.md.)
+
+## Home page
+
+If practice and the persistent agent both enter through the graph, the graph stays home and grows denser with affordances — no tabs. Tabs are what you add when something has no natural home. Watch: the graph page must not accrete too many meanings; "everything I know, and everything I can do with what I know" is one coherent meaning, and it should stay that way.

docs/vision-practice.md

@@ -0,0 +1,44 @@
+# Vision — The Practice Module (Exams)
+
+Started 2026-09-27, ideation round. **Priority 1** of the post-explain roadmap (above side chats; persistent agent parked separately).
+
+The teaching sessions are the *installation mechanism* — they install knowledge. Practice is the *training mechanism* — it solidifies what was installed. Sessions are for learning new things; practice is for retaining and sharpening them. Spaced repetition is the explicit long-term goal, but the entry point is deliberately simple: **the learner picks the nodes** (most commonly: everything a session covered) and gets an exam over them.
+
+## The assessment record model (owner rulings 2026-09-27)
+
+- **Session quiz answers NEVER carry over to the graph.** Quizzes in a teaching session tag *plan steps* — entirely session-scoped objects, distinct from global graph nodes. No direct mapping. (The graph only ever hears the extractor's judgment.)
+- **The extractor's understanding observation is data point zero.** First assignment at node conception; each session's extraction adds its own observation (today's seam already emits these as session-scoped ledger events).
+- **Each practice session that touches a node appends one new assessment record.** A node's understanding is therefore a *history of records* — never an overwritten field. "Understanding is inferred, never encoded" (vision.md §1) stays intact: the displayed level is derived from the record set.
+- **Aggregation over the records is future theory.** Weighted average at minimum; a Bayesian flavor is attractive (few data points = low confidence; the number of records should modulate certainty). Not decided. The user is presented **a number**.
+- **Labels are the extractor's standardization device; numbers are the truth.** The written scale (today: `solid / shaky / accepted / resisted / not yet engaged`) exists so extractor runs share one vocabulary; underneath it is an ordinal scale, and everything downstream — storage, derivation, presentation — works in numbers.
+
+The record history doubles as the substrate for **revision suggestions** ("what should I practice next") — schedulable mathematically/algorithmically later. But suggestions are a derived surface; the primary entry is always the learner's own node selection.
+
+## The exam flow (minimal agent shape, owner sketched 2026-09-27)
+
+1. **Entry.** The learner chooses a set of nodes — most commonly "the propositions this session covered" as a shortcut over a session. (Coverage data already derives session → node sets.)
+2. **The problem-engineer agent.** System prompt carries the problem-engineering theory and instructions (owner will author this theory — pending, see below). Input: the propositions and their connections — a portion of the graph, NOT session transcripts. Output: a problem set.
+3. **Coverage is guaranteed and self-verifiable.** Every proposition in the input is tested by some problem, and **each problem's metadata encodes the propositions it tests** — so the agent itself can check completeness and omit nothing (the metadata reinforces its own verification).
+4. **Exam shape.** Short and satisfying: **3–6 really good problems.** Challenging where possible — "all knowledge can usually be applied," so application problems are on the table across domains, not just math-exam shapes. (Owner leaning; theory pending.)
+5. **Problems may be one long tool call.** The problem set is authored up front — solutions and answers written beforehand (commit-before-pose, the same sycophancy mitigation as `explain`).
+6. **The learner turns in answers.** The agent's next input is the submission.
+7. **Grading against its own pre-written solutions.** Then the grades are submitted **via a dedicated tool** — that tool's input is what updates the nodes' understanding records. The grading tool call is the write seam.
+
+## Problem formats
+
+- The two existing question shapes (multiple-choice `quiz`, free-recall `explain`) are solid problem shapes — but the practice module gets **its own purpose-fitted tools** (duplicates either way), so teaching tools stay untouched.
+- **Formats stay highly configurable.** More shapes will likely be added; nothing is hardcoded to two.
+- **The problem-engineering theory is an owner deliverable.** The philosophy of constructing the optimal practice problem (types, difficulty, application-vs-recall, how connections enter problems) — owner is thinking and will bring it back. No implementation of the generator until that theory lands.
+
+## What this module finally unlocks
+
+The live, continuously updating view of the learner's understanding: extractor observations as the floor, practice outcomes accruing on top, derived numbers on the graph. This is the node-understanding-assessment thread resuming.
+
+## Open questions (unruled)
+
+- Practice sessions as a third session kind in the store (`kind: practice`)? Where do exam records live, and do abandoned/partial exams persist?
+- UI surface for practice sessions (exam presentation is meant to be satisfying — the shape of that screen is open; entry likely from sessions and/or the graph).
+- Retake policy — does re-practicing the same exam append new records like any other practice?
+- Migration: existing nodes already carry extractor observations — these become the initial records.
+- Does the grading write path go through the ledger (as a new practice-scoped event kind) or a dedicated assessment-record store?
+- Scheduling/revision-suggestion algorithm — parked until the history exists.

docs/vision-side-chat.md

@@ -0,0 +1,27 @@
+# Vision — Side Chats (block-scoped clarification threads)
+
+Started 2026-09-27, ideation round. **Priority 2** of the post-explain roadmap (practice module first — this one is expected to be easy at the end of the day).
+
+Quick clarification for quick questions — *between* the teaching. A separate, minimal agent exists beside the main learning agents; the teaching agents must stay unloaded (the owner's ruling: side chats have **zero effect on the teaching session**).
+
+## The shape (owner sketched 2026-09-27)
+
+- **Per teaching block.** Each block of the session transcript (the units divided by separators — turn groups) can carry its own mini thread.
+- **UI discipline — invisible until relevant:**
+  - No side chats → **nothing changes in the UI**, except:
+  - a small chat button in the **bottom-right corner of each block, visible on hover** of that block;
+  - opened threads render as a **collapsible mini-chat underneath their block**, accumulating inline.
+- **Never part of the teaching record.** The teaching agent never sees these threads; they are annotations on the session, not conversation within it. Where they persist (same file under a teacher-invisible namespace, or a side store keyed by chat + block anchor) is open.
+
+## The agent (v1, first try — owner ruled the starting point)
+
+- **Block-only context.** The ONE block being asked about is its only input, plus a system prompt instructing it to answer **very non-verbosely, directly, simply**. Questions are about specific sections, and the UI makes that scoping clear.
+- **Forking the session was considered and set aside.** A fork (session-so-far + different system prompt) gets role-confused — it reads the transcript as its own words. If block-only proves ungrounded, the agreed escalation ladder, in order: + the plan tree, + the relevant graph propositions, + selected earlier blocks.
+- Bare, cheap, tool-less, one model slot down from the teacher. The honest risk on record: an ungrounded answer that confidently contradicts the lesson is poison under the accuracy doctrine — watch it, don't pre-solve it.
+
+## Open questions (unruled)
+
+- Block identity/anchor stability (blocks are derived groupings — anchor by the block's first message id).
+- Persistence location and shape (teacher-invisible namespace in the chat record vs. a separate store).
+- Model slot (cheap, presumably) and any context ceiling.
+- Keyboard/affordance details (hover-only button, or also focus-reachable).