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. Claude.ai = scoping, CRs, methodology, records, design. CC (on DUNIN7-M4) = execution, retrieval, commits, pushes. Every repo write needs Operator authorization before commit AND before push (halt-before-push). Stage by explicit path. Fresh chat per work type. Records HTML+MD, home loomworks-record; CC drops record copies in ~/Downloads/ as the bridge.

Read this first

This session designed the Companion as a conversational driver over the Loomworks engine, 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.

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

How the session got here (the arc)

Started from "I did not notice any changes to the Companion interface" and the Companion feeling useless. Through the Operator repeatedly refusing the smaller question, it became: design the best Companion to drive the engine, using voice, grounded on the real API surface.

Shipped two engine CRs (held-commit affordance; conversational fidelity).
Surface-coherence audit found the nav severed (two systems, one-way island).
Operator reframed: design the Companion against the engine's real capabilities, not the pages.
Grounded on the live 204-operation API; produced the comprehensive Companion design.
Built four surface mockups (two levels × two form factors).
Blocked on the home — couldn't design it without engagement identity. Deep detour → identity record.
Returned, finished the home mockups, reconciled all four to the identity vocabulary.
Confirmed the Bin-3 gaps → the cost-sorted build queue.

Methodology lesson: the good design came from stepping back from feature-patching to ask "is the whole surface right," and 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 (`8d8fbe9`)

UUID is the engagement's identity — globally unique, exposed via the API, preserved on share, never regenerated. The only handle that crosses any boundary.
E#### is a local label — instance-wide sequence, shared by all members in one instance; in a federation future each instance assigns its own E#### to the same UUID. Never referenced by humans across instances.
operator_sequence_number — per-person handle (your "23", a real value; Personal is "0").
Personal is an engagement with visibility='personal' (E0030 in dev) — same machinery, NOT a separate object. NO "M" prefix, NO reserved 0001–0999 band (both hypotheses, corrected).
Contributorship is Model A (in-instance) today; federation does not exist. OVA (cross-authorization) is a permissive stub.
"Running out of E numbers" is a non-issue — bigint, four-digit is minimum padding (grows to E10000+). Only caveat: frontend must not assume four digits (render-robustness, no engine change).

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

loomworks-companion-design-v0_1 + through-line standing note. The Companion is a conversational driver over the engine's verb-grammar; pages become what it shows; voice carries the high-frequency verbs.
Two of four rooms (Manifestation, Shaping) have ZERO conversational path today — most 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)

loomworks-companion-bin3-capability-findings-v0_1. Four genuinely-missing capabilities, cost-sorted:
A — TTS: frontend-only, no engine change (browser SpeechSynthesis reads existing companion_message). Independent, near-free.
B — Current-engagement (spine): small engine change + wiring. SETTLED: a current_engagement_id field on host_account (single focus per person; NOT a session table — deferred). Unblocks voice-direct.
C — Reference resolution: Companion-side works now; engine-side rides on B's structure.
D — Composite read: works today by fan-out; a dedicated endpoint is an optimization.
Structural insight: gaps 1 and 4 share a root — no per-conversation server-side state object exists (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 (illustrations, NOT specs)

Standalone HTML, brand inlined, in ~/Downloads/, staged for filing: home-desktop, home-mobile, surface-desktop (in-engagement), surface-mobile (in-engagement). Decisions embodied (illustration-level; CR details deferred):

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

PENDING — filing not yet confirmed

Filing instructions were given but confirmation may not have landed. At session start, confirm with CC what is on loomworks-record main and pushed:

Bin-3 findings record — loomworks-companion-bin3-capability-findings-v0_1. Confirm filed + pushed.
The four surface mockups — filed as a set beside the design doc; the two surface-* (in-engagement) ones were consistency-passed (overwrite prior copies, same v0_1). Confirm filed + pushed, and whether the pair overwrote or were new.
Navigation-graph scoping note — loomworks-navigation-graph-scoping-note-v0_1 (Cluster A). Confirm filed + pushed.

If any are unfiled, files are in ~/Downloads/. CC files by explicit path, halts before push, reports SHA.

OPEN — not settled (future, not blocking)

Navigation graph (Cluster A) — scoping note recommends Solution 1 (restore the crossing); the intent gate is unanswered (is engagement-navigation the intended landing? is the split deliberate?). The Companion home partly supersedes this (voice-navigation reaches everything); the non-voice crossing is still wanted.
Gap-2 endpoint — build a composite aggregate, or stay with fan-out? Deferred.
Federation future — the receive-mechanism, live-shared vs. import-copy, the "Contributor" vocabulary split, FORAY-attestation of shared identity. All named in the identity record, deferred.
2026-05-17 design's unimplemented parts — Personal not consuming the global sequence; Personal dual-addressed by name; tags-as-aliases and workspaces.

The next action

Scope the current-engagement spine (queue item B) — fresh scoping note

Grounded and ready:

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

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

Parallel option: TTS (item A) — independent, near-free, frontend-only. Scopable 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), architecture spec v0.4 — then the Bin-3 findings record and the engagement-identity record for immediate context.