ho-06.2 — The Workshop: three-state glyphs and the heal surface

Make the vault's state legible at a glance and its drift reconcilable. This ho reads the scan cache ho-06.1 built — glyphs on the sidebar rows tell you where each scope lives, a pulled-on-demand drift surface tells you which materialized files have wandered from the vault, and one action reconciles them. Two gate-born chrome items ride along: a Settings scene with an appearance override, and scan-root visibility in the footer.

The ho-06 split. K4 planned ho-06 as one polish ho and flagged it as the densest in the project. It split three ways at ho-06.1's opening:

• ho-06.1 (closed 2026-07-10, PR #12) — responsiveness + honest feedback.
• ho-06.2 (this ho) — three-state glyphs + heal/drift surface.
• ho-06.3 (provisional) — first-run wizard, age-key generation + backup nudge, ingest flow. Its premise was gate-validated at 06.1: the operator could not find the repos-to-vault path from the GUI.

K4's ho-06 section body still describes the un-split ho; the split is recorded in K4's 2026-07-10 revision header and in K6. Reconciling the section body is a ho-kamae-4-overview-collaborator pass, flagged from this session — not edited here.

Out of scope:

• First-run wizard, age-key generation, backup nudge, ingest flow — ho-06.3.
• Orphan remediation (create-scope-from-orphan, remove-stray-marker) — this ho surfaces orphaned markers; fixing them is ingest-adjacent, ho-06.3.
• Multi-root scan management UI (add/remove/reconfigure roots) — owed as a near-term ho (see Decision 5). This ho shows all roots read-only.
• The right-side collapsible tool rail — deferred with criteria (Decision 1).
• The linking picker / shared-secret browser, rotation-driven staleness — ho-07.
• The per-entry "plain / not-a-secret" flag — parked schema Think (Kamae-2 level).
• Scriptable init, unconditional git init, non-atomic ingest — the owed CLI ho. Zero files under Sources/SharibakoCLI/ change in this ho, same rule as ho-05 and ho-06.1.
• Notarization / distribution — ho-08.

Phase 1 — Think

Five decisions, ratified 2026-07-11. Two facts about the Core surfaces drive most of them, both found by reading the code before deciding:

• Materializer.status(scopeID:scanRoots:) re-walks the tree on every call (it calls scan(roots:) internally). Glyphs must not route through it — that is the exact cost ho-06.1's in-memory scan cache exists to kill.
• Materializer.heal(marker:) decrypts every owned key to compare vault-plaintext against file-plaintext. Drift cannot be known passively; every drift check costs the age key, a Touch ID, and a VaultWorker hop.

Decision 1 — Chrome: native top-toolbar; the right-side rail deferred with criteria

The operator floated a right-side collapsible tool rail (icons when closed) replacing the top toolbar. The friction behind it is real — after 06.1 the toolbar carries Rescan, Jump, Sync, Materialize, Preview, and two Add buttons, and this ho adds heal actions. But a right-side action rail cuts against macOS convention (Mac puts actions in the top toolbar or a bottom bar; the right edge is conventionally an inspector — which is exactly what the third NavigationSplitView pane already is), and it commits every later surface (06.3, ho-07) to a non-native idiom. The operator's actual pains — crowding and label legibility — are solvable within the native idiom.

• This ho: Heal, Check-drift, and Materialize-all-stale get homes on the top toolbar; if that crowds the bar, secondary actions (Preview .env, Jump-to-directory) move into an overflow or contextual placement. Grouping is execution-level, not a migration.
• Rail revisit criteria: revisit the right-side rail only when a later surface needs standing chrome the top toolbar can't hold without discoverability loss — concretely, 06.3's first-run flow or ho-07's linking/shared-browser adding a mode that wants a persistent surface. Until then, native top-toolbar plus overflow.

Decision 2 — Glyphs: computed from the scan cache; orphaned markers get synthetic rows

Two parts. The first is forced by cost; the second is a data-model fork.

• 2a — Computation home. Glyph state computes in WorkshopModel from the in-memory scanReport.markers intersected with scopes — not through Materializer.status, which re-walks. A tested computed accessor, glyphState(forScope:), reads the cache. Synchronous, no worker, no Touch ID. live_here (vault scope with a marker in the scan roots) and live_elsewhere (vault scope with no marker in the roots) fall straight out of the intersection.

• 2b — Orphaned markers get synthetic sidebar rows. live_here and live_elsewhere are properties of a scope, so they map to scope rows. orphaned is a property of a marker that references a scope the vault doesn't have — it has no scope, so it has no row. Rather than hang a third glyph on rows that can't carry it, the sidebar renders orphaned markers as their own rows in a distinct "Unlinked markers" section, carrying the orphaned glyph, selectable to show the marker's path. This honors the plan's three-state intent and puts the orphan where the user is already looking. Surfacing only — remediation (create-scope, remove-marker) is ingest-adjacent and belongs to ho-06.3. scanReport.failures (malformed markers, ho-04.11) surface in the same section, distinguished from orphans by their load-failure reason.

Decision 3 — Heal: pull-based, session-cached drift; sweep behind one Touch ID; reconcile via materialize

Because drift costs a full decrypt, a "drift indicator on materialized scopes" cannot be ambient — rendering badges at launch would decrypt every scope at launch, prompting Touch ID the moment the window opens, which contradicts ho-06.1's whole achievement (window interactive immediately, no work until asked). So drift is pulled, then cached for the session — parallel to scanReport:

• Launch: no drift info, no Touch ID. Same posture as the scan cache.
• Check drift sweeps every live_here scope through VaultWorker with visible activity progress, behind one Touch ID (ho-06.1's 5-minute reuse window covers the sweep). Results land in a new session cache, driftReports: [scopeID: DriftReport].
• Rendering: sidebar drift badges and the detail pane's per-key drift render from that cache. "Drift indicator on materialized scopes" becomes true after a check, cached — never ambient-at-launch. Before a check, the badge slot is empty; the sidebar row shows only its glyph.
• Reconcile is the existing materialize(force:) flow — it already decrypts, already has the pendingDiff → confirmation dialog. heal views drift (read-only); materialize fixes it (writes). After a successful reconcile, that scope's cached drift refreshes.
• Materialize all stale batch-reconciles the scopes the cached drift marks as drifted, behind a confirmation listing what will be written and one Touch ID. This is the drift-driven version the README first-session vignette references. ho-07 later extends "stale" to include rotation-driven staleness, reusing the button — not a scope conflict, a shared definition growing.

Decision 4 — Settings: a native scene with an appearance override

Gate item. The operator asked for a System/Light/Dark flipper; a Settings scene is its native home. SwiftUI's Settings {} scene wires ⌘, automatically; a stored enum drives .preferredColorScheme; persistence is @AppStorage (UserDefaults), the right backend for a pure UI preference.

• Content this ho: the appearance override only. No invented heal/glyph toggles — a "check drift at launch" toggle would re-introduce the launch Touch ID this ho designs away.
• Two persistence backends, kept honest: appearance lives in UserDefaults (@AppStorage); vault and scan roots already live in config.yaml (operational config). The Settings scene does not fold scan-root state into UserDefaults.

Decision 5 — Scan-root visibility: footer, read-only, all roots

Gate item. "Where is it scanning?" has no UI answer — roots live invisibly in config.yaml. Waymarking answered the vault half (footer names vault + remote); this answers the scan-root half.

• This ho: the sidebar footer names the configured scan root(s) beside vault and remote, full paths in the tooltip, same pattern as the vault line. Because scanRoots is already [URL], the footer renders all roots — a user who hand-edits config.yaml to add roots sees them reflected. Read-only; the single-root pick stays the existing NSOpenPanel-on-empty flow.
• Owed, near-term: multi-root scan management UI (add / remove / reconfigure). The practitioner flagged this as a real, soon need — elevating it above K4's post-MVP Deferred Decision #4. Forward-only: a new ho, not a reopening of the deferral. Recorded in K6 and flagged for the same K4 overview-collaborator pass that reconciles the ho-06 split — likely a small dedicated scan-config ho, or folded into ho-06.3's first-run config work. Not placed here; placement is an overview call.

Discovery (deferred to execution)

• Glyph and badge symbols. SF Symbol choices for live_here / live_elsewhere / orphaned and for clean / drifted, with distinctions carried by shape, not color alone (colorblind-safe) and Reduce Motion respected. Execution-level; no ratification needed.
• Sweep progress granularity. Whether the Check-drift activity reports per-scope progress or a single "Checking drift…" is an execution call; a large vault makes per-scope nicer but it is not a decision.

Appendix — fresh-session bootstrap

To execute this ho in a new Claude Code session, load and run prompts/ho-06.2-execution-driver.md.

Authored 2026-07-11 (Think phase ratified same day, five decisions, split from K4's planned ho-06 at ho-06.1's opening). Executed and closed 2026-07-11: AT-01 → AT-02 → AT-03 + two gate fixes, signed-install + Touch-ID gate passed (chrome finding owed a followup ho, forward-only).