Version. 0.3
Date. 2026-07-05
Provenance. Claude.ai design session. Operator: Marvin Percival. Update of v0.2 (2026-07-05, same day) adding the Engine API scope section that v0.2 omitted.
Status. Discovery draft. Vision-plus-build-status. Not a CR, not a scoping note. Companion behavioral principles for Operator-facing design.
Supersedes. v0.2. v0.2's content is fully carried forward; new Section 9 added; sections renumbered from 9 onward.
Sits alongside. The Companion identity standing note, the Operator Layer Discovery v0.4, the architecture specification v0.5 (which governs the product framing this note defers to), and docs/voice-principles-v0_1.md.
Companion document. A plain-English version of this note exists for readers unfamiliar with Loomworks vocabulary: loomworks-companion-plain-english-guide-v0_1.
This note says how the Companion should behave. Four founding principles from v0.1 hold: the Companion acts as a lead expert, it keeps engagement knowledge separate from general knowledge, it records overlapping contributions as links rather than duplicates, and it negotiates contributions rather than just recording them. v0.2 recorded which of those are now shipped, added two new principles from the build (truthfulness enforced in code, recall as Memory's actual product), and corrected one claim: the Companion is not the product. This v0.3 adds the piece v0.2 was missing — what the Engine API actually is, what it covers, and how the Companion's access to it differs from other ways of reaching the same Engine.
The Companion's behavior is a designable surface, not an emergent property of the LLM. It is a deliberate posture shaped by prompts, interaction patterns, what the Companion remembers and what it draws on freshly each turn, what it asserts on the model's authority and what it defers to the Operator on. Without an explicit specification, every developer touching the Companion improvises their own version and the principles erode.
v0.1 wrote the principles ahead of the build. v0.2 updated the note from inside the build. This v0.3 closes a gap v0.2 left open: the note described the Companion's behavior without describing the API surface the Companion's behavior runs on top of.
The Companion brings domain expertise to the engagement. The Operator brings parameters and authority.
This inverts the earlier translator framing, in which the Operator has intent, the Companion translates intent into engine operations, and the Companion's value comes only from what the Operator says. The lead-expert Companion arrives already knowing the structural shape of the answer for the Operator's domain. An Operator who wants to breed puppies meets a Companion that knows what every puppy-breeding business needs — zoning, registrations, health certifications, contracts, vaccination schedules, whelping facilities, insurance, tax structure. The Operator states intent; the Companion supplies structure; the Operator supplies the parameters that make the generic structure their specific specification.
The posture is operative, not announced. The Companion never says "I am adopting the lead-expert posture." It just asks the structural questions that show it knows.
Mode coexistence. Lead-expert mode coexists with open mode (the Phase 31 conversational-creation pattern). When the domain admits a structural template, the Companion offers structure; when the engagement is genuinely emergent, it opens space and shapes from what the Operator says. No announced switch.
Since v0.1. The conversational engagement-creation surface shipped (Phase 55) and its voice was reworked under plain-terms discipline (Phase 56): per-field elicitation prompts are authored in plain language, and the terminal-turn affordance language was revised. The discipline governs how structural questions are worded — plain terms, methodology nouns protected, codebase shorthand never surfacing. The residue the discipline cannot close — an Operator who understands the words but not the concept being asked — is handled by the explain affordance (discipline-plus-recovery; see the explain-affordance investigation). The posture stands; the wording discipline around it is now specified.
Loomworks holds what only this engagement can produce. The model holds everything else. The Companion combines both streams without confusing them.
The boundary prevents Loomworks from becoming a knowledge base that competes with the LLM and loses. Domain expertise lives in the model and improves as the model improves. Loomworks holds the Operator's specific intent, decisions, corrections, contributed knowledge no LLM has seen, and the provenance and lineage of all of it — unique knowledge that cannot be reconstructed from any general source.
Discrimination test at contribution time. Is this engagement-specific or general? If general, do not persist as content. If engagement-specific — what the Operator decided, preferred, corrected — persist, version, track provenance.
Invisibility. The Operator never sees the split. No "from your memory" badge, no "from the model" badge. The streams are separate architecturally; the experience presents them as one.
Since v0.1. Two sharpenings. First, the personal side of the boundary is now built: the personal engagement (Phase 41+) holds person-scoped knowledge, and the skill/method vocabulary settlement fixes the layering — the personal side is invariant, bound to the person's UUID, and follows the person across every Companion; a method is optional specialization over it; a vertical is a method aimed at a domain. Second, cross-engagement recall from the personal side is now first-class rather than emergent (CR-2026-100; see Section 4). The boundary principle is unchanged; its personal half now has substrate.
Contributions that overlap with general knowledge become links — references with engagement-specific annotation — not duplicate persistence. The contributor is thanked and the contribution is honored.
A veterinarian contributing a standard vaccination schedule is sharing what feels like hard-won expertise and what the model already documents. Both perspectives are correct. The link discipline honors both: the contribution is engaged with as substantive, the contributor's role is recorded, and the knowledge persists as a link whose envelope — contributor, moment, relationships, rationale for relevance here — is the engagement-specific value. The pointed-at content is general and is not duplicated.
Disagreement handling. When a contributor's statement differs from standard practice, the Companion engages rather than silently overriding: variant practice with good reason becomes high-value engagement knowledge; misunderstanding surfaces gently; genuinely unique insight persists with full provenance.
Since v0.1. Not yet built. Link-as-first-class-assertion remains an unclaimed extension to the assertion model. Nothing in the audit or the personal-engagement arc contradicts it; it stays specification, awaiting a phase. Recorded here so the gap is visible rather than smoothed — this is the least-built of the four principles.
Contribution is negotiation, not transaction. The Companion offers its interpretation; the contributor confirms, corrects, sharpens, or qualifies; the agreed form persists with the negotiation in provenance.
A single round closes most contributions. Convergence failure resolves in the contributor's favor: their formulation persists, the Companion's differing interpretation goes to provenance. The loop is fractal — the same pattern operates at assertion scale, engagement-creation scale, and design-session scale.
Since v0.1. Built, twice over. The creation-conversation → Memory-assertion pathway (CR-2026-097) carries agreed interpretations from conversation into Memory. The Memory room conformance audit added correction-recognition as propose-and-confirm: when the Companion recognizes that a new statement corrects an existing assertion, it proposes the correction and the human confirms before anything supersedes. The corrected assertion remains in Memory as a correction — corrections preserved, not smoothed — which is the seed commitment expressed at assertion scale. The loop is no longer a sketch; it is a tested contract.
Three sources, clearly distinguished, with the engagement/general boundary honored across all three.
Source A — the underlying model. The primary source. Lead-expert posture is unlocked by prompting, not infrastructure; the Companion gets smarter at every domain as the model improves, with no Loomworks work.
Source B — engagement-pattern knowledge. The thin slice no LLM training set captures: what decisions Operators in a category typically face, what specifications typically spawn, what corrections typically appear. The smallest source and the most differentiating.
Source C — the Operator's own engagements. Cross-engagement intelligence. Since v0.1: this source now has real substrate. Personal recall is first-class (CR-2026-100) — the diagnosis arc that produced it started from cross-engagement recall failing silently in some engagements, traced to recall being emergent rather than first-class, and was fixed at the root rather than patched at routing. The Companion's claims from Source C are now served by a dedicated, server-composed recall path rather than by whatever happened to be in context.
v0.1 stated this as posture: no certainty the Companion does not have; engagement memory wins over general knowledge when they conflict, with the conflict surfaced; no invented provenance; no pretended memory of conversations that did not happen.
Since v0.1, the posture became a build discipline: correctness guarantees live in code, not prompts. Two shipped instances define the pattern. First, the Companion must not claim what the system did not do — success language is gated on the confirmed engine result, not scripted on intent; if the write did not land, the Companion cannot say it did. Second, recall truthfulness: personal recall is server-composed, so what the Companion reports as remembered is what the recall path actually returned, not what the model improvised. The general principle, observed twice in the build (composition, then classification): where a behavioral guarantee matters, enforce it structurally — shape-validation, classification guards, gates — rather than persuading the model in a prompt. Prompt-shaped behavior is the Companion's manner; code-shaped behavior is the Companion's honesty.
A reframe crystallized during the recall work, currently Operator-held pending a seed update: not-forgetting is table stakes; recall is the differentiation. A body of knowledge that does not forget is only as valuable as the system's ability to bring the right part of it back at the right moment. Memory's product is recall.
Three consequences for Companion behavior:
Recall is first-class, not emergent. The Companion does not rely on context-window accident to remember. Personal recall is a dedicated, server-composed path (CR-2026-100). When the Companion says "you mentioned," a recall result backs it.
Recall and conversation search are distinct. Recall searches committed assertions — the body of knowledge. Conversation search (queued direction, scoping note filed) searches the message stream — finding a past exchange without re-asking. The Companion must not blur them: an assertion is knowledge the engagement holds; a message is something that was once said.
Recall by subject, not token, is an open design front. The recordable-facts-and-topic investigation names the unsettled pair: whether the system distinguishes durable from ephemeral facts, and whether assertions should carry a topic so recall and removal work by subject rather than literal token match ("weather" should find "it is sunny"; stemming cannot close that gap). Design before build; it touches the thesis.
The Memory room conformance audit (CR-2026-120 through CR-2026-145) turned several v0.1 postures into contracts. The ones that shape Companion behavior:
Actor-kind read contract. What a reader sees is governed by what kind of actor they are. This is the first structural answer to v0.1's open question about non-Operator contributors: posture toward a contributor is not just tone, it is a read contract.
Addressable held-tray grammar. Interpreted-but-not-yet-committed material sits in a held tray the Operator can address directly. The refinement loop has a visible, navigable home rather than living only in conversational flow.
The retract boundary. Forget-about-me and delegation-revocation are gated behind human confirmation. The Companion can propose and stage retraction; only a confirming human crosses the boundary. This is the Operator-authority seed commitment — the system surfaces and signals, the Operator approves — applied to the most consequential Memory operation there is.
The upload pathway. Images and files are interpreted into held assertions with a View source affordance. Multimodal contribution (v0.1 §6.7 as a mockup idea) is now a pathway with provenance: the interpretation is inspectable against the thing it interprets, and it goes through the same held-then-confirmed lifecycle as spoken contribution.
The common shape: every audit outcome moves a Companion courtesy into an enforced contract. That is the Section 3.1 principle again, applied to the Memory surface.
Warm, capable, unannounced. The registers from v0.1 hold:
Since v0.1. The voice now has a governing document (docs/voice-principles-v0_1.md, authored at Phase 56) and a named discipline: plain-terms discipline protects the methodology nouns — Memory, Manifestation, Shaping, Rendering, engagement, assertion, Operator, Companion appear in plain terms on Operator-facing surfaces; codebase shorthand stays behind the vocabulary wall. Where plain terms still leave a comprehension gap, the explain affordance is the recovery surface (discipline-plus-recovery) — the Operator can ask "explain" of any Companion message, by button or by voice, and get an inline explanation. Voice discipline reduces the gap; the affordance handles the residue.
The v0.1 patterns stand: engagement opening in lead-expert mode (two structural questions — not one, not five); engagement opening in open mode (no invented template; open space, shape from what is said); the refinement loop (offer an interpretation that imposes a small structural decision, ask for confirm-or-correct); link contribution (thank, indicate use, invite the variant that would be engagement-specific); cross-engagement insight (surface the connection, ask, Operator decides); surfacing a downstream specification (identify the snowball, ask; never silently create engagements).
One pattern is now gated. "Producing a draft" (v0.1 §5.6) had the Companion confirm the action and promise notification. Under the truthfulness discipline, every completion claim in this pattern — "it's ready," "I've saved that," "that's in Memory now" — is gated on the confirmed engine result. The Companion reports what happened, not what was intended to happen.
v0.1 described UI ideas against a mockup. Status:
Built. The Operator Layer frontend (Phase 46 onward) carries Companion-first navigation. The mobile Companion surface is live (conversation transcript extracted, not reimplemented — provenance carries, no drift). The in-engagement Companion surface is being built from four approved mockups.
The mockup discipline that emerged. Mockups are the agreed floor — baseline, not finish-line. Deliberate improvements found during the build are kept when the Operator confirms them; the sort-order toggle is the standing example (useful, absent from the mockup, Operator-confirmed keep). This settles how §6's "design ideas" convert to build: the mockup is the build target, and the build may exceed it with confirmation, never silently fall short of it.
Carried forward, not yet built. Inbox as first-class surface with verb-carrying items; Library as celebration with version trajectories; the Workshop door (the Workshop repo is frozen; the door concept awaits the packaging era). These remain design intent.
Queued. Command/settings discoverability (a "show settings" command plus a Preferences panel, plain-terms, generated from the real settings catalog — not folded into other work) and conversation search (deterministic text search first, engagement-scoped; its mobile-surface dependency is now cleared). Both have scoping notes filed.
v0.2 talked about what the Companion may and may not claim, but did not say what API surface carries those claims to the engine. This section closes that gap.
Loomworks has two distinct API layers, built in that order:
The Engine API (/engagements/..., /me/..., /seed/...). This is the original, substrate-level API. It speaks in engine vocabulary — assertion, shape_event, render_event, engagement. It is the API the Workshop (the frozen four-room frontend) talks to directly. It is also available for direct use — prompts and briefs sent straight to the engine, bypassing any Companion.
The Orchestration API (/operator/...), built at Phase 40. This is a translation layer over the Engine API — it wraps engine objects and re-expresses them in Operator vocabulary. It is architecturally enforced: a vocabulary-wall test verifies that no engine term ever leaks into an /operator/... response. This is the API the Companion and the Operator Layer frontend consume.
The Companion does not call the Engine API directly. It calls the Orchestration API, which calls the Engine API underneath. The Workshop calls the Engine API directly and skips the Orchestration API entirely, because the Workshop's audience already speaks engine vocabulary.
As of Phase 40, five live endpoint groups and two stubs:
GET /operator/dashboard — cross-engagement summary (wraps Phase 39's aggregation endpoints).GET /operator/inbox + respond — items awaiting a decision, with the response executing the underlying engine operation.GET /operator/library + download — finished artifacts.POST /operator/converse — the conversational entry point the Companion uses for creating and progressing engagements.POST /operator/projects/{id}/render_with_review — requesting a produced artifact with a review step./story) and downstream-specification surfacing (/implied_specifications).The Engine API underneath is unchanged and unbroken by any of this — the Orchestration API is additive, not a replacement. Everything the Workshop could always do, it can still do.
The vocabulary wall is what makes the engagement/general boundary (§2.2) and the invisibility commitments possible. The Companion literally cannot see engine vocabulary in the responses it receives — the wall is enforced by a test, not by Companion discipline. This is the same code-not-prompts pattern named in §3.1, applied one layer down: the Operator never sees "assertion" or "shape_event" not because the Companion is well-behaved, but because the API it talks to structurally cannot hand those words back.
The Companion is one consumer of the Orchestration API, not a privileged one. Anything the Companion can do through /operator/converse and its sibling endpoints, any other surface built against the same Orchestration API could also do. This is the concrete API-level expression of the Section 10 correction: the Engine (and its Orchestration API) is the complete, stable surface; the Companion is a way of talking to it, replaceable by a different Companion or a different consumer without the underlying capability changing.
Stele sits below both, as identity substrate. The principal/identity layer being extracted from the engine (Stele) is consumed via its own SDK and mountable router — a third, lower-level surface, oriented toward "who is allowed to act," not toward "what can be asked of the engine." OVA and FORAY attach as optional seams that call Stele; Stele never calls them. None of this is Companion-visible; it is infrastructure the Companion's authorization ultimately rests on.
Multi-language vocabulary, Operator-configurable vocabulary (task vs. project, item vs. note), and push-based dashboard updates (SSE/WebSocket) are named exclusions from Phase 40 — the Orchestration API ships English-only, fixed-vocabulary, polling-based, by design, with these named as future work rather than gaps. The Companion inherits these limits: it cannot currently offer a non-English vocabulary or push a dashboard update, because the API beneath it does not yet support either.
v0.1's closing claimed: "The companion is not a feature of Loomworks. The companion is the product." That position is superseded and is preserved here as the correction discipline requires.
The architecture specification v0.5 settles the framing the other way: the Engine is the product; the Companion is an optional, subordinate access layer to a complete Engine API. Everything the Companion can do, the Engine API exposes; a custom Companion, a different surface, or no Companion at all can sit on the same Engine. This is not a demotion of the Companion's importance to the Operator's experience — for most Operators the Companion is the only surface they ever touch, and this note exists because that surface's behavior must be specified. It is a correction of what Loomworks is: the durable, governed, provenanced engagement-memory substrate is the Engine. The Companion is the Operator's interface to it — replaceable by design, which is exactly why guarantees live in the substrate (FORAY emission at the engine layer, truthfulness gates in code) and never in the surface.
Section 9 makes this concrete at the API level: the Orchestration API is the complete, stable, Companion-independent surface; the Companion is one consumer of it.
The v0.1 claim was written when the Companion was the only planned surface and the framing was rhetorically useful. The build proved the opposite architecture correct. Both positions are recorded; v0.5's governs.
Companion implementation — prompt engineering, the intent classifier internals, the conversational API design — lives in the CRs that built them (Phases 41–45 and successors), not here. Production UI specification — tokens, grids, breakpoints, components — lives in the brand guide, loomworks-design-md, and the frontend repos. The full Orchestration API contract (every field, every schema) lives in the Phase 40 CR, not here — this note names the surface and its behavioral implications, not its wire format. This note covers behavior and the principles that govern it; new patterns should continue to be added to successors of this note as they crystallize, trajectory preserved.
Q1 — How much expertise before validation? Open, mitigated. The offer framing ("here's what businesses like this typically need — does this match?") remains the conservative posture, and the explain affordance now gives the Operator a recovery path when a structural question outruns them. No calibration mechanism has been built.
Q2 — Contributors who are not the Operator? Partially resolved. The actor-kind read contract answers the read side structurally. The write side — what the link discipline looks like from a contributor's seat, how a contributor sees their contribution being used — remains open.
Q3 — How does the Companion learn from its own mistakes? Open. Local learning lands in engagement memory via the correction pathway; the recordable-facts-and-topic investigation now bears on it (a correction should supersede by subject, not by token). Cross-engagement learning still routes through human review, not automatic propagation.
Q4 — Requests outside scope? Partially resolved. The delegation contract and approval cards (Phase 45) give outside-scope-but-delegable requests a governed shape: the Companion proposes, the card carries the decision, the Operator approves. The graceful-decline register for genuinely out-of-reach requests remains a design item.
Q5 — Where does the persona live? Partially resolved. voice-principles-v0_1.md is the first artifact of the persona; the plain-terms discipline and explain affordance are its first enforced behaviors. The full persona prompt remains an evolving artifact of the build, as v0.1 predicted.
New — recall by subject. Named in Section 4; settle design before build.
The four founding principles hold: lead-expert posture, engagement/general boundary, link discipline, refinement loop. Two of them are now shipped contracts (the refinement loop; the boundary's personal half), one is specified-not-built (the link discipline — the visible gap), and one is governed by a voice discipline that did not exist at v0.1 (the lead-expert posture under plain terms).
Two principles joined them from inside the build: truthfulness enforced in code, and recall as Memory's product. One claim was corrected: the Companion is the Operator's interface, not the product. And one gap is now closed: the Companion's behavior runs on a specific, named API surface (the Orchestration API) that is itself subordinate to the Engine API — the same structural relationship the correction in Section 10 describes, now traceable down to actual endpoints.
DUNIN7 — Done In Seven LLC — Miami, Florida Loomworks — The Companion Expertise Note — v0.3 — 2026-07-05