Current index · The maintained retrieval map for choosing the chapters that bind a task.

Reading Index

Chapter summary: This index offers role-based reading paths, chapter descriptions, and a vocabulary map so humans and agents can retrieve only the material relevant to the task at hand. It covers the founding Grounding-first transition (00–11) and the working-surface, reasoning, knowledge, retrieval, uncertainty-representation, and capability-governance doctrine that grew from it (12–37). See the root README for the genesis and full arc.

The suite is intentionally divided into short, stable chapters. Agents should not load the whole directory into every prompt. Select the chapters whose authority is necessary for the current task, then retrieve live code and state for implementation detail. A UI claim is not settled by an accessibility-tree query alone — chapter 18 requires looking at the rendered view.

Reading paths

Product and architecture review

Read the abstract, development history, and target architecture. These chapters explain why the older index-centered design existed, why its lessons remain valuable, and why authority moves to Grounding and Storify now.

Grounding implementation

Read the target architecture, Grounding contract, and phases 1–3 of the refactoring program. Finish with the relevant tests in validation and acceptance.

Storify implementation

Read the current-state analysis, Grounding contract, and phases 2–4 of the refactoring program. The source-authority and no-index acceptance cases in validation and acceptance are mandatory.

Readiness, journey, or UI implementation

Read the target architecture, phase 4 of the refactoring program, and compatibility and future evolution. These changes are incomplete until generated capabilities and reasoning artifacts agree with the UI.

Index deletion

Read the entire refactoring program, especially its deletion gate, followed by the agent operating guide and validation and acceptance. Do not begin from a filename search and delete outward; prove replacement consumption first.

The Score, and composing a cut

Read the Score (the one working surface; the timeline and Cut as lenses; the Cut composes a take; every projection reads it — "has one cut"), then the beat and its arrangements (the beat anatomy and the take it fires) and animating truth (how the read is felt). Anything the writer sees or operates is also governed by the stage presents the act. The Cut is not a return of the retired patch-graph canvas — it is a lens and a second lane of the one surface.

Visual, UI, or design work

Read the stage presents the act first — it is the enforceable floor (the act is the star; the glasses test for type and hit targets; progressive disclosure; one act in focus; relationships drawn, not implied; verify by looking in light and dark). Then animating truth, the Score, and the specific surface's chapter. A machine-readable accessibility tree is the necessary but never sufficient half of accessibility; passing it is not passing legibility.

Copilot implementation

Read the target architecture, Grounding contract, the Copilot implementation extension, the situated Copilot, and Copilot capability governance, then follow chapter 10's mandatory discovery procedure before editing. Work that places the Copilot on a surface, or changes what she says when she arrives, is governed by chapter 15 and must satisfy its acceptance as well. The Copilot must reuse existing application operations and the same authority chain; it is not a second workflow engine. The behavioural, relaunch, no-index, and capability-parity acceptance cases in validation and acceptance apply.

Model lanes, cost, and task-based model selection

Read on-device first, and the writer's key — Reframe selects the best eligible model for the task from live capability, budget, credential, and health facts; paid is the default when available, bounded local execution is an internal economic optimization, and an explicit local-only instruction overrides it. It is governed together with the situated Copilot (the opener names the true elected lane and cost before spending).

Training the on-device model to the writer's work

Read training perspectives — a trained LoRA adapter is a perspective (a lens learned from the writer's material), authored by intent, adopted only on evidence (shadow comparison + eval gate), legible, and reversible; it is the on-device path to quality, the sibling axis to on-device first, and the writer's key (which governs the lane and cloud escalation).

Preferences, settings, and configuration

Read no preferences, only reasoning — Reframe has no panel where the writer configures how the app decides; the app reasons decisions in context and the writer instructs it in dialogue. The only stored settings are facts the app cannot reason into existence (credentials, storage location, account state), on a lean Accounts & Storage surface. It generalizes ch.20 (the lane) and ch.21 (training) into the rule both instance.

Turn routing, intent classification, the Copilot's understanding of a turn

Read one reasoning — a turn is understood by ONE reasoning over ONE complete taxonomy, and everything routes from that single decision; no speculative "fast" pre-classifier with a smaller vocabulary that fires first and misroutes, no cascade of reflect* passes racing to grab the turn. It is what makes ch.20's writer's-key recognition reachable and the sibling of ch.22 (no stored toggle for a decision; here, no fast pre-guess for the reasoning).

Intent uncertainty, clarification, escalation signal

Read the reasoning is an uncertainty map — the one reasoning (ch.23) produces an uncertainty map over what the writer could want (settled / ambiguity / thin / failure + why + what would resolve it), not a scalar confidence; the app routes from it (settled→dispatch, ambiguity→clarify, failure→fail visibly), it is the signal the writer's-key escalation (ch.20) reads, and it is inspectable/showable (UncertaintyScoreKit / FCIS-AX). This is also why the one reasoning can run lean.

UncertaintyScoreKit UX, arbitrary ledger lanes, and Reframe binding

Read a want is a gap in a ledger first — it makes the ledger collection open-ended and explains why a lane is only a ledger's drawing, never a fixed kind of doubt. Then read every gap keeps its address: the arbitrary-lane rack, shared-spine map, composite lane/note selection, stable selected-thread account, generic-kit/Reframe boundary, and the rule that chat records collaboration around the map rather than becoming its only state surface. Visual implementation is also governed by the stage presents the act, Apple's Human Interface Guidelines, and FCIS-AX.

Code review

Read current state and refactoring problem, the relevant target contract, and the phase exit criteria in the refactoring program. A review should reject dual authority, hidden index reads, numeric context shaping, or readiness claims that are not persisted.

.claude and .codex

Read the agent operating guide first, then follow the task-specific path above. The guide explains authority precedence, planning discipline, evidence expectations, and the rule that historical documentation is never operational state.

Release, publication, or “what can the App do?” review

Read the released surface is a named build, then validation and acceptance, Copilot capability governance, and the Copilot capability audit skill. The command catalog is an inventory; the release manifest is the only authority for what a named build ships.

Public publication and source-boundary review

Read public publication and private source policy, then the released surface is a named build and validation and acceptance. Use this path when changing what the Book, governance repository, or a public projection may expose.

Scenario execution, ownership, or acceptance integrity

Read validation and acceptance, the Reframe scenario development cycle, and scenario run ownership and non-interference. Use this path when a live scenario is being driven, resumed, interrupted, diagnosed, or promoted. The runner owns terminal classification; intermediate observations do not establish failure; and any unrecorded intervention invalidates the run.

Chapter catalogue

| A Selection Snaps to Meaning | Reframe asks the writer to point at text — to mark, cut, cite, reframe it — and was asking her to do it CHARACTER BY CHARACTER with a mouse. That is an operability failure belonging to the app, not to her: a reader indicates a phrase, a line, a speech, a sentence, never a character offset, and requiring the offset excludes anyone whose hands or eyes are not perfect today. So a selection is SNAPPED to the smallest unit of MEANING containing what she indicated — whole words always, the sentence or speech when she barely selected anything — and the snap only ever GROWS outward to a boundary the text itself declares: never shrinks, never moves off what she touched. The boundary is PARSED, never asked of a model (ch.27), and MEASURED, never concluded (ch.29) — a tokenizer says where a sentence ends, not what it means. And where the text declares no boundary the snap STOPS AND SAYS SO: measured on this app's own shipped corpus, Ulysses' Penelope runs 27,287 characters with a single full stop, so "snap to the sentence" there would select the whole episode. The unit is chosen by what the text IS at that point — speech, stage direction, verse line, sentence — which makes it contextual rather than mechanical; it is shown before it is committed; a deliberate precise selection is honoured exactly; and no surface ever tells the writer her selection was wrong. |

| The Writer Does Not Manage the Projection | Reframe contains its own ledgers, providers, consent, batches, and rendering detail so the writer can navigate /readings, /ground, /world, and an offered /reference act as manuscript questions — without managing internal machinery — while every durable uncertainty note remains reachable through a bounded, honest, AX-verifiable projection. |

| Scenario Run Ownership and Non-Interference | An executable scenario has one owner and one bound run identity; Store/AX observations remain provisional while it runs; only declared terminal predicates classify it; and any unrecorded intervention invalidates acceptance. | | The Scenario Runtime Is Swift and MIDI2-Native | Makes the scenario executor, Store preparation, lifecycle waits, evidence binding, and terminal classification an owned Swift capability using the same typed MIDI2 operation boundary as production peers; Python is transitional only, while AX/CoreGraphics remain independent witnesses. | | Scenario-Driven Development Is Org Infrastructure | Names the organizational consequence of the scenario cycle: a portable, released Swift/MIDI2 seam with product-local authority, independent evidence, public/maintainer projections, historical context, and a future of negotiated software peers. | | The Default Semantic Manuscript Projection | Fixes the default Reframe workspace as a continuous Courier/Fountain manuscript with semantic Questions, Movements, and Read coverage navigation, Copilot on the right, MIDI2 peers below, and no A4 cards, horizontal timeline, or Slugline application chrome. The signature illustration is design evidence only. |

Vocabulary

Canonical source means the imported manuscript stored under the source document identity. It is evidence, not a work surface for generated analysis.

Grounding Profile means the writer-confirmed policy document that directly governs downstream interpretation. It is not a summary of the source.

Storify Source Auto means the chapter-aware structural reading that converts source atoms into kept/noise decisions, beats, uncertainty, synopsis, and arcs.

Cut Script means the mutable, authored draft product assembled from chosen Storify units and later composition.

Continuity means the audit over Cut Script or other explicitly selected units. It is not a substitute source reader.

Legacy semantic artifacts means index passages, reading states, semantic memory, published semantic objects, repair debt, and index performance memory created before this refactor. They may remain inspectable, but they have no authority in the final pipeline.