V1 Product Promise

The Product Promise is the contract V1 makes to everyone who touches it — customers, learners, readers, operators, creators, and the institutions that adopt Oshun as a tenant. It states what the product is (one coherent customer-admin-assistant-platform system, centered on Tara, spanning a set of customer-facing domains over a set of platform substrates) and, just as importantly, how it behaves when things go wrong. It sits at the very top of the V1 architecture: every surface, domain, substrate, and route described in the sibling pages exists to keep one of these promises. This page expands the promise from ../ARCHITECTURE.md and reconciles its framing language against what the code in libs/oshun/ actually encodes, because the honest version of the promise — including the domain tiering the prose used to flatten — is the version engineering has to ship.

What V1 promises#

Oshun V1 ships as a single coherent customer, admin, assistant, and platform product rather than a federation of disconnected domain apps. The customer experience is Tara-centered — Tara is the experiential and thematic spine, the room the shell opens into first — and it spans a set of customer-facing domains rendered through a shared consumer shell and a single backend-for-frontend. Beneath those domains, a set of platform substrates supply grounding, assistant memory, real-time runtime, contemplative safety, governed generation, and non-custodial payment settlement. Operator products run review, safety, support, privacy, persona/model/rights/provenance operations, incidents, and launch governance on top of the same substrates, so the thing operators administer and the thing customers experience are the same system.

Restated as the concrete commitments the product must keep, V1 should:

• Present Tara as the experiential and thematic center of the customer product. This is not just editorial framing — OSHUN_SHELL_PRIMARY_DOMAIN is literally 'tara' in libs/oshun/domain-registry/src/registry.ts, and the default shell configuration places Tara as primaryDomain with every other enabled domain as a companionDomain.
• Treat the other domains (Arete, Veritas, Nyx, Nisaba, and Metis) as Oshun domains that share the shell, design tokens, navigation, assistant, and BFF data — not bolt-on microsites. (The prose historically called these "first-class … with no tiering"; the code says otherwise, and the reconciliation below is part of the honest promise.)
• Preserve continuity across web, mobile, assistant, notifications, library, profile, and activity history — a session paused on web resumes on mobile; the assistant remembers what the customer was doing; activity history is one timeline, not six.
• Ground claims and high-stakes educational, research, and evidence-sensitive outputs through Sophia (@oshun/evidence-sophia), so that an answer carries its evidence pack and citation trail rather than asserting authority it cannot show.
• Make memory, consent, provenance, synthetic-media, and grounding state visible wherever they affect user trust — surfaced through Iris (@oshun/memory-iris) for memory/consent and through generation provenance for synthetic media.
• Provide operator-grade admin tooling for every launch-critical governance workflow — review, safety, support, privacy, persona/model/rights/provenance operations, incidents, and launch readiness.
• Provide first-class authoring, curation, editorial, asset, taxonomy, versioning, and localization tooling for creators, scholars, teachers, translators, and operators across every content domain — the Oshun Studio surface.
• Provide first-class agentic AI surfaces for content development, research, tutoring, education, and operations, with the full registry, orchestration, budget, kill-switch, audit, and feedback machinery that governs them.
• Treat institutions, schools, research labs, partner organizations, and managed cohorts as first-class tenants — isolated admin, identity provisioning (SSO/SCIM), audit, integrations, and lifecycle communications — strictly separated from operator-only Oshun Admin.
• Support premium personas, voices, avatars, generated media, and educational assets only through governed approval paths — never by ungoverned generation reaching a customer.
• Degrade safely under subsystem outages, weak grounding, partial responses, provider failures, offline states, and interrupted sessions.
• Launch only with automated verification, observability, runbooks, release gates, rollback plans, and post-deploy monitoring in place.

The full prose list lives in the companion V1/features.md feature map under "V1 Product Promise"; this page is the architecture-side reading of it.

The promise is a degradation contract, not a happy path#

The single load-bearing sentence in the promise is the one about safe degradation. Every claim V1 makes to a customer must survive subsystem outages, weak grounding, partial responses, provider failures, offline states, and interrupted sessions. That is what makes the promise an architectural commitment rather than a marketing line: it dictates how every surface and substrate has to fail.

In practice the promise is honored through machinery the registry already encodes per domain. Each domain in DOMAIN_REGISTRY carries an offlineFallback card (DomainOfflineFallbackCard — title, body, cta, secondaryCta, cacheHint) so that an offline or degraded domain shows a calm, domain-specific fallback rather than a spinner or a stack trace. Each domain also carries a launchContract (DomainLaunchContract — icon, label, cta, and a list of DomainLaunchPermissions, each marked required or optional with a rationale) so the shell can explain, before launch, exactly what a domain needs and why. The shell also proceeds gracefully when an optional permission is declined.

The degradation contract is what forces, downstream:

• Grounding-state visibility — when Sophia returns weak or partial evidence, the customer sees that the answer is weakly grounded rather than being handed false confidence.
• Memory/consent visibility — Iris exposes what is remembered, lets it be exported or deleted, and suppresses what consent does not cover; a memory outage degrades to "no memory," never to "wrong memory."
• Real-time recovery — Psyche's session envelope, turn-taking, and reconnect logic mean an interrupted voice/avatar session resumes rather than restarts.
• Governed-generation failover — Isis's release gates, failover, and rollback mean a failing provider degrades to a fallback path, not to an ungoverned one.

Reconciling the promise with the tiering the code encodes#

The prose around the promise historically said V1 "treats all six domains … as co-equal first-class Oshun domains with no tiering." The code does encode a tiering, and the honest promise has to acknowledge it. libs/oshun/domain-registry/src/registry.ts defines DomainAvailability = 'active' | 'beta' | 'planned' and assigns each domain a real status:

getAvailableDomains() (registry.ts:503) filters out every domain whose availability === 'planned', so the canonical launch configuration is five domains, not six: getDefaultShellDomainConfiguration() returns enabledDomains: ['tara', 'veritas', 'nyx', 'arete', 'nisaba'] with primaryDomain: 'tara', companionDomains: ['veritas', 'nyx', 'arete', 'nisaba'], and betaDomains: ['nyx', 'nisaba']. Metis is deliberately kept visible in shell navigation — getShellNavigationDomains() returns all six (['tara', 'veritas', 'nyx', 'arete', 'nisaba', 'metis']) — but it is not enabled for launch. The registry test pins exactly this distinction: index.test.ts:103 asserts the registry "exposes planned Metis in shell navigation without enabling it for launch configuration," and the companion test (index.test.ts:96) asserts getAvailableDomains() excludes Metis (some(item.id === 'metis') is false).

This means the product-doc framing of Metis as "launch-blocking V1 scope" is in genuine tension with the code's availability: 'planned'. Both can be true if read precisely: Metis is a committed V1 domain (it has the most developed dedicated stack of any domain; see Subsystem Glossary and the apps/metis/ and libs/metis/ trees), but its registry status says it is not yet launch-enabled and is excluded from the default shell domain configuration. The promise V1 actually keeps is therefore: Tara, Veritas, and Arete ship active; Nyx and Nisaba ship beta; Metis ships visible-but-planned. When this page or the glossary says "first-class," read it as "shares the shell, BFF, design system, and assistant" — not as "all at the same availability tier."

Where the promise is enforced in code#

The promise is not aspirational prose floating above the system; it has concrete enforcement points:

• Domain identity and tiering — libs/oshun/domain-registry/src/registry.ts is the single source of truth for which domains exist (OSHUN_DOMAIN_IDS), their availability, their auth policy (DomainAuthPolicy — required, sessionKind, scopes, stepUpActions), their per-domain analytics-id, notification-channel, assistant-context-key, deep-link-prefix, and admin taxonomy.
• Single coherent backend — apps/oshun/bff/src/app.ts mounts registerDomainsRoutes plus per-domain registrars (registerTaraRoutes, registerAreteRoutes, registerNisabaRoutes, etc.) so the "one product" promise is literally one Fastify app, not six.
• Grounding — @oshun/evidence-sophia is the V1-consumed adapter over the sprawling libs/sophia/ substrate; it is the seam where "ground claims through Sophia" becomes a call.
• Memory and consent — @oshun/memory-iris is the adapter over libs/iris/.
• Governed generation — @oshun/generation-control-isis over libs/isis/.
• Non-custodial settlement — @oshun/payments-bridge over the libs/aje/ Web3 monorepo, keeping the "premium only through governed paths" and "non-custodial settlement" promises.

Each of these is documented in its own substrate page; the promise simply names the behavior they collectively guarantee.

Why it works this way#

V1's premise is that a contemplative, evidence-grounded, multi-domain product earns trust through consistency and candor, not feature count. Centering Tara gives the product a single emotional and navigational anchor so customers are never dropped into "utility clutter" (the registry's own shellNarrative language). Routing every domain through one shell and one BFF makes continuity, analytics, notifications, and the assistant structurally coherent rather than coordinated by convention. Encoding availability as data (active/beta/planned) rather than as prose lets the product ship honestly — a planned domain stays visible to set expectations without being pushed into the launch contract before it is ready. And making degradation a top-level promise forces every substrate to define its failure mode up front, which is the only way "every claim must degrade safely" can be more than a slogan.

Related#

• Subsystem Glossary — fixed vocabulary for every domain, substrate, support lib, and surface named here.
• High-Level Architecture — the runtime/package diagram the promise sits atop.
• Customer-Facing Domains — how Tara, Arete, Veritas, Nyx, Nisaba, and Metis render.
• Trust, Safety, and Privacy — how grounding, memory, and consent visibility are surfaced.
• Content, Localization, Documentation, and Launch Readiness — the verification, gates, and rollback the launch promise requires.
• ../ARCHITECTURE.md — the architecture hub.