Version. 1.0
Date. 2026-06-10
Status. Implementation notes — the record-resident write-up of the orientation & discovery capability (CR-2026-099), built and shipped to engine main a41ebf5 / Operator Layer 4e43e9f. Released (v1.0) — the capability is complete, faithful, and verified by Operator browser review. Records the build as it landed, the two design corrections that shaped it (D1, D2), and the composition-layer fabrication failure and its fix, with the two methodology lessons the arc earned. Operator-facing summary at top; technical detail below. Markdown primary, HTML companion.
Author posture. Descriptive of built behaviour, grounded in the build history. The fabrication failure and the gate breakdown are recorded plainly, not smoothed — both are load-bearing lessons.
Relates to. The orientation & discovery scoping note v0.2 (the settled design); CR-2026-099 v0.1 (the capability) and v0.2 (the composition fix); the Companion-as-Operator-system-interface standing note v0.1 (the principle this serves); queued-directions §6.4 (the Explain affordance, orientation's sibling).
This capability lets an Operator discover what they can do in Loomworks by asking the Companion — "what can I do here?", "what can I change?", "I'm lost, what's next?" — and get an answer scoped to where they are, with example phrasings they can tap. It is the discovery surface the Companion-as-interface principle assumed but did not provide: a conversation, unlike a settings screen, shows nothing until asked.
The build went in eight pieces across engine and Operator Layer. It held three disciplines: pull, not push (answer when asked, never nag); scoped to the perceived engagement-context (what's reachable from where the Operator is, located lightly — "in voice listening you can adjust the blur"); and generated, never hand-written (the catalog comes from the system's own registries, so it cannot go stale).
Two things in this build are worth remembering. First, an early version fabricated — asked "what can I do here?" in a houseplant project, the Companion invented houseplant-specific actions that weren't real, because the prose was composed by a language model fed the project's domain context. The fix removed the model from that reply entirely: the answer is now composed deterministically from the catalog, so it can only ever say what's actually available. Second, that fabricating version briefly reached main before Operator review caught it — a reminder that the review-before-ship gate must be a separate step, not bundled into the build.
Orientation & discovery is a Companion capability: the Operator asks what they can do or change in the current context, and the Companion answers from the system's own knowledge of what is available, with drive-it example phrasings. It subsumes settings discovery ("what can I change") as one category of the broader "what can I do here." It serves the Companion-as-Operator-system-interface principle by being its discovery surface — the conversation describing itself.
The capability answers three query kinds, scoped to the perceived engagement-context: all ("what can I do"), settings ("what can I change"), and next_step ("I'm lost / what's next").
Engine.
display_name field added to SettingSpec, a canonical display name per setting, and list_settings() returning the catalog (key, display name, bounds, synonyms) — the single source for any settings answer.unknown_setting fix — tune_setting's near-miss response repointed at the enumeration helper, so it names all current settings, generated. This closed a live staleness defect (the prior hardcoded list named 2 of 3 settings) and proved the generate-don't-restate spine on a shipping surface.orient intent (declare-and-register: IntentLabel Literal, classifier guidance, router dispatch, _route_orient handler). The handler assembles the context-scoped catalog and populates suggested_actions.ConverseRequest — carrying the perceived context, default None (back-compatible).Operator Layer.
suggested_actions — added the SuggestedActions render mount to CenterPane and the navigation surface (it had been create-engagement-only); the creation-flow population preserved unchanged.tryPromptHint content into the registry, and extend recognizeNavigation to accept the plain-terms forms the chips advertise ("project 23") — so the examples the capability teaches actually fire. The existing "engagement 23" hint was corrected to "project 23" (a plain-terms fix).The scoping note was a hypothesis; the Step 0 inspection corrected it before the CR built on it.
D2 — scope to the perceived engagement-context, not the technical component. The converse call sites give three coarse surfaces, but settings ownership is finer: from the in-engagement surface, only conversation.message_order is owned locally — the two voice settings are owned by the engagement-navigation voice panel. Strict converse-surface scoping would have told an in-engagement Operator only about message order and hidden the voice settings behind a component boundary the Operator does not perceive, reopening the discoverability hole. The fix: scope to the place the Operator perceives ("the engagement I'm in"), surface every setting reachable from it, and locate each lightly ("you can change the message order here; in voice listening you can adjust the blur and the wait time"). This honours "only show what is available" correctly — blur is available to an in-engagement Operator, so surfacing it is right and hiding it would be the failure.
D1 — the render mount was new work, not reuse. SuggestedActions was mounted only on the create-engagement surface; the in-engagement and navigation surfaces had no mount. "Generalize" therefore meant adding the mount to those surfaces, not reusing an existing one. Sizing correction, folded into the CR.
(A third, favorable correction — D3 — noted that intent_hint derives from IntentLabel, so adding the intent auto-widened it with no separate edit.)
This is the load-bearing lesson of the arc.
The failure. The capability shipped (CR-2026-099 v0.1) and, at Operator browser review, fabricated. Asked "what can I do here?" in an engagement titled "Houseplant — Monstera deliciosa," the Companion described invented houseplant-specific actions — "log a watering," "review the care details," "ask when the plant was last watered" — none of them real intents or registry actions. The rendered chips were correct (the real generic registry examples); the prose was fabricated.
The cause. The registry catalog the handler assembled was correct — generic, zero domain content. But the prose was composed by the responder LLM, and assemble_prompt placed PROJECT CONTEXT (the engagement title, its seed, recent Memory — the full plant-care domain) in the system prompt above a permissive template. The model, fed rich domain context and asked a capability-meta question, mapped the generic actions onto the domain: "add a note" → "log a watering." The fabrication was PROJECT CONTEXT bleeding into a capability-meta answer. Orientation is the one intent where domain context is a hazard rather than an aid.
The fix (CR-2026-099 v0.2). Server-compose the orient reply, bypassing the responder LLM. compose_orientation_reply(operation_data) is a pure deterministic function (mirroring compose_completeness_check_reply) that reads the structured catalog dict and composes the prose — it sees only the generic catalog, so domain elaboration is structurally impossible. A new elif intent == "orient" branch in the converse chain builds ConverseResponse directly; orient never calls assemble_prompt or generate_response. A defensive intent != "orient" guard on PROJECT CONTEXT was added as insurance. The dead LLM path (orient.md, _format_orient) was retired. The guarantee was proven by a test that injects domain context and asserts the output changes by zero characters. Operator browser review confirmed faithful output: real generic actions, located settings, no fabrication.
Lesson 1 — a structural-contract reply must be composed server-side, not generated. When a reply's content is an authoritative generated list (a structural contract — here, the catalog of what's available), composing it with an LLM fed domain context invites the model to substitute or elaborate under context pressure. Soft prompt constraints lose to rich context. The robust answer is to not generate the reply — compose it deterministically from the authoritative data. The voice completeness-check established this pattern (its own code comment names the same failure mode); orientation is its second instance. This generalizes: any reply whose shape is a contract over generated data should be server-composed. Recorded as a methodology candidate.
Lesson 2 — the browser-review gate must be structurally separated from the build. The fabricating v0.1 reached main before Operator browser review caught it: the FF+push ran bundled with (or immediately after) the build step, ahead of the review the checkpoint reserved. The correction, applied to the v0.2 fix: the build halts, and the push is a separate instruction the Operator sends only after confirming faithful output in the running stack. A review gate that lives in the same instruction as the action it gates is not a gate. Recorded so it does not recur.
Shipped and faithful (v1.0). Engine main a41ebf5, OL 4e43e9f. The capability answers the three query kinds, context-scoped (D2), with working example chips (D1), generated from registries (no staleness), and composed deterministically (no fabrication). Engine suite 2865 passed / 0 failed; live classifier confirmed (orient classifies, no action-utterance theft); composition no-leak proven; Operator browser review passed. Tags: companion-orientation-discovery-v0_1 (original ship) and companion-orientation-discovery-v0_2 (composition fix), trajectory preserved.
Open (deferred, logged for queued-directions): the on-screen "engagement" UI-label plain-terms cleanup (larger, separate); the test-DB concurrent-interference pattern (isolation family); and an observation that the voice completeness-check appears to fire on short orient utterances ("I'm lost") — a minor surface behavior to watch, not an orient defect.
DUNIN7 — Done In Seven LLC — Miami, Florida Loomworks — Companion orientation & discovery — implementation notes — v1_0 — 2026-06-10