# 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`](../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](#reconciling-the-promise-with-the-tiering-the-code-encodes)
  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 `DomainLaunchPermission`s, 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:

| Domain  | `availability` | Registry line     | Launch-enabled? |
| ------- | -------------- | ----------------- | --------------- |
| Tara    | `active`       | `registry.ts:166` | Yes             |
| Veritas | `active`       | `registry.ts:225` | Yes             |
| Arete   | `active`       | `registry.ts:355` | Yes             |
| Nyx     | `beta`         | `registry.ts:290` | Yes (beta)      |
| Nisaba  | `beta`         | `registry.ts:420` | Yes (beta)      |
| Metis   | `planned`      | `registry.ts:489` | **No**          |

`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](./glossary.md) 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](./glossary.md) — fixed vocabulary for every domain,
  substrate, support lib, and surface named here.
- [High-Level Architecture](./high-level-architecture.md) — the runtime/package
  diagram the promise sits atop.
- [Customer-Facing Domains](./customer-domains.md) — how Tara, Arete, Veritas,
  Nyx, Nisaba, and Metis render.
- [Trust, Safety, and Privacy](./trust-safety-and-privacy.md) — how grounding,
  memory, and consent visibility are surfaced.
- [Content, Localization, Documentation, and Launch Readiness](./content-localization-and-launch.md)
  — the verification, gates, and rollback the launch promise requires.
- [../ARCHITECTURE.md](../ARCHITECTURE.md) — the architecture hub.