Session handoff — Companion surface design + engagement identity + Bin-3 build queue

Version. v0.1 Date. 2026-06-25 (evening) For. The next chat, starting cold in the morning. Two-role discipline (standing). Claude.ai = scoping, CRs, methodology, records, design. Claude Code (CC, on DUNIN7-M4) = execution, retrieval, commits, pushes. Every repo write needs explicit Operator authorization before commit AND before push (halt-before-push). Stage by explicit path, never git add -A. Fresh chat per work type. Records are HTML-primary + Markdown, canonical home loomworks-record (behind Cloudflare Access). CC drops record copies in ~/Downloads/ as the Claude.ai retrieval bridge.

Plain-language summary — read this first

This session designed the Companion as a conversational driver over the Loomworks engine, then took a deep detour to settle engagement identity (which was blocking the design), then produced a grounded engine-work queue. Everything substantive is filed in loomworks-record. The design phase is essentially complete; the next phase is build scoping, and the queue tells you exactly what to scope first.

The single most important next action: scope the current-engagement spine (gap 1 / queue item B) — a current_engagement_id field on host_account. It is the structural keystone the whole voice-first Companion rests on. It is a fresh-chat scoping note, grounded by the Bin-3 findings record. (TTS / queue item A is an independent near-free frontend piece that can be scoped in parallel anytime.)

How the session got here (the arc)

It started from "I did not notice any changes to the Companion interface" and a frustration that the Companion is useless. That decomposed, through the Operator repeatedly refusing the smaller question, into: design the best Companion to drive the engine, using voice, grounded on the real API surface. The trajectory:

1. Shipped two engine CRs (held-commit affordance; conversational fidelity) — done before the design work.
2. Surface-coherence audit found the nav was severed (two nav systems, one-way island).
3. The Operator reframed: don't patch the pages — design the Companion against the engine's real capabilities.
4. Grounded on the live 204-operation API surface; produced the comprehensive Companion design (verb-grammar mapping, three-bin gap analysis).
5. Built four surface mockups (two levels × two form factors).
6. Hit a blocker: couldn't design the across-engagements home without settling engagement identity. Deep detour → engagement-identity decision record.
7. Returned, finished the home mockups, reconciled all four to the settled identity vocabulary.
8. Confirmed the Bin-3 engine gaps → produced the cost-sorted build queue.

The methodology lesson worth carrying: the good design came from stepping back from feature-patching to ask "is the whole surface right," and from grounding every structural claim against the live engine via CC rather than memory/screenshots — which diverged from truth repeatedly this session.

What is SETTLED (decided, grounded, filed)

Engagement identity (filed: substrate/loomworks-engagement-identity-record-v0_1, pushed, commit 8d8fbe9)

• UUID is the engagement's identity — globally unique by construction, exposed via the API, preserved on share, never regenerated. The only handle that crosses any boundary.
• E#### (display_identifier) is a local label — instance-wide sequence, shared by all members within one instance. In a federation future, each instance assigns its own E#### to the same UUID (Operator's rule). Never referenced by humans across instances.
• operator_sequence_number is a per-person handle — your "23" (a real live value); Personal is "0". Shown next to E####.
• Name is for speaking.
• Personal is an engagement with visibility='personal' (E0030 in dev) — same four-room machinery, NOT a separate object class. There is NO "M" prefix and NO reserved 0001–0999 band (both were hypotheses, corrected by CC).
• Contributorship is Model A (in-instance) today; federation does not exist. Cross-instance sharing, OVA (the cross-authorization gate, a permissive stub), and the federation receive-mechanism are all deferred/unbuilt.
• "Running out of E numbers" is a non-issue — bigint-backed, four-digit is minimum padding (grows to E10000+). Only forward caveat: frontend must not assume exactly four digits (render-robustness, no engine change).
• Companion addressing (consequence): address by name + per-Operator number + E####, all instance-local; UUID invisible.

The Companion design (filed earlier this session — confirm exact path with CC)

• Filed: loomworks-companion-design-v0_1 (the verb-grammar mapping, three-bin gap analysis), plus the through-line standing note loomworks-standing-note-companion-design-through-line-v0_1.
• Core idea: the Companion is a conversational driver over the engine's verb-grammar; pages become what the Companion shows, not a tree to navigate; voice carries the high-frequency verbs.
• Two of four rooms (Manifestation, Shaping) have ZERO conversational path today — most of the work is exposing existing engine operations via new intents (Bin 2), not new engine capability.

The Bin-3 build queue (filed THIS message — see "pending" below)

• Filed: loomworks-companion-bin3-capability-findings-v0_1.
• The four genuinely-missing capabilities, confirmed and cost-sorted:
• A — TTS (voice output): frontend-only, no engine change (browser SpeechSynthesis reads the existing companion_message). Independent, near-free.
• B — Current-engagement (the spine): small engine change + Companion wiring. SETTLED structure: a current_engagement_id field on host_account (single focus per person; NOT a session table — table deferred until concurrent contexts are a real need). Unblocks voice-direct.
• C — Reference resolution ("the second one"): Companion-side substitution works now; engine-side rides on B's structure.
• D — Composite engagement-state read: works today by fan-out over existing per-room endpoints; a dedicated endpoint is an optimization, not a blocker.
• Structural insight: gaps 1 and 4 share a root — there is no per-conversation server-side state object (a "conversation" is just the implicit set of conversation_turns for a person+engagement pair). Build B's structure and C's engine-side extends it.

The four surface mockups (design illustrations, NOT specs)

All four standalone HTML, brand colors inlined, in ~/Downloads/ and staged for filing (see pending):

• loomworks-companion-home-desktop-mockup-v0_1.html — across-engagements home (engagement list + Personal zone + lens tabs).
• loomworks-companion-home-mobile-mockup-v0_1.html — home, mobile (Personal pinned, swipe between lenses, anchored mic).
• loomworks-companion-surface-desktop-mockup-v0_1.html — inside an engagement, dual-pane (consistency-passed to the identity vocabulary).
• loomworks-companion-surface-mobile-mockup-v0_1.html — inside an engagement, mobile (voice + swipe, anchored mic; consistency-passed).

Design decisions embodied in them (settled this session, but illustration-level — CR-level details deferred):

• Voice = direct call ("open Goosey"); swipe = move (between rooms / between lenses). Both always available. Same model at both levels.
• Speak control is anchored chrome — fixed bar, never scrolls away (solves the Operator's scroll-away concern structurally).
• Across-engagements home: engagement-list-primary (not attention-feed-primary); "needs you / recent" are lenses one swipe/voice-command away. Three zones by visibility: Your space (Personal) / Your engagements / Shared (commons). Administrative (E0001) hidden — instance plumbing.
• Mobile home: Personal PINNED above the swipe plane (Operator chose this); two axes — swipe switches lens, scroll moves the list.

PENDING — filing actions not yet done (do these, or confirm done, at session start)

CC was given filing instructions for these but confirmation may not have landed before the handoff. At session start, confirm with CC what is on loomworks-record main and pushed:

1. Bin-3 findings record — loomworks-companion-bin3-capability-findings-v0_1.{html,md}. Filing instruction given this session; CONFIRM filed + pushed.
2. The four surface mockups (listed above) — filing instruction given as a set, beside the Companion design document; the two surface-* (in-engagement) ones were consistency-passed (overwrite prior copies if they existed, same v0_1). CONFIRM filed + pushed, and confirm whether the in-engagement pair overwrote or were new.
3. Navigation-graph scoping note — loomworks-navigation-graph-scoping-note-v0_1.{html,md} (Cluster A). Drafted and filing-instructed earlier; CONFIRM filed + pushed.

If any are unfiled, the files are in ~/Downloads/. Have CC file by explicit path, halt before push, report SHA.

OPEN — decisions and threads NOT yet settled (for future sessions, not blocking)

• Navigation graph (Cluster A) — the severed-nav fix has a scoping note recommending Solution 1 (restore the crossing), but the intent gate is unanswered: is engagement-navigation the intended landing, and is the two-system split deliberate? The Companion home design partly supersedes this (voice-navigation reaches everything), but the non-voice crossing is still wanted. Resolve when Cluster A is taken up.
• Gap-2 endpoint — build a composite engagement-state aggregate endpoint, or stay with fan-out? Deferred until efficiency justifies it.
• Federation future — the receive-mechanism (assign local E#### to a foreign UUID), live-shared vs. import-copy semantics, the "Contributor" vocabulary split (engine's in-instance bearer-token contributor vs. the Operator's cross-instance sense), FORAY-attestation of shared identity. All named in the identity record, all deferred.
• The 2026-05-17 design's unimplemented parts — Personal not consuming the global sequence; Personal dual-addressed by name; tags-as-aliases and workspaces as grouping surfaces. Settled in design, not (all) in the engine.

THE NEXT ACTION (what the morning chat should do)

Scope the current-engagement spine (queue item B) as a fresh scoping note.

It is grounded and ready:

• Engine: add current_engagement_id (nullable FK → engagements) to host_account. Converse reads it (the "here" for resolving "commit held 14") and the Companion writes it on "open X".
• Companion: "open Goosey" / "open 7" / "open E0007" → resolve to the engagement (by name / per-Operator number / E####, per the identity record) → set current_engagement_id. Reading "here" surfaces the current engagement.
• Structure is SETTLED: field on host_account, not a session table. (host_account already holds personal_engagement_id, companion_name — natural home.)
• This is the keystone: it unblocks voice-direct, and gap-4's referent set later extends the same structure.

Per discipline, the scoping note starts with a Step-0 inspection brief for CC (read-only): confirm host_account's current columns, the converse read/write path, how "open X" addressing resolves today (EngagementList.tsx:137 resolves on display_identifier client-side), and where the focus would be read on the converse path. Then draft the scoping note.

Parallel option: TTS (queue item A) — independent, near-free, frontend-only (browser SpeechSynthesis reads companion_message). Can be scoped anytime without touching the spine.

First-read for the morning chat: this handoff, then the seed (highest loomworks-candidate-seed-vN_M), the current-status manifest (highest), and architecture spec v0.4 — then the Bin-3 findings record and the engagement-identity record for the immediate context.

DUNIN7 — Done In Seven LLC — Miami, Florida Session handoff — Companion surface design + engagement identity + Bin-3 build queue — v0.1 — 2026-06-25