The Companion is the pleasant way to use Loomworks. It is not Loomworks. The Engine — the substrate that holds Memory, runs the four rooms, keeps provenance, and enforces the bound at the API — is the product and the authority. The Companion is one caller among possible callers, subordinate to the Engine, and it can never do anything the raw Engine API cannot do; it only makes the API pleasant to use. That single rule governs this entire specification.
The Companion is one thing with one behavioral contract — gather, confirm, submit to Memory, organize and arrange, produce, deliver — described along two independent axes. Scope is how wide its view is: one engagement, a named group, or your whole working set. Driver is who is at the controls: a present human, or an authorized agent acting on your behalf. Every behaviour in this specification is stated as a binding of the contract, and every contract point carries both its scope binding and its driver binding.
Today the Companion is built for one corner of that space: a present human, scoped to one engagement per turn, in conversation. This specification describes that built corner exactly as it is — including the fact that the confirm-before-commit card lives in the notifications Inbox, not in the conversation — and specifies the rest as the target the build reaches in stages.
This specification does not re-decide the architecture. The foundation note v0.2 settled it; this section restates only what every later section binds to, so the specification stands on its own. Where the foundation note and the architecture specification v0.4 differ, the foundation note governs (§1.3).
The Engine is elevated; the Companion is subordinate. The Engine holds the disciplines, the provenance, and the bound at the API. It governs every caller equally and can only ever know a caller's identity, its authorized reach, and the nature of each action it takes. The Companion is one kind of caller. It feeds the Engine (submits to Memory) and leverages what the Engine does (initiates Manifestation, Shaping, Rendering; reads what the Engine knows). Its entire behavioral surface is bounded by what the Engine's API and provenance permit.
From this axiom comes the hard rule that governs the whole specification:
The Companion never does anything the raw API cannot. It only makes the API pleasant.
Every capability described below is a capability the Engine API already exposes (or, for prescriptive sections, will expose) to any caller. The Companion adds conversation, voice, persona, confirmation, and proactivity on top of API operations — it never adds reach. If a section ever seems to grant the Companion a power the API does not have, that section is wrong, not the rule.
The Companion has operational agency — it does things, including things the Operator did not ask for in the moment (proactive surfacing) — but never sovereign agency. It has no will of its own. Every action traces to authority the Operator granted, exercised within what the Engine permits any caller to do.
Whatever the scope and whatever the driver, the Companion performs one behavioral sequence. The axes are bindings of this template; they do not change it.
Three disciplines bind the whole sequence, inherited from settled commitments and not re-litigated here:
The architecture specification v0.4 §02 and §08 predate the foundation note's sharpening and carry two framings this specification does not adopt. Recorded here so the Discovery trail shows the specification was written on the sharpened framing, and so the residue (a future v0.5 touch-up to the architecture specification) is visible.
Where architecture specification v0.4 adds operational detail the foundation note does not contradict — the intent taxonomy, engagement context loading, the standing-versus-engaged distinction, the delegation-contract fields — this specification carries that detail as the built description, grounded against code in the sections below.
Every contract point in §§4–9 names its scope binding and its driver binding. This section defines the two axes once.
Scope is how wide the Companion's view is: a selection over the Loomworks engagement space. It is a range, not a switch.
Trajectory (set aside): the axis began modeled as a binary — personal scope versus engagement scope. The executive-coach case broke it (a scope wider than one engagement, narrower than the whole personal world, with no home in the binary). The named-group band was promoted to first-class and scope became a range, grounded in the fact that the addressing primitives already exist.
The two registers. Engagement identity has two handles; the Companion uses the right one for the context:
E4729). The same value for everyone. The register for anything that must mean the same thing beyond you: external reference, shared documents, cross-person disambiguation, any multi-party engagement.Rule the specification carries: the Companion uses the personal register for the Operator's own navigation and the universal register whenever a reference must hold beyond the Operator. The scope range runs on the personal register; the universal register is what lets scope ever reach beyond you, and is the identity layer any future multi-party work stands on (that future remains gated).
Identity is a number, not a fixed width. The engagement identity is a monotonic integer; the E-number is a presentation that zero-pads to four digits today. This specification uses "E-number" / "engagement identifier" structurally and E#### only as illustrative presentation; it does not bake the four-digit width into anything load-bearing. (A planned refactor collapses the display identifier into the per-Operator sequence and renders the prefix at the surface.)
Driver is who is at the controls. It is a genuine second axis, independent of scope and independent of autonomy.
What driver governs: presence (whether a responsive human can be asked when something is genuinely ambiguous), medium (a human reads UI; an agent parses protocol — a difference in kind, not frequency), and identity (a human is the Operator with nothing to prove; an agent is a distinct identity that must prove it is authorized to act for the person without being that person).
What driver does not govern: autonomy. How much the Companion does without checking is a separate setting on the delegation contract — per_action (always waits) versus pre_authorized (acts and reports).
Trajectory (set aside): the skeptical view held that driver is not an axis at all, merely where the autonomy dial sits (human = always per_action; agent = always pre_authorized). Set aside by the crossing test: a human can be pre_authorized ("just do the small things, don't ask me") and an agent can be per_action (queues a card and waits for your return). Both crossed cases are real and useful; because driver and autonomy cross freely, they are independent dimensions.
The two axes are independent, so any combination is a real position. Four corners make the model concrete:
The named-group scope and the autonomy dial add further real positions between these corners.
Because the Companion is an access path and not the system, the Operator may bypass it. Operator-direct is a first-class posture: the Operator is the actor, with no Companion delegation in between, calling Engine operations directly. The Companion-mediated posture (Companion proposes; Operator commits) and the Operator-direct posture are both first-class. This is the concrete meaning of "optional access layer": remove the Companion and the Engine still works, because the Engine is the product. Nothing in this specification may make the Companion a required path to any Engine capability.
The specification is descriptive where code exists and prescriptive where it does not. This section is the map; later sections carry the detail and repeat the marking inline.
Built today (descriptive sections). A signed-in human Operator, scoped to exactly one engagement per turn (the engagement UUID resolved on the frontend before the Engine is called), drives the Companion conversationally through POST /operator/converse. The Engine classifies the turn against an intent taxonomy, loads engagement and personal-memory and recent-history context, assembles a persona-grounded prompt, and either answers, performs an engine-internal operation, tunes a personal setting, or proposes an action that — under the delegation contract — executes immediately (pre_authorized) or becomes an approval card. The Companion is attributed as a distinct companion-kind actor bound to the person's UUID. Every write is held-then-commit with provenance; Operator-final-authority is intact. The confirm loop runs end to end.
Target, not yet built (prescriptive sections), each tied to its foundation-note flag:
agent-kind actor is unreachable through conversation. (Foundation note §4.4: agent binding is specified-ahead-of-build.)converse is UUID-bound and single-engagement. "Open E4729," "is this also in engagement 23?", "move this to my commons" are unbuilt. The addressing primitives and a resolver exist as substrate, but converse does not call the resolver; engagement switching is a surface act (the frontend changes the URL), not a Companion act. (Foundation note §3.5: net-new wiring of an existing-but-unused primitive.)Scope binding. One engagement (built): each turn carries one engagement identifier. Named-group and whole-working-set gathering are target (§3). Driver binding. Human (built): conversational input, text or voice. Agent: structured input (§9).
The Operator's turn enters through POST /operator/converse (authenticated by session cookie; get_current_person). The request carries the message, the engagement's project identifier (null only on the first project-creating turn), an optional intent hint that skips classification, and an input mode (text or voice, defaulting to text).
The Engine assembles context for the turn: the engagement's seed and recent Memory, recent conversation turns, and — when both an engagement and the Operator's personal engagement are in play — personal Memory. Context loading is bounded by engagement boundaries: the engagement's own scope plus the Operator's personal scope, by default. This is the gather step reading what it needs to understand the turn; it adds no reach the API would not grant the same caller.
Voice turns differ in two built ways: they carry an input_mode provenance marker, and they receive a server-side completeness pre-check — if a voice turn is incomplete, the Engine composes a clarifying reply rather than proceeding. Text turns are treated as deliberate.
At named-group or whole-working-set scope, gather reads across the addressed set on the personal register (and the universal register where a reference must hold beyond the Operator). At the agent driver, gather takes the agent's structured input rather than a conversational turn. Both are bindings of the same step; neither grants reach beyond what the API permits the caller.
This is the load-bearing checkpoint, and the place where built reality and the foundation note's phrasing must be reconciled carefully.
Scope binding. Independent of scope — confirmation is per-proposed-action, whatever the view's width. Driver binding. This is where driver bites hardest: the presence of confirmation is invariant; the medium changes (human card vs agent structured response).
Before anything becomes durable, the Companion surfaces what it understood. The Operator commits; the Companion does not commit on the Operator's behalf except within an explicit standing delegation. This is Operator-final-authority expressed at the moment of action.
The conversation surface and the confirmation channel are two separate channels today. This is the single most important built-reality fact in the specification, and it is stated plainly rather than smoothed.
converse.pre_authorized, the action executes now and an informational notification is written; under per_action, an approval card is created and a real-time notification_created signal is published. The Companion's reply narrates the proposal.So the confirm-before-commit checkpoint is built and works end to end, but the "card you read and tap" is today a notifications-Inbox interaction, not an in-conversation one.
The foundation note §4.1 frames the human medium as "confirmation binds to a screen — a card you read and tap," presented as built. The card is built and is read-and-tapped — in the Inbox. The note's phrasing implies the conversation surface; the code places it in the notifications channel. Neither is wrong about the mechanism; they differ on where the tap happens.
Resolution (no architecture change needed): the in-Inbox card is the built confirmation medium and is described as such (§5.2). The target is in-conversation confirmation cards — the card appearing inline in the conversation where the proposal was made — which is prescriptive. The mechanism (propose → authorize-at-approval → dispatch → record) is unchanged; only the surface of the tap moves from Inbox to conversation. This is a frontend convergence item, not an Engine change, and it composes with the two-surface convergence (§10).
The autonomy setting and the dispatch record are different things and use layered vocabulary, settled by judgment: per_action / pre_authorized describe the contract's standing rule (the dial); explicit is the dispatch record of an individually-approved action (what the Companion actor reference carries when a card is approved). The specification keeps these distinct.
At the agent driver, confirmation binds to a structured response the agent can act on, or a deferred card queued for the Operator's return. A present human can be asked in the moment; an absent agent cannot, and must defer, decide within bounds, or abort. Defining the checkpoint abstractly here (human card-binding, agent protocol-binding) is what makes the agent path a clean future build rather than a retrofit (§9).
Scope binding. One engagement (built); the write lands in the addressed engagement's Memory, plus the personal engagement for remember-about-me writes. Driver binding. Human (built) and agent (target) both write through the same mechanics; attribution differs by actor kind.
The Companion writes to the Engine through the same assertion mechanics any caller uses. Writes are held-then-commit: a new contribution enters the held state, attributable to a contributor, awaiting Operator commit. Before commit, retraction is silent (the assertion never existed); after commit, retraction is governance-bearing (the trail shows existence, contribution, retraction). Supersession preserves the prior assertion alongside the new one — trajectory preserved, never smoothed.
The Companion is attributed as a distinct actor of kind companion, with its identifier bound to the person's UUID — there is no separate companions table and no second identity. Its display name is the Operator's chosen Companion name. An Operator turn is attributed as kind person. This is the provenance discipline made concrete: a contribution the Companion made is marked as the Companion's, attributed and origin-tied, never disguised as the Operator's and never inventing a source.
Built write-bearing operations the Companion performs through conversation include: creating, finalizing, and committing a project draft; adding knowledge to the engagement; remembering and forgetting personal facts (the personal-Memory writes, which land in the personal engagement); and saving a filter. Each is an Engine operation the API exposes; the Companion adds the conversational route, not the capability.
Remember-about-me and forget-about-me are built personal-Memory operations. They write to the Operator's personal engagement, the substrate that lets personal context carry across the Operator's other engagements. This is the content facet of personal scope (§8.1), partly built.
An agent's writes use the same held-then-commit mechanics and the same provenance discipline, attributed to an agent-kind actor carrying its OVA authorization. The agent actor kind exists in the actor model but is unreachable through conversation today (§9). External action logs and the delegation contract itself are recorded as assertions, keeping the Companion's actions inside the same Memory discipline as everything else.
These four steps (template steps 4–6, plus delivery) are the Companion leveraging what the Engine does. The Companion initiates; the Engine performs; the artifact is the Engine's, produced under the rooms' discipline.
Scope binding. One engagement (built) for the operations below; cross-scope composition in Shaping is an Engine capability the Companion initiates at the engagement scope today. Driver binding. Human (built); agent (target) initiates the same operations through structured dispatch.
The Companion initiates derivation of a Manifestation: Memory organized at a moment in time, a structured reading of the engagement's committed assertions against its seed. The Companion does not organize Memory itself — it asks the Engine to derive, and narrates the result. Prior Manifestations are preserved when Memory grows and the Operator re-derives.
The Companion initiates a Shaping: organized knowledge arranged for a specific reader, selecting and emphasizing and leaving out for an audience and purpose. The Shaping is grammar-indifferent — the grammar of the eventual artifact (Markdown, HTML, presentation, application code) is declared on the Shaping; production lives below in Rendering. Cross-scope composition (drawing several scopes' Manifestations together for a reader) is an Engine capability per the seed; the Companion initiates it where the work requires, bounded by what the API and the Operator's reach permit.
The Companion initiates Rendering, which produces either the artifact directly or the specification a downstream system consumes — the seed's two Rendering modes:
The Companion's role is to initiate and narrate; the render specialists and materializers produce. The Companion never produces an artifact the Rendering layer could not produce for any caller.
The Companion returns or routes the output: surfacing a produced artifact for the Operator to read or download through the Library, or routing it onward where the work calls for it. Built delivery includes finding and surfacing a download and reporting progress; the request-download and progress paths are built conversational operations.
When scope is at its widest — the personal / Standing posture — the Companion is yours, and "personal" carries four facets. All four are in-scope for this specification to define; they differ in build state.
The Companion holds Memory about you: your preferences, your history, what you have asked it to remember about yourself. Partly built: the invisible personal engagement (Phase 41) and the remember-about-me / forget-about-me paths (§6.2). This is the personal scope's content.
Personal recall — the read side (built, CR-2026-100). The personal scope now has a first-class recall capability. The Operator can ask the Companion to recall their personal memories — a person, a date, a preference, anything held about them and their world — from any engagement, and receive the same answer wherever they ask, because personal memory is person-scoped and reachable everywhere. Recall reads the complete set of the Operator's committed personal memories and the Companion composes the answer from them: leading with the specific fact for a specific question ("Lisa's birthday is April 12"), or giving a brief, warm account for a broad one ("what do you know about me"). The Companion speaks as someone who simply knows the Operator — it does not narrate that it is "checking personal memory," and it does not expose scope or engagement boundaries. If it holds nothing that answers, it says so plainly and offers to remember.
This makes personal recall reliable rather than emergent. Before CR-2026-100, recalling a personal fact depended on a turn happening to reach the responder, which read a personal-memory block from its prompt; a query that classified into a responder-bypassing intent (orientation) silently returned nothing, and the block was budget-clipped so older facts could drop. Personal recall is now its own routed, retrieval-backed capability that reads the personal store directly and wholesale — and a structural guard ensures a recall query can never land on the orientation bypass. The Operator's reasonable expectation — that the Companion recalls what they have told it, from anywhere — is now honoured by construction.
It is yours: a persistent, named presence with a consistent voice and a memory of your shared history, continuous across all your engagements and when no engagement is in focus. This is the personal scope's identity. Its canonical home is the standing-note / specification layer, not the seed — see §11 for the reasoning. The cross-engagement continuity (the Standing Companion recognizing that something said in one engagement might belong in another) is named in the architecture specification as planned, not yet a behavior; it is target here.
The Companion serves you, not only the work: managing your preferences, surfacing things proactively across your engagements, being your interface to the whole Loomworks system. This is the home the "Companion-as-Operator-system-interface" principle was reaching for. Partly built: the tune-setting handler (Phase 60) adjusts a small set of personal settings (backdrop blur, voice-listening thresholds, and other Companion settings) through conversation — the first instance of preferences-through-conversation rather than a settings UI. The principle generalizes; most of the function facet is target.
A built detail worth recording: the tune-setting turn is treated as a non-conversation intent — it is not recorded as a conversation turn, because it adjusts the Operator's environment rather than contributing to Memory. The setting change is returned to the surface, which applies it (and drops the optimistic turn for tune-setting).
The Companion specialized to you and your domain: a vertical solution that pairs an engagement shape with a domain-specialized Companion. This is the personal scope's customization, and it is target.
The agent driver is entirely absent from code: the Engine authenticates only a human session, there is no agent-driver path, OVA is not in code, and the agent actor kind is unreachable through conversation. This section is prescriptive throughout and specifies the architecture fully and confidently while deferring implementation detail to when the substrate exists — the resolution of the foundation note's first deferred decision.
OVA is the agent-authorization mechanism — named, in hand, planned for implementation, not speculative. An agent acting as the Companion is a distinct identity that must prove it is authorized to act for the Operator without being the Operator and without revealing more about the Operator than necessary. The agent carries a zero-knowledge authorization proof; the Engine verifies it; the proof discloses authorization without revealing the principal.
OVA's substrate is maturing on a tracked roadmap: Kaspa's zero-knowledge verification opcodes (live as of the Toccata hard fork) provide an on-chain verification substrate an OVA proof can anchor to; OVA's full functionality — authorization that composes synchronously with the operations it governs — wants synchronously-composable verifiable programs (vprogs), which is post-Toccata and not yet released. So OVA's horizon is: architecture specifiable now; verification substrate live now; full synchronous-composition functionality sequenced to vprogs. This is sequencing against a maturing dependency the Operator is actively tracking, not doubt about whether OVA happens.
What is specified now versus deferred. The agent binding's architecture is specified fully and confidently now: the contract binds both ways, the identity model is settled (the agent carries a ZK authorization proof; the Engine verifies it), and the absent-agent ambiguity policy is settled (an absent agent must defer, decide within bounds, or abort — never invent a human's answer). The implementation detail — the circuit, the handshake, the composition mechanics — is deferred to when the substrate (vprogs) exists, because pinning it now would be specifying against unbuilt, still-moving machinery.
OVA authorizes the agent (prevention, at the API); FORAY records what the agent did, with provenance (accountability). Together: OVA prevents the unauthorized; FORAY makes the authorized auditable and makes deviation visible after the fact. FORAY does not stop an action — that is OVA's job at the API; FORAY makes misbehaviour detectable and attributable, and patterns of it visible over time. This extends a role FORAY already plays (a setting change writes a FORAY audit row on every change); it is not a new mechanism.
Oversight is Operator-scoped, by construction. Because an agent is always Operator-bound — it acts for a specific Operator under that Operator's delegation, with the Companion identity bound to the person's UUID — the FORAY events an agent generates are that Operator's: in that Operator's engagements, attributable to that Operator's delegated agent. Agent oversight therefore collapses to the right scale: "is my agent staying within the delegation I granted?" is answerable entirely inside the Operator's own boundary, against the Operator's own FORAY trail and delegation contracts.
Trajectory (set aside): a dedicated privileged-watcher agent — a platform security-operations layer observing all activity — was considered and set aside. Such a watcher is by construction the most over-privileged caller in the system, the single largest least-privilege violation, and it imports a quis custodiet problem (who authorizes the watcher; what governs it). The correction that dissolved it: agents are Operator-bound, so the activity is already partitioned and attributable per Operator, and no cross-cutting watcher is needed. Oversight lives in the personal register (your agents, your trail, your bounds), not the universal register.
A possible shape worth remembering (not committed): Operator-scoped oversight could be Engine-intrinsic analysis of the FORAY ledger the Engine already writes, or a governed infrastructure engagement whose subject is the Operator's own activity stream — never a privileged watcher-agent. Either keeps least-privilege intact.
Parked: cross-boundary oversight for shared, multi-party engagements. An agent acting in an engagement two Operators share generates FORAY events touching more than one Operator's world, and there oversight does cross a boundary — but only the multi-party case, which is already gated. The open question, when that gate is approached: who is authorized to see across the boundary enough to detect misbehaviour, and what governs that authority. That is a FORAY-governance question larger than this specification, to be taken up with the multi-Operator decision.
The delegation contract is the architectural locus of Companion authority. It carries the scope of authority delegated, the duration, the operations included, the operations excluded (which require explicit approval), the autonomy rule (per_action versus pre_authorized), and the audit trail of operations performed under it. The contract is part of the engagement substrate and persists with the engagement. Default contracts are conservative; the Operator can read the contract, narrow it, or extend it per engagement. The contract is itself recorded as assertions — Memory, not a side table — keeping it inside the same discipline as the rest of the work.
The contract already governs the built human path: a proposing intent checks the contract, and pre_authorized executes-and-reports while per_action raises a card (§5.2). The same contract governs the agent path when it is built; this is the contract binding both ways that §9.1 specifies.
The agent Companion is the first entity to use all three DUNIN7 protocols at once: Loom (personal and engagement Memory are Loom assertion records), FORAY (every consequential agent action is a FORAY-structured transaction), and OVA (the agent's authority to act is an OVA credential). The protocols were designed to compose; the agent Companion is where they compose. This is recorded as the architectural reading, not a build commitment beyond what §§9.1–9.3 specify.
The Companion role requires a principal. Where no Operator principal exists — for example the Credit Management infrastructure engagement — the engagement runs without a Companion, and a system sentinel acts instead. This is a boundary condition of the role, recorded so the agent specification is not read as implying every engagement has a Companion.
The Companion is reached through conversation surfaces. Two exist today and they diverge; the specification names the convergence as target.
converse with the engagement's project identifier and the input mode, applies returned setting changes, and renders both roles as plain text (no Markdown). It renders no approval cards.So features are split across the two surfaces: pagination, ordering, and voice live on the primary surface; suggested actions, the draft-specification card, and the exhaustion dialog live on the legacy surface.
The two surfaces should converge to one full-featured conversation surface, and Companion turns should render Markdown (today only Operator turns do, and only on the legacy surface). In-conversation confirmation cards (§5.3) land as part of this convergence — the card moving from the Inbox to inline in the conversation. All three are frontend convergence items; none changes the Engine contract.
Authentication is the Engine's, governed by the seed: identity is the system-assigned UUID; authentication is by credentials the Operator controls (passkey, authenticator code, organizational SSO). Sign-in never requests email; sign-in never keys lookup by email; recovery never uses email-based reset. Email and mobile are user-maintained communication attributes, not identity. The Companion plays no part in establishing identity; it is reached only after a session exists. Recorded here because the Companion is the Operator's interface to the system, and the boundary between "interface to the system" and "establisher of identity" must stay clean.
The seed is silent on Companion identity, and that silence is settled and deliberate — the resolution of the foundation note's second deferred decision. Recorded here because a later reader may expect the seed to carry the Companion's identity commitments and read their absence as a soft spot. It is not.
The reasoning: the Companion is an optional access path, not part of the system (§1, §2.4). The seed is the Loomworks engagement seed — it governs what the system is committed to, and the system is the Engine. The Companion's identity commitments (named, persistent, yours; "you are talking to your Companion, not to an AI") are experience-design commitments about an optional access layer, and they are already canonical in their own layer — the Product Identity standing note, the Companion Expertise Note, the Phase 41 CR, which the architecture specification already points to.
"Not in the seed" is therefore not a demotion: the seed is silent on Companion identity, so there is nothing for it to supersede; the standing-note layer is the authority there. Two further reasons the seed is the wrong home: the Companion is cross-cutting (it appears in every engagement), so an engagement seed is a category-mismatched place for it; and this architecture is freshly designed and largely unbuilt, so seed-level commitment would be premature. The identity stays where it is — canonical in its layer, referenced by this specification.
Four tensions surfaced in grounding are resolved and stated here, not re-decided:
approval_mode vocabulary — layered (§5.4): per_action / pre_authorized describe the contract's standing rule; explicit is the dispatch record of an individually-approved action.Settled and specified. The founding axiom and the hard rule; the behavioral contract and its three disciplines; both axes as binding dimensions; Operator-direct as a first-class posture; the built human-binding loop (gather, confirm, submit, organize/arrange/produce, deliver) grounded against code with the confirm-in-Inbox reality stated plainly; the four personal facets with their build states; the agent driver's architecture (OVA identity, FORAY accountability, the delegation contract, the boundary condition) specified ahead of build; why identity is not in the seed.
Residues this specification opens or carries:
converse to the existing resolver so the Companion can scope, switch, and cross-reference engagements conversationally (§3, §2.1), intersecting the planned identifier refactor.