> ## Documentation Index
> Fetch the complete documentation index at: https://helloluciallc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lucia Decision Log

<Note>
  This log records meaningful product, architecture, and launch decisions so Lucia remembers why it has its current shape.
</Note>

***

## 2026-07-12 — Keep Engine and Guest Agent model configuration independent

**Decision:** Lucia Engine and Lucia Guest Agent own separate model-configuration and runtime-verification boundaries. A model value verified for one surface must not be inherited, inferred, or presented as proof for the other.

**Current state:** Both surfaces currently use `gpt-5.6-sol`. The Guest Agent selects its model through its own `VV_AI_MODEL` production override and source fallback; Lucia Engine retains its separately owned configuration and runtime-provenance contract.

**Verification policy:** Each surface requires its own deployed configuration and provider-returned model evidence. Shared use of the OpenAI Responses API does not collapse the two runtime boundaries.

**Compatibility consequence:** Guest Agent model upgrades must preserve its prompts, verification flow, routing, schemas, and core SSE event contract (`start`, `token`, `cta`, `meta`, `done`) unless a separately authorized change says otherwise. Its embeddings model remains independently configured as `text-embedding-3-small`.

**Historical continuity:** The dated 2026-06-04 Guest Agent GPT-5.5 doctrine record and 2026-04-26 Lucia GPT-5.5 decision remain historical evidence. This decision supersedes the former Guest Agent GPT-5.5 default for current configuration without rewriting those entries.

***

## 2026-07-10 — Require runtime provenance for model verification

**Decision:** Treat runtime/model provenance from the same `/admin/operator-focus` response as the evidence contract for Eval Labs model verification. Preserve the stable top-level `ok / data / meta` shape; publish Engine identity in `meta.runtime` and model-path evidence in `meta.model_runtime`.

**Required evidence:** The contract records the configured model, provider-resolved model, whether a model was invoked, whether the response was deterministic-only, whether fallback was used, and per-task outcomes. A successful HTTP response or configured model name alone is not proof that a model ran.

**Eval Labs policy:** The owner-only verification panel evaluates the resolved endpoint, target and Engine environments, Engine commit SHA, configured/resolved model agreement, model invocation, deterministic path, fallback state, successful task evidence, and verification timestamp. New runs persist `runtimeProvenance`; historical runs without it explicitly say it was not captured and are not backfilled with inference.

**Current verified state:** On 2026-07-10, Eval Labs production verified the Development `/admin/operator-focus` path with configured and provider-resolved model `gpt-5.6-sol`, model invoked `true`, deterministic path `false`, fallback `false`, and status `Verified`.

**Routing history:** The uninterrupted Staging-target configuration began at `2026-05-04T16:21:35Z` and was corrected and live-verified against Development on 2026-07-10. This establishes routing drift, not that every historical run individually used Staging.

**Supersession:** The 2026-04-26 GPT-5.5 decision below remains historical. GPT-5.6 Sol is now the Lucia Engine Development default. This decision does not establish the separately configured Guest Agent model.

**Promotion consequence:** Eval Labs production targeting Development is not a Staging promotion. The Development baseline must still be captured and reviewed before v0.1.3.6 is promoted.

***

## 2026-06-23 — Unify docs into a Mintlify library

**Decision:** Migrate both documentation sets (Lucia Canon and Eval Labs Canon) off Obsidian Publish onto a single Mintlify library — two products with a switcher — served at `helloluciallc.com`, with `docs.hellolucia.ai` and `docs.evaluationlabs.ai` redirecting in. New repo `hello-lucia/lucia-library` becomes the source of truth for published docs.

**Why:** A unified library splits and groups the content better and presents both brands as one home. Mintlify's Products feature fits directly; founder accepted leaving the Obsidian authoring workflow for git/MDX.

**Status:** Accepted; implementation in progress (Phase 1 conversion complete and pushed, not yet deployed/live).

**Historical status note — 2026-07-10:** The two-product and redirect language above records the original decision intent. The current canonical library has three products — Lucia, Lucia Fieldwork, and Eval Labs — and the two former Obsidian domains remain live legacy, non-canonical sites without redirects. The amended ADR below owns current documentation status.

**See:** [ADR - Unify Docs into Mintlify Library](/lucia/decisions/adr-unify-docs-into-mintlify-library)

***

## 2026-05-11 — Use Resend for waitlist outbound email

**Decision:** Use Resend for Lucia waitlist outbound welcome emails, while keeping Postmark focused on inbound operational/system email intake.

**Why:** Resend is lightweight, already available, easy to operate, and better suited to this specific public waitlist confirmation path than a heavier marketing platform.

**Implementation:** The `hello-lucia/lucia-marketing` Cloudflare Pages Function at `functions/api/waitlist.js` now sends the welcome email after a new Supabase waitlist insert succeeds.

**Verified behavior:** `send.hellolucia.ai` is verified in Resend, live new-signup email delivery passed, and duplicate signup behavior returns `ok:true duplicate:true` without sending a second email.

**Known gap:** The endpoint returns Resend message id/status, but message id and send status are not yet persisted back into Supabase.

***

## 2026-04-29 — Add Branding and Identity as a Canon section

**Decision:** Add a dedicated `Branding and Identity` section to the Lucia Canon.

**Why:** Lucia’s visual identity, color system, voice, and brand guardrails are now first-class source-truth concerns, not side notes.

**Consequence:** Brand work should be documented in the Canon and treated as connected to product trust, operator calm, and emotional containment.

***

## 2026-04-27 — Adopt Canon v1.0 architecture

**Decision:** Restructure the Lucia Canon around the real system: Foundation, System Architecture, Intelligence, Evaluation, Operations, Infrastructure, Properties, Roadmap, Decisions, Releases, Templates, and Archives.

**Why:** The previous structure mixed doctrine, runtime, intent, Eval Labs, and live transition notes across overlapping folders.

**Consequence:** Old folders are moved into Archives. The new Canon becomes the source of truth.

***

## 2026-04-27 — Treat Lucia as a dual-surface intelligence system

**Decision:** Lucia is canonically defined as a dual-surface system.

<div className="hl-flow"><span>Operator Intelligence</span><span>controls</span><span>Guest Intelligence</span></div>

**Why:** The Operator System is the control layer today, while Guest Intelligence and concierge flows are downstream execution surfaces.

**Consequence:** Guest-facing work must not bypass operator truth-state and permission rules.

***

## 2026-04-27 — Development is active external intake during live transition

**Decision:** Twilio and Postmark target `api-dev.hellolucia.ai` during current live-transition testing.

**Why:** Dev is the active iteration environment. Staging validates promoted code but does not receive live provider traffic unless manually switched.

**Consequence:** Staging tests require temporary provider webhook changes or smoke tests.

***

## 2026-04-27 — Defer Postmark attachment rendering

**Decision:** Email attachment rendering is deferred until a Postmark API retrieval path is implemented.

**Why:** Current webhook payloads provide email body and attachment metadata but not reliable binary attachment content.

**Consequence:** Email body and metadata are usable now; images are supported through SMS/MMS and WhatsApp.

***

## 2026-04-27 — Bunny is required for provider media rendering

**Decision:** Maintenance media should render through Bunny CDN, not provider URLs.

**Why:** Twilio media URLs require authentication and break in browser rendering.

**Consequence:** Provider media must be fetched server-side, uploaded to Bunny Storage, and rendered from Bunny CDN.

***

## 2026-04-26 — Upgrade toward GPT-5.5 and Responses API

**Decision:** Lucia should move toward GPT-5.5 and the Responses API for model-assisted text paths.

**Why:** The model layer needs a controlled upgrade path and stronger reasoning for the intent layer and operator OS.

**Consequence:** Model upgrades must not break response contract, truth-state discipline, or operator calm.